001/*
002 * (C) Copyright 2006-2007 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Nuxeo - initial API and implementation
016 *
017 * $Id: Graph.java 25079 2007-09-18 14:49:05Z atchertchian $
018 */
019
020package org.nuxeo.ecm.platform.relations.api;
021
022import java.io.InputStream;
023import java.io.OutputStream;
024import java.io.Serializable;
025import java.util.List;
026import java.util.Map;
027
028/**
029 * Interface for graphs.
030 * <p>
031 * New types of graphs will be registered using extension points.
032 * <p>
033 * Graphs have to be serializable has they will be kept as references in the RelationService bean.
034 *
035 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
036 */
037public interface Graph extends Serializable {
038
039    /**
040     * Sets the graph description.
041     *
042     * @param graphDescription
043     */
044    void setDescription(GraphDescription graphDescription);
045
046    /**
047     * Returns namespaces for the graph.
048     * <p>
049     * Namespaces are prefix/namespace bindings, as rdf for http://www.w3.org/1999/02/22-rdf-syntax-ns#.
050     *
051     * @returns namespaces map of namespace bindings for the graph
052     */
053    Map<String, String> getNamespaces();
054
055    /**
056     * Adds the statement object to the graph.
057     *
058     * @param statement statement to add
059     * @since 5.5
060     */
061    void add(Statement statement);
062
063    /**
064     * Adds given list of Statement objects to the graph.
065     *
066     * @param statements list of Statement instances to add
067     */
068    void add(List<Statement> statements);
069
070    /**
071     * Removes the statement object from the graph.
072     *
073     * @param statement statement to remove
074     * @since 5.5
075     */
076    void remove(Statement statement);
077
078    /**
079     * Removes given list of Statement objects from the graph.
080     *
081     * @param statements List of Statement instances to remove
082     */
083    void remove(List<Statement> statements);
084
085    /**
086     * Returns all statements in the graph.
087     *
088     * @return list of Statement instances
089     */
090    List<Statement> getStatements();
091
092    /**
093     * Returns all statements in the graph matching the pattern.
094     *
095     * @param statement pattern to match, can hold null nodes as wildcards
096     * @return list of Statement instances matching the pattern
097     */
098    List<Statement> getStatements(Statement statement);
099
100    /**
101     * Returns all statements in the graph matching the pattern.
102     *
103     * @param statement pattern to match, can hold null nodes as wildcards
104     * @return list of Statement instances matching the pattern
105     * @since 5.5
106     */
107    List<Statement> getStatements(Node subject, Node predicate, Node object);
108
109    /**
110     * Get items matching the statement pattern (null, predicate, object).
111     *
112     * @param predicate predicate pattern, null accepted
113     * @param object object pattern, null accepted
114     * @return list of subjects
115     */
116    List<Node> getSubjects(Node predicate, Node object);
117
118    /**
119     * Gets items matching the statement pattern (subject, null, object).
120     *
121     * @param subject subject pattern, null accepted
122     * @param object object pattern, null accepted
123     * @return list of predicates
124     */
125    List<Node> getPredicates(Node subject, Node object);
126
127    /**
128     * Gets items matching the statement pattern (subject, predicate, null).
129     *
130     * @param subject subject pattern, null accepted
131     * @param predicate predicate pattern, null accepted
132     * @return list of node objects
133     */
134    List<Node> getObjects(Node subject, Node predicate);
135
136    /**
137     * Returns true if given statement pattern is in the graph.
138     *
139     * @param statement statement pattern, can use null as wild cards
140     * @return true or false
141     */
142    boolean hasStatement(Statement statement);
143
144    /**
145     * Returns true if given resource appears in any statement of the graph.
146     *
147     * @param resource
148     * @return true or false
149     */
150    boolean hasResource(Resource resource);
151
152    /**
153     * Returns the number of statements in the graph.
154     *
155     * @return number of statements as a Long
156     */
157    Long size();
158
159    /**
160     * Clears the graph, removing all statements in it.
161     */
162    void clear();
163
164    /**
165     * Query the graph using a base URI.
166     *
167     * @param queryString the query string
168     * @param language the query language (sparql, rdql,...)
169     * @param baseURI the base URI to use for query
170     * @return QueryResult instance
171     */
172    QueryResult query(String queryString, String language, String baseURI);
173
174    /**
175     * Counts the number of results of a query.
176     *
177     * @param queryString the query string
178     * @param language the query language (sparql, rdql,...)
179     * @param baseURI the base URI to use for query
180     * @return the count
181     */
182    int queryCount(String queryString, String language, String baseURI);
183
184    // I/O
185
186    /**
187     * Parses source into the graph.
188     *
189     * @param path path on file system where to take the serialization file
190     * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The
191     *            default value, represented by null, is "RDF/XML".
192     * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows
193     *            relative uris to be used in the model.
194     * @return true on success, else false
195     */
196    boolean read(String path, String lang, String base);
197
198    /**
199     * Parses source into the graph.
200     *
201     * @param in input stream
202     * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The
203     *            default value, represented by null, is "RDF/XML".
204     * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows
205     *            relative uris to be used in the model.
206     * @return true on success, else false
207     */
208    boolean read(InputStream in, String lang, String base);
209
210    /**
211     * Serializes graph.
212     *
213     * @param path path on file system where to put the serialization file
214     * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The
215     *            default value, represented by null, is "RDF/XML".
216     * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows
217     *            relative uris to be used in the model.
218     * @return true on success, else false
219     */
220    boolean write(String path, String lang, String base);
221
222    /**
223     * Serializes graph.
224     *
225     * @param out output stream
226     * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The
227     *            default value, represented by null, is "RDF/XML".
228     * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows
229     *            relative uris to be used in the model.
230     * @return true on success, else false
231     */
232    boolean write(OutputStream out, String lang, String base);
233
234}