public interface OracleOperationBuilder
OracleOperationBuilder builds and executes various read
and write operations on the OracleCollection, in a chainable
manner.
An OracleOperationBuilder is first obtained by calling a
OracleCollection.find().
OracleOperationBuilder provides two types of methods: terminal
and non-terminal.
Non-terminal methods are used to build up the operation in a chainable
manner. They return the same OracleOperationBuilder object, on
which other non-terminal or terminal methods can be chained. Non-terminal
methods do not cause operation creation or execution. Under the hood, they
simply store additional state information in the
OracleOperationBuilder object, capturing the specified
parts of the operation.
Unlike non-terminal methods, terminal methods actually cause operation creation and execution.
For example:
OracleCollection ocollection = ...;
OracleCursor ocursor = ocollection.find().keys(keys).skip(25).limit(25).getCursor();
In this example, keys(Set), skip(long),
and limit(int) are non-terminal methods that specify parts
of the operation. More concretely, they specify that documents matching
provided keys should be returned, the first 25 of these results should be
skipped,and the number of results should be limited to 25. The
getCursor() method is a terminal, so it builds the operation
from the specified parts and executes it.| Modifier and Type | Method and Description |
|---|---|
long |
count()
Counts the number of documents.
|
OracleOperationBuilder |
filter(OracleDocument filterSpecification)
Finds documents matching a filter specification
(a query-by-example expressed in JSON).
|
OracleOperationBuilder |
filter(java.lang.String filterSpecification)
Finds documents matching a filter specification
(a query-by-example expressed in JSON).
|
OracleCursor |
getCursor()
Returns
OracleCursor which is an iterator over
result documents. |
OracleDocument |
getOne()
Returns a single document.
|
OracleOperationBuilder |
headerOnly()
Specifies that the returned documents should contain only the
the following:
key,
creation-on timestamp (if present in the collection),
last-modified timestamp (if present in the collection),
version (if present in the collection).
The documents' contents will not be returned.
|
OracleOperationBuilder |
hint(java.lang.String hints)
Adds execution hints to the operation
|
OracleOperationBuilder |
key(java.lang.String key)
Finds a document with a specific key.
|
OracleOperationBuilder |
keyLike(java.lang.String pattern,
java.lang.String escape)
Finds documents with keys matching a supplied
pattern. |
OracleOperationBuilder |
keys(java.util.Set<java.lang.String> keys)
Finds documents with specific keys.
|
OracleOperationBuilder |
limit(int limit)
Specifies an upper limit on the number of results.
|
OracleOperationBuilder |
lock()
Indicates that the operation should lock the documents.
|
boolean |
mergeOne(OracleDocument document)
Merges the specified document into an existing one.
|
OracleDocument |
mergeOneAndGet(OracleDocument document)
Merges a document.
|
int |
remove()
Removes documents.
|
boolean |
replaceOne(OracleDocument document)
Replaces a document.
|
OracleDocument |
replaceOneAndGet(OracleDocument document)
Replaces a document.
|
OracleOperationBuilder |
skip(long skip)
Specifies the number of results to skip.
|
OracleOperationBuilder |
startKey(java.lang.String startKey,
java.lang.Boolean ascending,
java.lang.Boolean inclusive)
Specifies that only keys that come after (or alternatively before) the
specified key.
|
OracleOperationBuilder |
version(java.lang.String version)
Finds a document with a specific version.
|
OracleOperationBuilder keys(java.util.Set<java.lang.String> keys) throws OracleException
This is a non-terminal method, and, as such, it does not cause operation execution.
If this method is invoked in conjunction with key(String)
or keyLike(String, String) on the same OracleOperationBuilder
object, then only the method specified last will be honored,
and the preceding ones will be ignored.
Example:
// key(...) is ignored, because keys(...) is set last.
col.find().key(...).keys(...).getCursor();
keys - a set of keys. Cannot be nullOracleOperationBuilderOracleException - if keys is null,
or doesn't return any elements.OracleOperationBuilder key(java.lang.String key) throws OracleException
This is a non-terminal method, and, as such, it does not cause operation execution.
If this method is invoked in conjunction with keys(Set)
or keyLike(String, String) on the same OracleOperationBuilder
object, then only the method specified last will be honored,
and the preceding ones will be ignored.
Example:
// keys(...) is ignored, because key(...) is set last.
col.find().keys(...).key(...).getOne();
key - the key. Cannot be nullOracleOperationBuilderOracleException - if the key is nullOracleOperationBuilder keyLike(java.lang.String pattern, java.lang.String escape) throws OracleException
pattern.
This method is only supported on collections with client-assigned keys, and a key column of type varchar2.
The pattern can contain special pattern matching characters _ (which
matches any single character), or % (which matches zero or more characters).
The escape parameter allows specifying an optional escape character, which
is used to test for literal occurences of the special pattern matching characters
_ and %.
Example 1: passing "%mykey%" for pattern, and null for escape
will match documents with keys containing the string "mykey", e.g "mykey20" or "20mykey".
Example 2: passing "key_1" for pattern, and null for escape
will match documents with keys that start with the string "key" followed by any single
character, followed by "1", e.g. "keyA1" or "keyB1".
Example 3: passing "mykey!_1" for pattern, and ! for escape
will match a document with key "mykey_1". Since the _ is escaped in the supplied
pattern, it is matched literally.
The pattern and escape character parameters correspond
to the pattern and escape of the Oracle SQL
LIKE condition.
This is a non-terminal method, and, as such, it does not cause operation execution.
If this method is invoked in conjunction with key(String)
or keys(Set) on the same OracleOperationBuilder
object, then only the method specified last will be honored,
and the preceding ones will be ignored.
Example:
// keys(...) is ignored, because keyLike(...) is set last.
col.find().keys(...).keyLike(...).getCursor();
pattern - pattern. Can contain special pattern matching characters
_ and %. Cannot be nullescape - escape character. Can be null,
which means no escape character will be usedOracleOperationBuilderOracleException - if pattern is null, or if
this method cannot be invoked on a particular
collection, because the latter doesn't have client-assigned
keys of type varchar2.OracleOperationBuilder filter(OracleDocument filterSpecification) throws OracleException
This is a non-terminal method, and, as such, it does not cause operation execution.
filterSpecification - the filter specification. Cannot
be nullOracleOperationBuilderOracleException - if the filterSpecification
is null or invalid.OracleOperationBuilder filter(java.lang.String filterSpecification) throws OracleException
filter(db.createDocumentFromString(filterSpecification));
filterSpecification - the filter specification. Cannot
be nullOracleOperationBuilderOracleException - if the filterSpecification
is null or invalid.OracleOperationBuilder version(java.lang.String version) throws OracleException
This method can be used in conjunction with the key(...)
method to match a document with a specific key and version:
col.find().key("k1").version("v1"). This combination
is useful for optimistic locking.
For example,
replace-if-version operation can be specified as follows:
col.find("k1").version("v1").replaceOne(d1)
Similarly, remove-if-version operation can be specified as follows:
col.find().key("k1").version("v1").remove()
This is a non-terminal method, and, as such, it does not cause operation execution.
version - version. Cannot be nullOracleOperationBuilderOracleException - if the provided version is nullOracleCursor getCursor() throws OracleException
OracleCursor which is an iterator over
result documents.
This is a terminal method, and, as such, it causes operation execution.
OracleCursorOracleException - if there's an error creating
the cursorOracleDocument replaceOneAndGet(OracleDocument document) throws OracleException
This method is used in conjunction with key(...),
and (optionally) version(...) methods.
For example:
// Replace a document with the key "k1" and version "v1",
// with the input document 'd1'.
OracleDocument doc = col.find().key("k1").version("v1").replaceOneAndGet(d1)
Note that the key and version information (if any) in the input
document 'd1' is ignored.
This is a terminal method, and, as such, it causes operation execution.
document - input document. Cannot be nullOracleException - if (1) the input document is null,
or (2) there's an error replacing the input
document.boolean replaceOne(OracleDocument document) throws OracleException
This method is used in conjunction with key(...),
and (optionally) version(...) methods.
For example:
// Replace a document with the key "k1" and version "v1"
// with the input document 'd1'.
col.find().key("k1").version("v1").replaceOne(d1)
Note that the key and version information (if any) in the input document 'd1' is ignored.
This is a terminal method, and, as such, it causes operation execution.
document - input document. Cannot be nulltrue if the document was
replaced successfully, false
otherwiseOracleException - if (1) the input document is null,
or (2) there's an error replacing the input
document.int remove()
throws OracleException
For example, the following removes a document
with a particular key and version:
col.find().key("k1").version("v1").remove()
Documents matching specific keys can be
removed as follows:
col.find().keys(keys).remove().
Documents matching a filter specification
can be removed as follows:
col.find().filter(filterSpec).remove()
This is a terminal method, and, as such, it causes operation execution.
OracleException - if an error during removal occursOracleOperationBuilder limit(int limit) throws OracleException
This is a non-terminal method, and, as such, it does not cause operation execution.
This method requires that the results are ordered. If an order is not
explicitly specified using the filter() method,
the documents will be ordered by the document key. See also
startKey()
This method should only be invoked as part of building a
read operation. If it's invoked as part of building a write operation
(e.g. with replace, remove, etc.), it will have no effect.
It is an error to specify this method in conjunction with
a count() terminal.
limit - limit on the number of results. Must be
positive.OracleOperationBuilderOracleException - if the limit is not positive.OracleOperationBuilder skip(long skip) throws OracleException
This is a non-terminal method, and, as such, it does not cause operation execution.
This interface assumes the results are ordered (e.g. by key).
This method should only be invoked as part of building a
read operation. If it's invoked as part of building a write operation
(e.g. with replace, remove, etc.), it will have no effect.
It is an error to specify this method in conjunction with
a count() terminal.
skip - number of results to skip. Must be
non-negative.OracleOperationBuilderOracleException - if the skip is negativeOracleOperationBuilder headerOnly()
This is a non-terminal method, and, as such, it does not cause operation execution.
This method should only be invoked as part of building a
read operation. If it's invoked as part of building
a write operation (e.g. replace, remove, etc), it will have
no effect. Also, this method will have no effect if invoked
as part of building a count() operation.
OracleOperationBuilderlong count()
throws OracleException
This is a terminal method, and, as such, it causes operation execution.
OracleException - if there is an error getting the countOracleDocument getOne() throws OracleException
OracleOperationBuilder returned by
key(String), for example: col.find().key(key).getOne()
If this method is used as a terminal for an operation that returns multiple documents, the first document is returned.
This is a terminal method, and, as such, it causes operation execution.
For the Oracle RDBMS implementation of SODA, the current limit for the maximum size of document that can be read is 2GB. An exception will be thrown by this method if the document's size exceeds this limit.
null
if no document is available.OracleException - if there is an error retrieving the
OracleDocumentOracleOperationBuilder lock() throws OracleException
This is a non-terminal method, and, as such, it does not cause operation execution.
This method should only be invoked as part of building a
read operation. If it's invoked as part of building a write operation
(e.g. with replace, remove, etc.), it will have no effect.
It is an error to specify this method in conjunction with
a count() terminal, skip(long) non-terminal, and
limit(int) non-terminal.
In order to use this method, ensure that the JDBC connection associated with this operation builder object is not in auto-commit mode. Otherwise, the acquired lock will be immediately unlocked by the automatic commit performed after the read operation. In other words, locking will have no effect if the connection is in auto-commit mode.
OracleOperationBuilderOracleException - if skip(long) or limit(int) are
already specified on this OracleOperationBuilder objectOracleOperationBuilder hint(java.lang.String hints) throws OracleException
hints - contains one or more hints, cannot be nullOracleOperationBuilderOracleException - If hint is null or invalid.boolean mergeOne(OracleDocument document) throws OracleException
{"count":42, "color":"red"} into an
existing document {"name":"apple", "count":12} produces a new
merged document {"name":"apple", "count":42, "color":"red"}.
This method is used in conjunction with key(...),
and (optionally) version(...) methods.
For example:
// Replace a document with the key "k1" and version "v1"
// with the input document 'd1'.
col.find().key("k1").version("v1").mergeOne(d1)
Note that the key and version information (if any) in the input document 'd1' is ignored.
This is a terminal method, and, as such, it causes operation execution.
document - input document. Cannot be nulltrue if the document was
replaced successfully, false
otherwiseOracleException - if (1) the input document is null,
or (2) there's an error replacing the existing
document.OracleDocument mergeOneAndGet(OracleDocument document) throws OracleException
This method is the same as mergeOne(OracleDocument) but additionally
returns the modified document. The mergeOne(OracleDocument) method may
avoid the additional cost of transferring the document back to the caller.
This is a terminal method, and, as such, it causes operation execution.
document - input document. Cannot be nullOracleException - if (1) the input document is null,
or (2) there's an error replacing the input
document.OracleOperationBuilder startKey(java.lang.String startKey, java.lang.Boolean ascending, java.lang.Boolean inclusive) throws OracleException
This method is expected to be used with the limit(int) method to do
pagination over a, possibly filtered, set of
documents. Calling limit(int) by itself will ensure that the
documents are returned in key order. For example:
// find the first 10 documents where the "count" property is greater than 20
String filter = "{\"count\": {\"$gt\" : 20}}";
OracleCursor cursor = col.find()
.filter()
.limit(10)
.getCursor();
String key = null;
while (cursor.hasNext()) {
OracleDocument doc = cursor.next();
key = doc.getKey();
...
}
...
// use startKey() to get the next 10 documents with count greater than 20
cursor = col.find()
.filter(filter)
.startKey(key, true, false)
.limit(10)
.getCursor();
This is a non-terminal method, and, as such, it does not cause operation execution. This method should only be invoked as part of building a read operation. If it's invoked as part of building a write operation (e.g. with replace, remove, etc.), it will have no effect.
startKey - the starting key.ascending - when true, returns documents in ascending order following
the startKey. When false, returns documents preceding the
startKey in descending order.inclusive - when true, the document with the startKey value, if it
exists, is included in the result.OracleOperationBuilderOracleException - if startKey is null