01: /*
02: * Copyright Aduna (http://www.aduna-software.com/) (c) 2007.
03: *
04: * Licensed under the Aduna BSD-style license.
05: */
06: package org.openrdf.model;
07:
08: import java.io.Serializable;
09: import java.util.Collection;
10: import java.util.Iterator;
11:
12: import org.openrdf.OpenRDFUtil;
13: import org.openrdf.model.util.GraphUtil;
14:
15: /**
16: * An RDF graph, represented as a collection of {@link Statement}s.
17: *
18: * @see GraphUtil
19: * @author Arjohn Kampman
20: */
21: public interface Graph extends Collection<Statement>, Serializable {
22:
23: /**
24: * Gets the value factory for this graph.
25: */
26: public ValueFactory getValueFactory();
27:
28: /**
29: * Adds one or more statements to the graph. This method creates a statement
30: * for each specified context and adds those to the graph. If no contexts are
31: * specified, a single statement with no associated context is added.
32: *
33: * @param subj
34: * The statement's subject, must not be <tt>null</tt>.
35: * @param pred
36: * The statement's predicate, must not be <tt>null</tt>.
37: * @param obj
38: * The statement's object, must not be <tt>null</tt>.
39: * @param contexts
40: * The contexts to add statements to.
41: */
42: public boolean add(Resource subj, URI pred, Value obj,
43: Resource... contexts);
44:
45: /**
46: * Gets the statements with the specified subject, predicate, object and
47: * (optionally) context. The <tt>subject</tt>, <tt>predicate</tt> and
48: * <tt>object</tt> parameters can be <tt>null</tt> to indicate wildcards.
49: * The <tt>contexts</tt> parameter is a wildcard and accepts zero or more
50: * values. If no contexts are specified, statements will match disregarding
51: * their context. If one or more contexts are specified, statements with a
52: * context matching one of these will match. Note: to match statements
53: * without an associated context, specify the value <tt>null</tt> and
54: * explicitly cast it to type <tt>Resource</tt>.
55: * <p>
56: * Examples: <tt>graph.match(s1, null, null)</tt> matches all statements
57: * that have subject <tt>s1</tt>,<br>
58: * <tt>graph.match(null, null, null, c1)</tt> matches all statements that
59: * have context <tt>c1</tt>,<br>
60: * <tt>graph.match(null, null, null, (Resource)null)</tt> matches all
61: * statements that have no associated context,<br>
62: * <tt>graph.match(null, null, null, c1, c2, c3)</tt> matches all
63: * statements that have context <tt>c1</tt>, <tt>c2</tt> or <tt>c3</tt>.
64: *
65: * @param subj
66: * The subject of the statements to match, <tt>null</tt> to match
67: * statements with any subject.
68: * @param pred
69: * The predicate of the statements to match, <tt>null</tt> to match
70: * statements with any predicate.
71: * @param obj
72: * The object of the statements to match, <tt>null</tt> to match
73: * statements with any object.
74: * @param contexts
75: * The contexts of the statements to match. If no contexts are
76: * specified, statements will match disregarding their context. If one
77: * or more contexts are specified, statements with a context matching
78: * one of these will match.
79: * @return The statements that match the specified pattern.
80: * @throws IllegalArgumentException
81: * If a <tt>null</tt>-array is specified as the value for
82: * <tt>contexts</tt>. See
83: * {@link OpenRDFUtil#verifyContextNotNull(Resource[])} for more
84: * info.
85: */
86: public Iterator<Statement> match(Resource subj, URI pred,
87: Value obj, Resource... contexts);
88: }
|