Package oracle.soda

Interface OracleOperationBuilder

  • public interface OracleOperationBuilder
    An 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.

    • Method Detail

      • keys

        OracleOperationBuilder keys​(Set<String> keys)
                     throws OracleException
        Finds documents with specific keys.

        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();
        Parameters:
        keys - a set of keys. Cannot be null
        Returns:
        OracleOperationBuilder
        Throws:
        OracleException - if keys is null, or doesn't return any elements

      • key

        OracleOperationBuilder key​(String key)
                    throws OracleException
        Finds a document with a specific key.

        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();
        Parameters:
        key - the key. Cannot be null
        Returns:
        OracleOperationBuilder
        Throws:
        OracleException - if the key is null

      • keyLike

        OracleOperationBuilder keyLike​(String pattern,
                               String escape)
                        throws OracleException
        Finds documents with keys matching a supplied 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();
        Parameters:
        pattern - pattern. Can contain special pattern matching characters _ and %. Cannot be null
        escape - escape character. Can be null, which means no escape character will be used
        Returns:
        OracleOperationBuilder
        Throws:
        OracleException - 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
        See Also:
        LIKE Condition

      • filter

        OracleOperationBuilder filter​(OracleDocument filterSpecification)
                       throws OracleException
        Finds documents matching a filter specification (a query-by-example expressed in JSON).

        This is a non-terminal method, and, as such, it does not cause operation execution.

        Parameters:
        filterSpecification - the filter specification. Cannot be null
        Returns:
        OracleOperationBuilder
        Throws:
        OracleException - if the filterSpecification is null or invalid

      • filter

        OracleOperationBuilder filter​(String filterSpecification)
                       throws OracleException
        Finds documents matching a filter specification (a query-by-example expressed in JSON). Calling this method is equivalent to the following: 
         
   filter(db.createDocumentFromString(filterSpecification));
        Parameters:
        filterSpecification - the filter specification. Cannot be null
        Returns:
        OracleOperationBuilder
        Throws:
        OracleException - if the filterSpecification is null or invalid

      • version

        OracleOperationBuilder version​(String version)
                        throws OracleException
        Finds a document with a specific version.

        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.

        Parameters:
        version - version. Cannot be null
        Returns:
        OracleOperationBuilder
        Throws:
        OracleException - if the provided version is null

      • getCursor

        OracleCursor getCursor()
                throws OracleException
        Returns OracleCursor which is an iterator over result documents.

        This is a terminal method, and, as such, it causes operation execution.

        Returns:
        OracleCursor
        Throws:
        OracleException - if there's an error creating the cursor

      • replaceOneAndGet

        OracleDocument replaceOneAndGet​(OracleDocument document)
                         throws OracleException
        Replaces target document with supplied document.

        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.

        Parameters:
        document - input document. Cannot be null
        Returns:
        result document which contains the key and (if present) the created-on timestamp, last-modified timestamp, and version only. The input document's content is not returned as part of the result document
        Throws:
        OracleException - if (1) the input document is null, or (2) there's an error replacing the input document

      • replace

        int replace​(OracleDocument document)
     throws OracleException
        Replaces target document(s) with supplied document.

        Unlike replaceOne() and replaceOneAndGet() method, this method does not require key() method to be used in conjunction. Note also: unlike the two "replace one" methods mentioned above, this method can replace multiple target documents in the collection with the supplied document.

        For example: 

         // Replace content of documents having field "_id" with value 1,
 // with the content of supplied document d1
 col.find().filter("{\"_id\" : 1}").replace(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.

        Parameters:
        document - input document. Cannot be null
        Returns:
        number of documents replaced
        Throws:
        OracleException - if (1) the input document is null, or (2) there's an error replacing the input document

      • replaceOne

        boolean replaceOne​(OracleDocument document)
            throws OracleException
        Replaces target document with supplied document.

        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.

        Parameters:
        document - input document. Cannot be null
        Returns:
        true if the document was replaced successfully, false otherwise
        Throws:
        OracleException - if (1) the input document is null, or (2) there's an error replacing the input document

      • remove

        int remove()
    throws OracleException
        Removes documents.

        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.

        Returns:
        number of documents removed
        Throws:
        OracleException - if an error during removal occurs

      • limit

        OracleOperationBuilder limit​(int limit)
                      throws OracleException
        Specifies an upper limit on the number of results.

        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.

        Parameters:
        limit - limit on the number of results. Must be positive
        Returns:
        this OracleOperationBuilder
        Throws:
        OracleException - if the limit is not positive

      • orderByKey

        OracleOperationBuilder orderByKey​(boolean order)
        Specifies whether implicit order by should be included for operations involving skip(long) or limit(int).

        Documents are implicitly ordered by key, when skip() or limit() are used. This ensures a deterministic order by, which is needed for pagination.

        This function can be used to avoid this order by. This might be appropriate, for example, when limit(int) is used by itself, to simply return a bounded number of results.

        This method should only be invoked as part of building a read operation. If it is invoked as part of building a write operation (e.g. replace, remove, etc), it will have no effect.

        This is a non-terminal method, and, as such, it does not cause operation execution.

        Parameters:
        order - if false, operations involving skip(long) or limit(int) will not include an implicit sort. If true, operations involving skip(long) or limit(int) will include an implicit sort. Note that specifying true is equivalent to default behavior, in effect if this method is not invoked
        Returns:
        this OracleOperationBuilder

      • skip

        OracleOperationBuilder skip​(long skip)
                     throws OracleException
        Specifies the number of results to skip.

        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.

        Parameters:
        skip - number of results to skip. Must be non-negative
        Returns:
        OracleOperationBuilder
        Throws:
        OracleException - if the skip is negative

      • headerOnly

        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.

        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.

        Returns:
        this OracleOperationBuilder

      • count

        long count()
    throws OracleException
        Counts the number of documents.

        This is a terminal method, and, as such, it causes operation execution.

        Returns:
        document count
        Throws:
        OracleException - if there is an error getting the count

      • getOne

        OracleDocument getOne()
               throws OracleException
        Returns a single document. Use this method to get the document from the 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.

        Returns:
        returns a single document. null if no document is available
        Throws:
        OracleException - if there is an error retrieving the OracleDocument

      • lock

        OracleOperationBuilder lock()
                     throws OracleException
        Indicates that the operation should lock the documents.

        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.

        Returns:
        OracleOperationBuilder
        Throws:
        OracleException - if skip(long) or limit(int) are already specified on this OracleOperationBuilder object

      • mergeOne

        boolean mergeOne​(OracleDocument document)
          throws OracleException
        Merges the specified document into an existing one. The two documents are merged using the algorithm described in RFC7396 - JSON Merge Patch. For example, merging the document {"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.

        Parameters:
        document - input document. Cannot be null
        Returns:
        true if the document was replaced successfully, false otherwise
        Throws:
        OracleException - if (1) the input document is null, or (2) there's an error replacing the existing document
        See Also:
        RFC7396 - JSON Merge Patch

      • mergeOneAndGet

        OracleDocument mergeOneAndGet​(OracleDocument document)
                       throws OracleException
        Merges a document.

        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.

        Parameters:
        document - input document. Cannot be null
        Returns:
        result document which contains the key and (if present) the created-on timestamp, last-modified timestamp, and version only. The input document's content is not returned as part of the result document
        Throws:
        OracleException - if (1) the input document is null, or (2) there's an error replacing the input document

      • startKey

        OracleOperationBuilder startKey​(String startKey,
                                Boolean ascending,
                                Boolean inclusive)
                         throws OracleException
        Specifies that only keys that come after (or alternatively before) the specified key. The total ordering over key values in a collection is guaranteed stable and consistent. The ordering may depend on the underlying key storage type and default the collation settings of the database.

        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.

        Parameters:
        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
        Returns:
        this OracleOperationBuilder
        Throws:
        OracleException - if startKey is null