001: /*
002: * Copyright Aduna (http://www.aduna-software.com/) (c) 1997-2007.
003: *
004: * Licensed under the Aduna BSD-style license.
005: */
006: package org.openrdf.sail;
007:
008: import info.aduna.iteration.CloseableIteration;
009:
010: import org.openrdf.model.Namespace;
011: import org.openrdf.model.Resource;
012: import org.openrdf.model.Statement;
013: import org.openrdf.model.URI;
014: import org.openrdf.model.Value;
015: import org.openrdf.query.BindingSet;
016: import org.openrdf.query.Dataset;
017: import org.openrdf.query.QueryEvaluationException;
018: import org.openrdf.query.algebra.TupleExpr;
019:
020: /**
021: * A connection to an RDF Sail object. A SailConnection is active from the
022: * moment it is created until it is closed. Care should be taken to properly
023: * close SailConnections as they might block concurrent queries and/or updates
024: * on the Sail while active, depending on the Sail-implementation that is being
025: * used.
026: *
027: * @author jeen
028: * @author Arjohn Kampman
029: */
030: public interface SailConnection {
031:
032: /**
033: * Checks whether this SailConnection is open. A SailConnection is open from
034: * the moment it is created until it is closed.
035: *
036: * @see SailConnection#close
037: */
038: public boolean isOpen() throws SailException;
039:
040: /**
041: * Closes the connection. Any updates that haven't been committed yet will be
042: * rolled back. The connection can no longer be used once it is closed.
043: */
044: public void close() throws SailException;
045:
046: /**
047: * Evaluates the supplied TupleExpr on the data contained in this Sail
048: * object, using the (optional) dataset and supplied bindings as input
049: * parameters.
050: *
051: * @param tupleQuery
052: * The TupleQuery to evaluate.
053: * @param dataset
054: * The dataset to use for evaluating the query, <tt>null</tt> to use
055: * the Sail's default dataset.
056: * @param bindings
057: * A set of input parameters for the query evaluation. The keys
058: * reference variable names that should be bound to the value they map
059: * to.
060: * @param includeInferred
061: * Indicates whether inferred triples are to be considered in the
062: * query result. If false, no inferred statements are returned; if
063: * true, inferred statements are returned if available
064: * @return The TupleQueryResult.
065: * @throws SailException
066: * If the Sail object encountered an error or unexpected situation
067: * internally.
068: */
069: public CloseableIteration<? extends BindingSet, QueryEvaluationException> evaluate(
070: TupleExpr tupleExpr, Dataset dataset, BindingSet bindings,
071: boolean includeInferred) throws SailException;
072:
073: /**
074: * Returns the set of all unique context identifiers that are used to store
075: * statements.
076: *
077: * @return An iterator over the context identifiers, should not contain any
078: * duplicates.
079: */
080: public CloseableIteration<? extends Resource, SailException> getContextIDs()
081: throws SailException;
082:
083: /**
084: * Gets all statements from the specified contexts that have a specific
085: * subject, predicate and/or object. All three parameters may be null to
086: * indicate wildcards. The <tt>includeInferred</tt> parameter can be used
087: * to control which statements are fetched: all statements or only the
088: * statements that have been added explicitly.
089: *
090: * @param subj
091: * A Resource specifying the subject, or <tt>null</tt> for a
092: * wildcard.
093: * @param pred
094: * A URI specifying the predicate, or <tt>null</tt> for a wildcard.
095: * @param obj
096: * A Value specifying the object, or <tt>null</tt> for a wildcard.
097: * @param includeInferred
098: * if false, no inferred statements are returned; if true, inferred
099: * statements are returned if available
100: * @param contexts
101: * The context(s) to get the data from. Note that this parameter is a
102: * vararg and as such is optional. If no contexts are supplied the
103: * method operates on the entire repository.
104: * @return The statements matching the specified pattern.
105: * @throws SailException
106: * If the Sail object encountered an error or unexpected situation
107: * internally.
108: */
109: public CloseableIteration<? extends Statement, SailException> getStatements(
110: Resource subj, URI pred, Value obj,
111: boolean includeInferred, Resource... contexts)
112: throws SailException;
113:
114: /**
115: * Returns the number of (explicit) statements.
116: *
117: * @return The number of explicit statements in this Sail.
118: */
119: public long size(Resource... contexts) throws SailException;
120:
121: /**
122: * Commits any updates that have been performed since the last time
123: * {@link #commit()} or {@link #rollback()} was called.
124: *
125: * @throws SailException
126: * If the SailConnection could not be committed.
127: */
128: public void commit() throws SailException;
129:
130: /**
131: * Rolls back the SailConnection, discarding any uncommitted changes that
132: * have been made in this SailConnection.
133: *
134: * @throws SailException
135: * If the SailConnection could not be rolled back.
136: */
137: public void rollback() throws SailException;
138:
139: /**
140: * Adds a statement to each context in the specified contexts.
141: *
142: * @param subj
143: * The subject of the statement to add.
144: * @param pred
145: * The predicate of the statement to add.
146: * @param obj
147: * The object of the statement to add.
148: * @param contexts
149: * The context(s) to add the statement to. Note that this parameter is
150: * a vararg and as such is optional. If no contexts are supplied the
151: * method operates on the entire repository.
152: * @throws SailException
153: * If the statement could not be added.
154: */
155: public void addStatement(Resource subj, URI pred, Value obj,
156: Resource... contexts) throws SailException;
157:
158: /**
159: * Removes all statements matching the specified subject, predicate and
160: * object from the repository. All three parameters may be null to indicate
161: * wildcards.
162: *
163: * @param subj
164: * The subject of the statement that should be removed, or
165: * <tt>null</tt> to indicate a wildcard.
166: * @param pred
167: * The predicate of the statement that should be removed, or
168: * <tt>null</tt> to indicate a wildcard.
169: * @param obj
170: * The object of the statement that should be removed , or
171: * <tt>null</tt> to indicate a wildcard. *
172: * @param contexts
173: * The context(s) from which to remove the statement. Note that this
174: * parameter is a vararg and as such is optional. If no contexts are
175: * supplied the method operates on the entire repository.
176: * @throws SailException
177: * If the statement could not be removed.
178: */
179: public void removeStatements(Resource subj, URI pred, Value obj,
180: Resource... context) throws SailException;
181:
182: /**
183: * Removes all statements from the specified/all contexts. If no contexts are
184: * specified the method operates on the entire repository.
185: *
186: * @param contexts
187: * The context(s) from which to remove the statements. Note that this
188: * parameter is a vararg and as such is optional. If no contexts are
189: * supplied the method operates on the entire repository.
190: * @throws SailException
191: * If the statements could not be removed.
192: */
193: public void clear(Resource... contexts) throws SailException;
194:
195: /**
196: * Gets the namespaces relevant to the data contained in this Sail object.
197: *
198: * @returns An iterator over the relevant namespaces, should not contain any
199: * duplicates.
200: * @throws SailException
201: * If the Sail object encountered an error or unexpected situation
202: * internally.
203: */
204: public CloseableIteration<? extends Namespace, SailException> getNamespaces()
205: throws SailException;
206:
207: /**
208: * Gets the namespace that is mapped to the specified prefix.
209: *
210: * @param prefix
211: * A namespace prefix.
212: * @return The namespace name that the specified prefix maps to.
213: */
214: public String getNamespace(String prefix) throws SailException;
215:
216: /**
217: * Sets the prefix of a namespace.
218: *
219: * @param prefix
220: * The new prefix.
221: * @param name
222: * The namespace name that the prefix maps to.
223: */
224: public void setNamespace(String prefix, String name)
225: throws SailException;
226:
227: /**
228: * Removes a namespace declaration by removing the association between a
229: * prefix and a namespace name.
230: *
231: * @param prefix
232: * The namespace prefix of which the assocation with a namespace name
233: * is to be removed.
234: * @throws SailException
235: * If the namespace prefix could not be removed.
236: */
237: public void removeNamespace(String prefix) throws SailException;
238:
239: /**
240: * Removes all namespace declarations from the repository.
241: *
242: * @throws SailException
243: * If the namespaces could not be removed.
244: */
245: public void clearNamespaces() throws SailException;
246:
247: /**
248: * Registers a SailConnection listener with this SailConnection. The listener
249: * should be notified of any statements that are added or removed as part of
250: * this SailConnection.
251: *
252: * @param listener
253: * A SailConnectionListener.
254: */
255: public void addConnectionListener(SailConnectionListener listener);
256:
257: /**
258: * Deregisters a SailConnection listener with this SailConnection.
259: *
260: * @param listener
261: * A SailConnectionListener.
262: */
263: public void removeConnectionListener(SailConnectionListener listener);
264:
265: }
|