001/**
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package com.github.commonsrdf.api;
015
016import java.util.stream.Stream;
017
018/**
019 * An <a href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph"> RDF 1.1
020 * Graph</a>, a set of RDF triples, as defined by <a
021 * href="http://www.w3.org/TR/rdf11-concepts/" >RDF-1.1 Concepts and Abstract
022 * Syntax</a>, a W3C Recommendation published on 25 February 2014.
023 */
024public interface Graph {
025
026    /**
027     * Add a triple to the graph.
028     *
029     * @param triple
030     *            The triple to add
031     */
032    void add(Triple triple);
033
034    /**
035     * Add a triple to the graph.
036     *
037     * @param subject
038     *            The triple subject
039     * @param predicate
040     *            The triple predicate
041     * @param object
042     *            The triple object
043     */
044    void add(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
045
046    /**
047     * Check if graph contains triple.
048     *
049     * @param triple
050     *            The triple to check.
051     * @return True if the Graph contains the given Triple.
052     */
053    boolean contains(Triple triple);
054
055    /**
056     * Check if graph contains a pattern of triples.
057     *
058     * @param subject
059     *            The triple subject (null is a wildcard)
060     * @param predicate
061     *            The triple predicate (null is a wildcard)
062     * @param object
063     *            The triple object (null is a wildcard)
064     * @return True if the Graph contains any Triples that match
065     *            the given pattern.
066     */
067    boolean contains(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
068
069    /**
070     * Remove a concrete triple from the graph.
071     *
072     * @param triple
073     *            triple to remove
074     */
075    void remove(Triple triple);
076
077    /**
078     * Remove a concrete pattern of triples from the graph.
079     *
080     * @param subject
081     *            The triple subject (null is a wildcard)
082     * @param predicate
083     *            The triple predicate (null is a wildcard)
084     * @param object
085     *            The triple object (null is a wildcard)
086     */
087    void remove(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
088
089    /**
090     * Clear the graph.
091     */
092    void clear();
093
094    /**
095     * Number of triples contained by the graph.
096     *
097     * @return The size of the graph.
098     */
099    long size();
100
101    /**
102     * Get all triples contained by the graph.<br>
103     *
104     * The behaviour of the Stream is not specified if add, remove, or clear,
105     * are called on the Stream before it terminates.<br>
106     *
107     * Implementations may throw ConcurrentModificationException from Stream
108     * methods if they detect a conflict while the Stream is active.
109     *
110     * @return A {@link Stream} over all of the triples in the graph.
111     */
112    Stream<? extends Triple> getTriples();
113
114    /**
115     * Get all triples contained by the graph matched with the pattern.
116     *
117     * The behaviour of the Stream is not specified if add, remove, or clear,
118     * are called on the Stream before it terminates.<br>
119     *
120     * Implementations may throw ConcurrentModificationException from Stream
121     * methods if they detect a conflict while the Stream is active.
122     *
123     * @param subject
124     *            The triple subject (null is a wildcard)
125     * @param predicate
126     *            The triple predicate (null is a wildcard)
127     * @param object
128     *            The triple object (null is a wildcard)
129     * @return A {@link Stream} over the matched triples.
130     */
131    Stream<? extends Triple> getTriples(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
132
133}