/* * Copyright Aduna (http://www.aduna-software.com/) (c) 2007-2008. * * Licensed under the Aduna BSD-style license. */ package org.openrdf.model; import java.io.Serializable; import java.util.Map; import java.util.Set; import org.openrdf.OpenRDFUtil; import org.openrdf.model.util.ModelException; /** * An RDF model, represented as a set of {@link Statement}s with predictable * iteration order. * * @author James Leigh */ public interface Model extends Set, Serializable { /** * Gets the map that contains the assigned namespaces. * * @return Map of prefix to namespace */ public Map getNamespaces(); /** * Gets the namespace that is associated with the specified prefix, if any. * * @param prefix * A namespace prefix. * @return The namespace name that is associated with the specified prefix, * or null if there is no such namespace. */ public String getNamespace(String prefix); /** * Sets the prefix for a namespace. * * @param prefix * The new prefix. * @param name * The namespace name that the prefix maps to. */ public String setNamespace(String prefix, String name); /** * Removes a namespace declaration by removing the association between a * prefix and a namespace name. * * @param prefix * The namespace prefix of which the assocation with a namespace name * is to be removed. */ public void removeNamespace(String prefix); /** * Gets the base URI which can be used when outputting the model, * e.g. in HTML templates. * * @return The base URI or null if none has been set. */ public String getBaseURI(); /** * Sets the base URI which can be used when outputting the model, * e.g. in HTML templates. * * @param baseURI The base URI to be set. */ public void setBaseURI(String baseURI); /** * Gets the resource that this model is mainly about. * This provides a starting point for traversing the graph. * * @return The resource of interest or null if none has been set. */ public URI getResourceOfInterest(); /** * Sets the resource that this model is mainly about. * This provides a starting point for traversing the graph. * * @param resourceOfInterest The resource of interest to be set. */ public void setResourceOfInterest(URI resourceOfInterest); /** * Determines if statements with the specified subject, predicate, object and * (optionally) context exist in this model. The subject, * predicate and object parameters can be null to * indicate wildcards. The contexts parameter is a wildcard and * accepts zero or more values. If no contexts are specified, statements will * match disregarding their context. If one or more contexts are specified, * statements with a context matching one of these will match. Note: to match * statements without an associated context, specify the value null * and explicitly cast it to type Resource. *

* Examples: model.contains(s1, null, null) is true if any * statements in this model have subject s1,
* model.contains(null, null, null, c1) is true if any statements in * this model have context c1,
* model.contains(null, null, null, (Resource)null) is true if any * statements in this model have no associated context,
* model.contains(null, null, null, c1, c2, c3) is true if any * statements in this model have context c1, c2 or * c3. * * @param subj * The subject of the statements to match, null to match * statements with any subject. * @param pred * The predicate of the statements to match, null to match * statements with any predicate. * @param obj * The object of the statements to match, null to match * statements with any object. * @param contexts * The contexts of the statements to match. If no contexts are * specified, statements will match disregarding their context. If one * or more contexts are specified, statements with a context matching * one of these will match. * @return true if statements match the specified pattern. * @throws IllegalArgumentException * If a null-array is specified as the value for * contexts. See * {@link OpenRDFUtil#verifyContextNotNull(Resource[])} for more * info. */ public boolean contains(Resource subj, URI pred, Value obj, Resource... contexts); /** * Adds one or more statements to the model. This method creates a statement * for each specified context and adds those to the model. If no contexts are * specified, a single statement with no associated context is added. If this * Model is a filtered Model then null (if context empty) values are * permitted and will used the corresponding filtered values. * * @param subj * The statement's subject. * @param pred * The statement's predicate. * @param obj * The statement's object. * @param contexts * The contexts to add statements to. * @throws IllegalArgumentException * If This Model cannot store the given statement, because it is * filtered out of this view. * @throws UnsupportedOperationException * If this Model cannot accept any statements, because it is filter * to the empty set. */ public boolean add(Resource subj, URI pred, Value obj, Resource... contexts); /** * Merges the specified model into this one by adding all its statements * to this model's statements, adding all its namespace mappings (overriding * existing ones) and setting properties from the other model if this one * didn't have them set yet. * * @param other The model to be merged into this one. Remains unchanged. */ public void addAll(Model other); /** * Removes statements with the specified context exist in this model. * * @param context * The context of the statements to remove. * @return true if one or more statements have been removed. * @throws IllegalArgumentException * If a null-array is specified as the value for * contexts. See * {@link OpenRDFUtil#verifyContextNotNull(Resource[])} for more * info. */ public boolean clear(Resource... context); /** * Removes statements with the specified subject, predicate, object and * (optionally) context exist in this model. The subject, * predicate and object parameters can be null to * indicate wildcards. The contexts parameter is a wildcard and * accepts zero or more values. If no contexts are specified, statements will * be removed disregarding their context. If one or more contexts are * specified, statements with a context matching one of these will be * removed. Note: to remove statements without an associated context, specify * the value null and explicitly cast it to type Resource. *

* Examples: model.remove(s1, null, null) removes any statements in * this model have subject s1,
* model.remove(null, null, null, c1) removes any statements in this * model have context c1,
* model.remove(null, null, null, (Resource)null) removes any * statements in this model have no associated context,
* model.remove(null, null, null, c1, c2, c3) removes any statements * in this model have context c1, c2 or c3. * * @param subj * The subject of the statements to remove, null to remove * statements with any subject. * @param pred * The predicate of the statements to remove, null to remove * statements with any predicate. * @param obj * The object of the statements to remove, null to remove * statements with any object. * @param contexts * The contexts of the statements to remove. If no contexts are * specified, statements will be removed disregarding their context. * If one or more contexts are specified, statements with a context * matching one of these will be removed. * @return true if one or more statements have been removed. * @throws IllegalArgumentException * If a null-array is specified as the value for * contexts. See * {@link OpenRDFUtil#verifyContextNotNull(Resource[])} for more * info. */ public boolean remove(Resource subj, URI pred, Value obj, Resource... contexts); // Views /** * Returns a view of the statements with the specified subject, predicate, * object and (optionally) context. The subject, predicate * and object parameters can be null to indicate wildcards. * The contexts parameter is a wildcard and accepts zero or more * values. If no contexts are specified, statements will match disregarding * their context. If one or more contexts are specified, statements with a * context matching one of these will match. Note: to match statements * without an associated context, specify the value null and * explicitly cast it to type Resource. *

* The returned model is backed by this Model, so changes to this Model are * reflected in the returned model, and vice-versa. If this Model is modified * while an iteration over the returned model is in progress (except through * the iterator's own remove operation), the results of the * iteration are undefined. The model supports element removal, which removes * the corresponding statement from this Model, via the * Iterator.remove, Set.remove, removeAll, * retainAll, and clear operations. The statements passed * to the add and addAll operations must match the * parameter pattern. *

* Examples: model.filter(s1, null, null) matches all statements * that have subject s1,
* model.filter(null, null, null, c1) matches all statements that * have context c1,
* model.filter(null, null, null, (Resource)null) matches all * statements that have no associated context,
* model.filter(null, null, null, c1, c2, c3) matches all statements * that have context c1, c2 or c3. * * @param subj * The subject of the statements to match, null to match * statements with any subject. * @param pred * The predicate of the statements to match, null to match * statements with any predicate. * @param obj * The object of the statements to match, null to match * statements with any object. * @param contexts * The contexts of the statements to match. If no contexts are * specified, statements will match disregarding their context. If one * or more contexts are specified, statements with a context matching * one of these will match. * @return The statements that match the specified pattern. * @throws IllegalArgumentException * If a null-array is specified as the value for * contexts. See * {@link OpenRDFUtil#verifyContextNotNull(Resource[])} for more * info. */ public Model filter(Resource subj, URI pred, Value obj, Resource... contexts); /** * Returns a {@link Set} view of the subjects contained in this model. The * set is backed by the model, so changes to the model are reflected in the * set, and vice-versa. If the model is modified while an iteration over the * set is in progress (except through the iterator's own remove * operation), the results of the iteration are undefined. The set supports * element removal, which removes the corresponding statement from the model, * via the Iterator.remove, Set.remove, removeAll, * retainAll, and clear operations. It does not support the * add or addAll operations if the parameters pred * or obj are null. * * @return a set view of the subjects contained in this model */ public Set subjects(); /** * Returns a {@link Set} view of the predicates contained in this model. The * set is backed by the model, so changes to the model are reflected in the * set, and vice-versa. If the model is modified while an iteration over the * set is in progress (except through the iterator's own remove * operation), the results of the iteration are undefined. The set supports * element removal, which removes the corresponding statement from the model, * via the Iterator.remove, Set.remove, removeAll, * retainAll, and clear operations. It does not support the * add or addAll operations if the parameters subj * or obj are null. * * @return a set view of the predicates contained in this model */ public Set predicates(); /** * Returns a {@link Set} view of the objects contained in this model. The set * is backed by the model, so changes to the model are reflected in the set, * and vice-versa. If the model is modified while an iteration over the set * is in progress (except through the iterator's own remove * operation), the results of the iteration are undefined. The set supports * element removal, which removes the corresponding statement from the model, * via the Iterator.remove, Set.remove, removeAll, * retainAll, and clear operations. It does not support the * add or addAll operations if the parameters subj * or pred are null. * * @return a set view of the objects contained in this model */ public Set objects(); /** * Returns a {@link Set} view of the contexts contained in this model. The * set is backed by the model, so changes to the model are reflected in the * set, and vice-versa. If the model is modified while an iteration over the * set is in progress (except through the iterator's own remove * operation), the results of the iteration are undefined. The set supports * element removal, which removes the corresponding statement from the model, * via the Iterator.remove, Set.remove, removeAll, * retainAll, and clear operations. It does not support the * add or addAll operations if the parameters subj * , pred or obj are null. * * @return a set view of the contexts contained in this model */ public Set contexts(); /** * Gets the object of the statement(s). If contains one or more statements, * all these statements should have the same object. A * {@link ModelException} is thrown if this is not the case. * * @return The object of the matched statement(s), or null if no * matching statements were found. * @throws ModelException * If the statements matched by the specified parameters have more * than one unique object. */ public Value objectValue() throws ModelException; /** * Utility method that casts the return value of {@link #objectValue()} to a * Literal, or throws a ModelUtilException if that value is not a Literal. * * @return The object of the matched statement(s), or null if no * matching statements were found. * @throws ModelException * If such an exception is thrown by * {@link #getOptionalObject(Model, Resource, URI, Resource[])} or if * its return value is not a Literal. */ public Literal objectLiteral() throws ModelException; /** * Utility method that casts the return value of {@link #objectValue()} to a * Resource, or throws a ModelUtilException if that value is not a Resource. * * @return The object of the matched statement(s), or null if no * matching statements were found. * @throws ModelException * If such an exception is thrown by * {@link #getOptionalObject(Model, Resource, URI, Resource[])} or if * its return value is not a Resource. */ public Resource objectResource() throws ModelException; /** * Utility method that casts the return value of {@link #objectValue()} to a URI, * or throws a ModelUtilException if that value is not a URI. * * @return The object of the matched statement(s), or null if no * matching statements were found. * @throws ModelException * If such an exception is thrown by * {@link #getOptionalObject(Model, Resource, URI, Resource[])} or if * its return value is not a URI. */ public URI objectURI() throws ModelException; /** * Utility method that returns the string value of {@link #objectValue()}. * * @return The object string value of the matched statement(s), or * null if no matching statements were found. * @throws ModelException * If the statements matched by the specified parameters have more * than one unique object. */ public String objectString() throws ModelException; }