org.apache.commons.rdf.api.Dataset Maven / Gradle / Ivy
Show all versions of commons-rdf-api Show documentation
/**
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.rdf.api;
import java.util.ConcurrentModificationException;
import java.util.Iterator;
import java.util.Optional;
import java.util.stream.Stream;
/**
* An RDF
* 1.1 Dataset, a set of RDF quads, as defined by
* RDF-1.1 Concepts and Abstract
* Syntax, a W3C Recommendation published on 25 February 2014.
*
* @since 0.3.0-incubating
* @see RDF#createDataset()
*/
public interface Dataset extends AutoCloseable, GraphLike {
/**
* Add a quad to the dataset, possibly mapping any of the components of the
* Quad to those supported by this dataset.
*
* @param quad
* The quad to add
*/
@Override
void add(Quad quad);
/**
* Add a quad to the dataset, possibly mapping any of the components to
* those supported by this dataset.
*
* @param graphName
* The graph the quad belongs to, or null for the
* default graph
* @param subject
* The quad subject
* @param predicate
* The quad predicate
* @param object
* The quad object
*/
void add(BlankNodeOrIRI graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
/**
* Check if dataset contains quad.
*
* @param quad
* The quad to check.
* @return True if the dataset contains the given Quad.
*/
@Override
boolean contains(Quad quad);
/**
* Check if dataset contains a pattern of quads.
*
* @param graphName
* The graph the quad belongs to, wrapped as an {@link Optional}
* (null is a wildcard, {@link Optional#empty()} is
* the default graph)
* @param subject
* The quad subject (null is a wildcard)
* @param predicate
* The quad predicate (null is a wildcard)
* @param object
* The quad object (null is a wildcard)
* @return True if the dataset contains any quads that match the given
* pattern.
*/
boolean contains(Optional graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
/**
* Close the dataset, relinquishing any underlying resources.
*
* For example, this would close any open file and network streams and free
* database locks held by the dataset implementation.
*
* The behaviour of the other dataset methods are undefined after closing
* the dataset.
*
* Implementations might not need {@link #close()}, hence the default
* implementation does nothing.
*/
@Override
default void close() throws Exception {
}
/**
* Get the default graph of this dataset.
*
* The {@link Triple}s of the default graph are equivalent to the
* {@link Quad}s in this Dataset which has the {@link Quad#getGraphName()}
* set to {@link Optional#empty()}.
*
* It is unspecified if modifications to the returned Graph are reflected in
* this Dataset.
*
* The returned graph MAY be empty.
*
* @see #getGraph(BlankNodeOrIRI)
* @return The default graph of this Dataset
*/
Graph getGraph();
/**
* Get a named graph in this dataset.
*
* The {@link Triple}s of the named graph are equivalent to the the Quads of
* this Dataset which has the {@link Quad#getGraphName()} equal to the
* provided graphName, or equal to {@link Optional#empty()} if
* the provided graphName is null.
*
* It is unspecified if modifications to the returned Graph are reflected in
* this Dataset.
*
* It is unspecified if requesting an unknown or empty graph will return
* {@link Optional#empty()} or create a new empty {@link Graph}.
*
* @see #getGraph()
* @see #getGraphNames()
* @param graphName
* The name of the graph, or null for the default
* graph.
* @return The named Graph, or {@link Optional#empty()} if the dataset do
* not contain the named graph.
*/
Optional getGraph(BlankNodeOrIRI graphName);
/**
* Get the graph names in this Dataset.
*
* The set of returned graph names is equivalent to the set of unique
* {@link Quad#getGraphName()} of all the {@link #stream()} of this dataset
* (excluding the default graph).
*
* The returned {@link Stream} SHOULD NOT contain duplicate graph names.
*
* The graph names can be used with {@link #getGraph(BlankNodeOrIRI)} to
* retrieve the corresponding {@link Graph}, however callers should be aware
* of any concurrent modifications to the Dataset may cause such calls to
* return {@link Optional#empty()}.
*
* Note that a Dataset always contains a default graph
* which is not named, and thus is not represented in the returned Stream.
* The default graph is accessible via {@link #getGraph()} or by using
* {@link Optional#empty()} in the Quad access methods).
*
* @return A {@link Stream} of the graph names of this Dataset.
*/
Stream getGraphNames();
/**
* Remove a concrete quad from the dataset.
*
* @param quad
* quad to remove
*/
@Override
void remove(Quad quad);
/**
* Remove a concrete pattern of quads from the default graph of the dataset.
*
* @param graphName
* The graph the quad belongs to, wrapped as an {@link Optional}
* (null is a wildcard, {@link Optional#empty()} is
* the default graph)
* @param subject
* The quad subject (null is a wildcard)
* @param predicate
* The quad predicate (null is a wildcard)
* @param object
* The quad object (null is a wildcard)
*/
void remove(Optional graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
/**
* Clear the dataset, removing all quads.
*/
@Override
void clear();
/**
* Number of quads contained by the dataset.
*
* The count of a set does not include duplicates, consistent with the
* {@link Quad#equals(Object)} equals method for each {@link Quad}.
*
* @return The number of quads in the dataset
*/
@Override
long size();
/**
* Get all quads contained by the dataset.
*
* The iteration does not contain any duplicate quads, as determined by the
* {@link Quad#equals(Object)} method for each {@link Quad}.
*
* The behaviour of the {@link Stream} is not specified if
* {@link #add(Quad)}, {@link #remove(Quad)} or {@link #clear()} are called
* on the {@link Dataset} before it terminates.
*
* Implementations may throw {@link ConcurrentModificationException} from
* Stream methods if they detect a conflict while the Stream is active.
*
* @return A {@link Stream} over all of the quads in the dataset
*/
@Override
Stream stream();
/**
* Get all quads contained by the dataset matched with the pattern.
*
* The iteration does not contain any duplicate quads, as determined by the
* {@link Quad#equals(Object)} method for each {@link Quad}.
*
* The behaviour of the {@link Stream} is not specified if
* {@link #add(Quad)}, {@link #remove(Quad)} or {@link #clear()} are called
* on the {@link Dataset} before it terminates.
*
* Implementations may throw {@link ConcurrentModificationException} from
* Stream methods if they detect a conflict while the Stream is active.
*
* @param graphName
* The graph the quad belongs to, wrapped as an {@link Optional}
* (null is a wildcard, {@link Optional#empty()} is
* the default graph)
* @param subject
* The quad subject (null is a wildcard)
* @param predicate
* The quad predicate (null is a wildcard)
* @param object
* The quad object (null is a wildcard)
* @return A {@link Stream} over the matched quads.
*/
Stream stream(Optional graphName, BlankNodeOrIRI subject, IRI predicate,
RDFTerm object);
/**
* Get an Iterable for iterating over all quads in the dataset.
*
* This method is meant to be used with a Java for-each loop, e.g.:
*
*
* for (Quad t : dataset.iterate()) {
* System.out.println(t);
* }
*
*
* The behaviour of the iterator is not specified if {@link #add(Quad)},
* {@link #remove(Quad)} or {@link #clear()}, are called on the
* {@link Dataset} before it terminates. It is undefined if the returned
* {@link Iterator} supports the {@link Iterator#remove()} method.
*
* Implementations may throw {@link ConcurrentModificationException} from
* Iterator methods if they detect a concurrency conflict while the Iterator
* is active.
*
* The {@link Iterable#iterator()} must only be called once, that is the
* Iterable must only be iterated over once. A {@link IllegalStateException}
* may be thrown on attempt to reuse the Iterable.
*
* The default implementation of this method will call {@link #stream()} to
* return its {@link Stream#iterator()}.
*
* @return A {@link Iterable} that returns {@link Iterator} over all of the
* quads in the dataset
* @throws IllegalStateException
* if the {@link Iterable} has been reused
* @throws ConcurrentModificationException
* if a concurrency conflict occurs while the Iterator is
* active.
*/
@Override
@SuppressWarnings("unchecked")
default Iterable iterate() throws ConcurrentModificationException, IllegalStateException {
return ((Stream) stream())::iterator;
}
/**
* Get an Iterable for iterating over the quads in the dataset that match
* the pattern.
*
* This method is meant to be used with a Java for-each loop, e.g.:
*
*
* IRI alice = factory.createIRI("http://example.com/alice");
* IRI knows = factory.createIRI("http://xmlns.com/foaf/0.1/");
* for (Quad t : dataset.iterate(null, alice, knows, null)) {
* System.out.println(t.getGraphName());
* System.out.println(t.getObject());
* }
*
*
* The behaviour of the iterator is not specified if {@link #add(Quad)},
* {@link #remove(Quad)} or {@link #clear()}, are called on the
* {@link Dataset} before it terminates. It is undefined if the returned
* {@link Iterator} supports the {@link Iterator#remove()} method.
*
* Implementations may throw {@link ConcurrentModificationException} from
* Iterator methods if they detect a concurrency conflict while the Iterator
* is active.
*
* The {@link Iterable#iterator()} must only be called once, that is the
* Iterable must only be iterated over once. A {@link IllegalStateException}
* may be thrown on attempt to reuse the Iterable.
*
* The default implementation of this method will call
* {@link #stream(Optional, BlankNodeOrIRI, IRI, RDFTerm)} to return its
* {@link Stream#iterator()}.
*
* @param graphName
* The graph the quad belongs to, wrapped as an {@link Optional}
* (null is a wildcard, {@link Optional#empty()} is
* the default graph)
* @param subject
* The quad subject (null is a wildcard)
* @param predicate
* The quad predicate (null is a wildcard)
* @param object
* The quad object (null is a wildcard)
* @return A {@link Iterable} that returns {@link Iterator} over the
* matching quads in the dataset
* @throws IllegalStateException
* if the {@link Iterable} has been reused
* @throws ConcurrentModificationException
* if a concurrency conflict occurs while the Iterator is
* active.
*/
@SuppressWarnings("unchecked")
default Iterable iterate(final Optional graphName, final BlankNodeOrIRI subject, final IRI predicate,
final RDFTerm object) throws ConcurrentModificationException, IllegalStateException {
return ((Stream) stream(graphName, subject, predicate, object))::iterator;
}
}