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