001/*
002 * (C) Copyright 2006-2019 Nuxeo (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
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    void setDescription(GraphDescription graphDescription);
043
044    /**
045     * Returns namespaces for the graph.
046     * <p>
047     * Namespaces are prefix/namespace bindings, as rdf for http://www.w3.org/1999/02/22-rdf-syntax-ns#.
048     *
049     * @return namespaces map of namespace bindings for the graph
050     */
051    Map<String, String> getNamespaces();
052
053    /**
054     * Adds the statement object to the graph.
055     *
056     * @param statement statement to add
057     * @since 5.5
058     */
059    void add(Statement statement);
060
061    /**
062     * Adds given list of Statement objects to the graph.
063     *
064     * @param statements list of Statement instances to add
065     */
066    void add(List<Statement> statements);
067
068    /**
069     * Removes the statement object from the graph.
070     *
071     * @param statement statement to remove
072     * @since 5.5
073     */
074    void remove(Statement statement);
075
076    /**
077     * Removes given list of Statement objects from the graph.
078     *
079     * @param statements List of Statement instances to remove
080     */
081    void remove(List<Statement> statements);
082
083    /**
084     * Returns all statements in the graph.
085     *
086     * @return list of Statement instances
087     */
088    List<Statement> getStatements();
089
090    /**
091     * Returns all statements in the graph matching the pattern.
092     *
093     * @param statement pattern to match, can hold null nodes as wildcards
094     * @return list of Statement instances matching the pattern
095     */
096    List<Statement> getStatements(Statement statement);
097
098    /**
099     * Returns all statements in the graph matching the pattern.
100     *
101     * @return list of Statement instances matching the pattern
102     * @since 5.5
103     */
104    List<Statement> getStatements(Node subject, Node predicate, Node object);
105
106    /**
107     * Get items matching the statement pattern (null, predicate, object).
108     *
109     * @param predicate predicate pattern, null accepted
110     * @param object object pattern, null accepted
111     * @return list of subjects
112     */
113    List<Node> getSubjects(Node predicate, Node object);
114
115    /**
116     * Gets items matching the statement pattern (subject, null, object).
117     *
118     * @param subject subject pattern, null accepted
119     * @param object object pattern, null accepted
120     * @return list of predicates
121     */
122    List<Node> getPredicates(Node subject, Node object);
123
124    /**
125     * Gets items matching the statement pattern (subject, predicate, null).
126     *
127     * @param subject subject pattern, null accepted
128     * @param predicate predicate pattern, null accepted
129     * @return list of node objects
130     */
131    List<Node> getObjects(Node subject, Node predicate);
132
133    /**
134     * Returns true if given statement pattern is in the graph.
135     *
136     * @param statement statement pattern, can use null as wild cards
137     * @return true or false
138     */
139    boolean hasStatement(Statement statement);
140
141    /**
142     * Returns true if given resource appears in any statement of the graph.
143     *
144     * @return true or false
145     */
146    boolean hasResource(Resource resource);
147
148    /**
149     * Returns the number of statements in the graph.
150     *
151     * @return number of statements as a Long
152     */
153    Long size();
154
155    /**
156     * Clears the graph, removing all statements in it.
157     */
158    void clear();
159
160    /**
161     * Query the graph using a base URI.
162     *
163     * @param queryString the query string
164     * @param language the query language (sparql, rdql,...)
165     * @param baseURI the base URI to use for query
166     * @return QueryResult instance
167     */
168    QueryResult query(String queryString, String language, String baseURI);
169
170    /**
171     * Counts the number of results of a query.
172     *
173     * @param queryString the query string
174     * @param language the query language (sparql, rdql,...)
175     * @param baseURI the base URI to use for query
176     * @return the count
177     */
178    int queryCount(String queryString, String language, String baseURI);
179
180    // I/O
181
182    /**
183     * Parses source into the graph.
184     *
185     * @param path path on file system where to take the serialization file
186     * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The
187     *            default value, represented by null, is "RDF/XML".
188     * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows
189     *            relative uris to be used in the model.
190     * @return true on success, else false
191     */
192    boolean read(String path, String lang, String base);
193
194    /**
195     * Parses source into the graph.
196     *
197     * @param in input stream
198     * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The
199     *            default value, represented by null, is "RDF/XML".
200     * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows
201     *            relative uris to be used in the model.
202     * @return true on success, else false
203     */
204    boolean read(InputStream in, String lang, String base);
205
206    /**
207     * Serializes graph.
208     *
209     * @param path path on file system where to put the serialization file
210     * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The
211     *            default value, represented by null, is "RDF/XML".
212     * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows
213     *            relative uris to be used in the model.
214     * @return true on success, else false
215     */
216    boolean write(String path, String lang, String base);
217
218    /**
219     * Serializes graph.
220     *
221     * @param out output stream
222     * @param lang format for the input serialization, may be "RDF/XML", "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The
223     *            default value, represented by null, is "RDF/XML".
224     * @param base base uri to be used when converting relative uris to absolute uris, may be null. If set to "", allows
225     *            relative uris to be used in the model.
226     * @return true on success, else false
227     */
228    boolean write(OutputStream out, String lang, String base);
229
230}