com.worklight.jsonstore.api

Class JSONStoreCollection

  • java.lang.Object
    • com.worklight.jsonstore.api.JSONStoreCollection


  • public class JSONStoreCollection
    extends java.lang.Object
    This class represents a single JSONStore collection. Operations on the collection can be done by using the API for this class.
    • Constructor Detail

      • JSONStoreCollection

        public JSONStoreCollection(java.lang.String name)
                            throws JSONStoreInvalidSchemaException
        Throws:
        JSONStoreInvalidSchemaException
    • Method Detail

      • getName

        public java.lang.String getName()
        Get the name of this collection.
        Returns:
        The name of the collection.
      • wasReopened

        public boolean wasReopened()
        Determine if the collection was reopened when it was initialized.
        Returns:
        True if the collection was reopened (already existed) when the collection is opened, or false if it is a brand new collection.
      • getSearchFields

        public java.util.Map getSearchFields()
        Return a map of search fields from the collection.
        Returns:
        A list of search fields that are defined in the collection.
      • setSearchField

        public void setSearchField(java.lang.String key,
                          SearchFieldType type)
        Set a search field for the collection.
        Parameters:
        key - The name of the search field to add. Only useful before the collection is opened.
        type - The type of the search field.
        See Also:
        SearchFieldType
      • hasSearchField

        public boolean hasSearchField(java.lang.String search_field)
        Determine if a collection contains the given search field.
        Parameters:
        search_field - The name of the search field to look up.
        Returns:
        True if the search field is defined in the collection, false if it is not defined.
      • setAdditionalSearchField

        public void setAdditionalSearchField(java.lang.String key,
                                    SearchFieldType type)
        Set an additional search field for the collection.
        Parameters:
        key - The name of the additional search field to add. Only useful before the collection is opened.
        type - The type of the search field.
        See Also:
        SearchFieldType
      • getAdditionalSearchFields

        public java.util.Map getAdditionalSearchFields()
        Get a map of the additional search fields for this collection.
        Returns:
        A map of additional search fields.
      • hasAdditionalSearchField

        public boolean hasAdditionalSearchField(java.lang.String additional_search_field)
        Determines if the collection contains the given additional search field.
        Parameters:
        additional_search_field - The name of the additional search field to check for existence.
        Returns:
        True if the additional search field exists.
      • getAllSearchFields

        protected java.util.Map getAllSearchFields()
        Get a map of all search fields for this collection.
        Returns:
        A map of all search fields and additional search fields in this collection.
      • removeCollection

        public void removeCollection()
                              throws JSONStoreRemoveCollectionException,
                                     JSONStoreDatabaseClosedException,
                                     JSONStoreTransactionFailureException
        Permanently deletes all the documents that are stored in a collection and destroys the collection.
        Throws:
        JSONStoreRemoveCollectionException - An error occurred when finding the collection to remove (may have already been removed).
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to remove the collection.
        JSONStoreTransactionFailureException - A transaction is in process and cannot be accessed to remove the collection.
      • clearCollection

        public void clearCollection()
                             throws JSONStoreDatabaseClosedException
        Removes all documents from a collection, but does not destroy the collection.
        Throws:
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to clear the collection.
      • changeData

        public int changeData(org.json.JSONObject[] data)
                       throws JSONStoreChangeException,
                              JSONStoreDatabaseClosedException,
                              org.json.JSONException
        Change a list of documents in the collection.
        Parameters:
        data - An array of data to update documents in the collection.
        Returns:
        The total number of documents that are changed.
        Throws:
        JSONStoreChangeException - An exception occurred when performing the change operation, and the operation failed.
        JSONStoreDatabaseClosedException - The JSONStore database is closed and cannot be accessed to execute the change operation.
        org.json.JSONException
      • changeData

        public int changeData(org.json.JSONObject[] data,
                     JSONStoreChangeOptions options)
                       throws JSONStoreChangeException,
                              JSONStoreDatabaseClosedException,
                              org.json.JSONException
        Change a list of documents in the collection.
        Parameters:
        data - A JSONObject array of data to update documents in the collection or add (if addNew option is enabled).
        options - Optional change options that are used to manipulate the change operation.
        Returns:
        The total number of documents that are changed or added.
        Throws:
        JSONStoreChangeException - An exception occurred when performing the change operation, and the operation failed.
        JSONStoreDatabaseClosedException - The JSONStore database is closed and cannot be accessed to execute the change operation.
        org.json.JSONException
      • changeData

        public int changeData(java.util.List data)
                       throws JSONStoreChangeException,
                              JSONStoreDatabaseClosedException,
                              org.json.JSONException
        Change a list of documents in the collection.
        Parameters:
        data - A list of data to update documents in the collection.
        Returns:
        The total number of documents that are changed.
        Throws:
        JSONStoreChangeException - An exception occurred when performing the change operation, and the operation failed.
        JSONStoreDatabaseClosedException - The JSONStore database is closed and cannot be accessed to execute the change operation.
        org.json.JSONException
      • changeData

        public int changeData(java.util.List data,
                     JSONStoreChangeOptions options)
                       throws JSONStoreChangeException,
                              JSONStoreDatabaseClosedException
        Change a list of documents in the collection.
        Parameters:
        data - A list of data to update documents in the collection or add (if addNew option is enabled).
        options - Optional change options that are used to manipulate the change operation.
        Returns:
        The total number of documents that are changed or added.
        Throws:
        JSONStoreChangeException - An exception occurred when performing the change operation, and the operation failed.
        JSONStoreDatabaseClosedException - The JSONStore database is closed and cannot be accessed to execute the change operation.
      • findDocumentById

        public org.json.JSONObject findDocumentById(int id)
                                             throws JSONStoreDatabaseClosedException,
                                                    JSONStoreFindException
        Find a document in the collection based on the given ID.
        Parameters:
        id - The unique id that is associated with a document in the database (the _id search field).
        Returns:
        The JSONObject that is associated with the document. Returns null if it is not found.
        Throws:
        JSONStoreFindException - There was an error executing the find operation.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to execute the find.
      • findDocumentsById

        public java.util.List findDocumentsById(int[] ids)
                                         throws JSONStoreDatabaseClosedException,
                                                JSONStoreFindException
        Find documents in the collection that have the given ID.
        Parameters:
        ids - An array of unique ids that are associated with a document in the database (the _id search field).
        Returns:
        All documents with the given ids that are present in the collection.
        Throws:
        JSONStoreFindException - There was an error executing the find operation.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to execute the find.
      • findDocumentsById

        public java.util.List findDocumentsById(java.util.List ids)
                                         throws JSONStoreDatabaseClosedException,
                                                JSONStoreFindException
        Find all documents in the collection that have the given ids.
        Parameters:
        ids - A list of unique ids that are associated with a document in the database (the _id search field).
        Returns:
        All documents with the given ids that are present in the collection.
        Throws:
        JSONStoreFindException - There was an error executing the find operation.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to execute the find.
      • findAllDirtyDocuments

        public java.util.List findAllDirtyDocuments()
                                             throws JSONStoreFindException,
                                                    JSONStoreDatabaseClosedException
        Find all the dirty documents in the collection.
        Returns:
        A list of documents that are marked dirty in the collection.
        Throws:
        JSONStoreFindException - An error occurred when trying to execute the find.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to execute the find.
      • findAllDocuments

        public java.util.List findAllDocuments()
                                        throws JSONStoreFindException,
                                               JSONStoreDatabaseClosedException
        Find all documents in the collection.
        Returns:
        A list of all the documents in the collection.
        Throws:
        JSONStoreFindException - An error occurred when trying to execute the find.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to execute the find.
      • findAllDocuments

        public java.util.List findAllDocuments(JSONStoreFindOptions options)
                                        throws JSONStoreFindException,
                                               JSONStoreDatabaseClosedException
        Find all documents in the collection.
        Parameters:
        options - Additional options to modify the count operation.
        Returns:
        The list of documents in the collection.
        Throws:
        JSONStoreFindException - An error occurred when trying to execute the find.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to execute the find.
      • findDocuments

        public java.util.List findDocuments(JSONStoreQueryParts query)
                                     throws JSONStoreFindException,
                                            JSONStoreFilterException,
                                            JSONStoreDatabaseClosedException
        Find documents in the collection that are based on the given query.
        Parameters:
        query - The find query that restricts the search.
        Returns:
        A list of documents.
        Throws:
        JSONStoreFindException - An error occurred when trying to execute the find.
        JSONStoreFilterException - An error occurred when trying to apply a filter to the query.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to execute the find.
      • findDocuments

        public java.util.List findDocuments(JSONStoreQueryParts query,
                                   JSONStoreFindOptions options)
                                     throws JSONStoreFindException,
                                            JSONStoreFilterException,
                                            JSONStoreDatabaseClosedException
        Find documents in the collection that are based on the given query.
        Parameters:
        query - The find query that restricts the search.
        options - Additional options to modify the count operation.
        Returns:
        A list of documents.
        Throws:
        JSONStoreFindException - An error occurred when trying to execute the find.
        JSONStoreFilterException - An error occurred when trying to apply a filter to the query.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to execute the find.
      • isDocumentDirty

        public boolean isDocumentDirty(int id)
                                throws JSONStoreDirtyCheckException,
                                       JSONStoreDatabaseClosedException
        Determine if a document is dirty or not.
        Parameters:
        id - The unique identifier of the document to check.
        Returns:
        Returns true if the given document is dirty.
        Throws:
        JSONStoreDirtyCheckException - An error occurred when checking to see if the document is dirty.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to check if the document is dirty.
      • markDocumentsClean

        public int markDocumentsClean(org.json.JSONObject[] documents)
                               throws JSONStoreMarkCleanException,
                                      JSONStoreDatabaseClosedException
        Mark an array of documents in the collection clean.
        Parameters:
        documents - An array of documents to clean in the collection.
        Returns:
        Returns the number of clean documents.
        Throws:
        JSONStoreMarkCleanException - An error occurred when trying to clean the documents that were passed.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to mark the documents clean.
      • markDocumentsClean

        public int markDocumentsClean(java.util.List documents)
                               throws JSONStoreMarkCleanException,
                                      JSONStoreDatabaseClosedException
        Mark a list of documents in the collection clean.
        Parameters:
        documents - A list of documents to clean in the collection.
        Returns:
        Returns the number of clean documents.
        Throws:
        JSONStoreMarkCleanException - An error occurred when trying to clean the documents that were passed.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to mark the documents clean.
      • markDocumentClean

        public int markDocumentClean(org.json.JSONObject document)
                              throws JSONStoreMarkCleanException,
                                     JSONStoreDatabaseClosedException
        Mark a document in the collection clean.
        Parameters:
        document - A document to clean in the collection.
        Returns:
        Returns 1 if the document has been cleaned.
        Throws:
        JSONStoreMarkCleanException - An error occurred when trying to clean the documents that were passed.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to mark the documents clean.
      • countAllDocuments

        public int countAllDocuments()
                              throws JSONStoreCountException,
                                     JSONStoreDatabaseClosedException
        Count the number of documents in the collection.
        Returns:
        The total number of documents that are currently in the database that are not marked dirty.
        Throws:
        JSONStoreCountException - A failure occurred when trying to determine the count.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the count.
      • countDocuments

        public int countDocuments(JSONStoreQueryParts query)
                           throws JSONStoreCountException,
                                  JSONStoreDatabaseClosedException
        Count the number of documents in the collection that are based on the given query.
        Parameters:
        query - The count query that limits the count scope.
        Returns:
        The total number of documents that are currently in the database that are not marked dirty.
        Throws:
        JSONStoreCountException - A failure occurred when trying to determine the count.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the count.
      • countDocuments

        public int countDocuments(JSONStoreQueryParts query,
                         JSONStoreCountOptions options)
                           throws JSONStoreCountException,
                                  JSONStoreDatabaseClosedException
        Count the number of documents in the collection that are based on the given query.
        Parameters:
        query - The find query that limits the count scope.
        options - Additional options to modify the count operation.
        Returns:
        The total number of documents that are currently in the database that are not marked dirty and fit the find query.
        Throws:
        JSONStoreCountException - A failure occurred when trying to determine the count.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the count.
      • countAllDirtyDocuments

        public int countAllDirtyDocuments()
                                   throws JSONStoreDatabaseClosedException,
                                          JSONStoreCountException
        Count the number of dirty documents in the collection.
        Returns:
        The number of dirty documents.
        Throws:
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the count.
        JSONStoreCountException - A failure occurred when trying to determine the count.
      • addData

        public void addData(org.json.JSONObject object_to_add)
                     throws JSONStoreAddException,
                            JSONStoreDatabaseClosedException
        Add data and create a new document in the collection.
        Parameters:
        object_to_add - The data for a new document to be added to the collection. The document must contain search field keys.
        Throws:
        JSONStoreAddException - Thrown if the document could not be added to the collection. Commonly thrown if search fields are missing in the document. The message contains the reason.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the add.
      • addData

        public void addData(java.util.List data,
                   JSONStoreAddOptions options)
                     throws JSONStoreAddException,
                            JSONStoreDatabaseClosedException
        Add data and create a new document in the collection.
        Parameters:
        data - The data for a new document to be added to the collection. The document must contain search field keys.
        options - Additional options to modify the add operation.
        Throws:
        JSONStoreAddException - Thrown if the document could not be added to the collection. Commonly thrown if search fields are missing in the document. The message contains the reason.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the add.
      • addData

        public void addData(org.json.JSONObject object_to_add,
                   JSONStoreAddOptions opts)
                     throws JSONStoreAddException,
                            JSONStoreDatabaseClosedException
        Throws:
        JSONStoreAddException
        JSONStoreDatabaseClosedException
      • addData

        public void addData(java.util.List object_to_add)
                     throws JSONStoreAddException,
                            JSONStoreDatabaseClosedException
        Throws:
        JSONStoreAddException
        JSONStoreDatabaseClosedException
      • addData

        public void addData(org.json.JSONArray dataArray)
                     throws JSONStoreAddException,
                            JSONStoreDatabaseClosedException
        Throws:
        JSONStoreAddException
        JSONStoreDatabaseClosedException
      • addData

        public void addData(org.json.JSONArray dataArray,
                   JSONStoreAddOptions opts)
                     throws JSONStoreAddException,
                            JSONStoreDatabaseClosedException
        Throws:
        JSONStoreAddException
        JSONStoreDatabaseClosedException
      • removeDocumentById

        public int removeDocumentById(java.lang.Integer id)
                               throws JSONStoreRemoveException,
                                      JSONStoreDatabaseClosedException
        Remove a document from a collection that is based on the given id.
        Parameters:
        id - the integer id
        Returns:
        the number of documents removed from the collection.
        Throws:
        JSONStoreRemoveException - Thrown if the document could not be removed to the collection. Commonly thrown if search fields are missing in the document. The message contains the reason.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the remove.
      • removeDocumentById

        public int removeDocumentById(java.lang.Integer id,
                             JSONStoreRemoveOptions options)
                               throws JSONStoreRemoveException,
                                      JSONStoreDatabaseClosedException
        Remove a document from the collection that is based on the given id.
        Parameters:
        id - the integer id
        options - Additional options to modify the remove operation.
        Returns:
        the number of documents removed from the collection.
        Throws:
        JSONStoreRemoveException - Thrown if the document could not be removed to the collection. Commonly thrown if search fields are missing in the document. The message contains the reason.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the remove.
      • removeDocumentsById

        public int removeDocumentsById(java.util.List document_ids)
                                throws JSONStoreRemoveException,
                                       JSONStoreDatabaseClosedException
        Remove list of documents from the collection that are based on the given ids.
        Parameters:
        document_ids - A list of document ids.
        Returns:
        The number of documents that have been removed from the collection.
        Throws:
        JSONStoreRemoveException - Thrown if the document could not be removed to the collection. Commonly thrown if search fields are missing in the document. The message contains the reason.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the remove.
      • removeDocumentsById

        public int removeDocumentsById(java.util.List document_ids,
                              JSONStoreRemoveOptions options)
                                throws JSONStoreRemoveException,
                                       JSONStoreDatabaseClosedException
        Remove list of documents from the collection that are based on the given ids.
        Parameters:
        document_ids - A list of document ids.
        options - Additional options to modify the remove operation.
        Returns:
        The number of documents that have been removed from the collection.
        Throws:
        JSONStoreRemoveException - Thrown if the document could not be removed to the collection. Commonly thrown if search fields are missing in the document. The message contains the reason.
        JSONStoreDatabaseClosedException - The JSONStore database is closed, and cannot be accessed to perform the remove.
      • replaceDocument

        public int replaceDocument(org.json.JSONObject document)
                            throws JSONStoreReplaceException,
                                   JSONStoreDatabaseClosedException
        Replace a document in the collection.
        Parameters:
        document - A JSONObject that represents the document to update in the collection. The document's '_id' is used to determine which document to replace.
        Returns:
        The number of replaced documents.
        Throws:
        JSONStoreReplaceException - The document could not be replaced. The message contains the reason.
        JSONStoreDatabaseClosedException - The collection is currently closed.
      • replaceDocument

        public int replaceDocument(org.json.JSONObject document,
                          JSONStoreReplaceOptions options)
                            throws JSONStoreReplaceException,
                                   JSONStoreDatabaseClosedException
        Replace a document in the collection.
        Parameters:
        document - A JSONObject that represents the document to update in the collection. The document's '_id' is used to determine which document to replace.
        options - Additional options to modify the replace operation.
        Returns:
        The number of replaced documents.
        Throws:
        JSONStoreReplaceException - The document could not be replaced. The message contains the reason.
        JSONStoreDatabaseClosedException - The collection is currently closed.
      • replaceDocuments

        public int replaceDocuments(java.util.List documents)
                             throws JSONStoreDatabaseClosedException,
                                    JSONStoreReplaceException
        Replace a list of documents in the collection.
        Parameters:
        documents - A List that contains JSONObjects that represent the documents to update in the collection. The document's '_id' is used to determine which document to replace. If all documents could not be updated, a rollback is performed to a state where no documents were updated.
        Returns:
        The number of replaced documents.
        Throws:
        JSONStoreReplaceException - The document could not be replaced. The message contains the reason.
        JSONStoreDatabaseClosedException - The collection is currently closed.
      • replaceDocuments

        public int replaceDocuments(java.util.List documents,
                           JSONStoreReplaceOptions options)
                             throws JSONStoreDatabaseClosedException,
                                    JSONStoreReplaceException
        Replace a list of documents in the collection.
        Parameters:
        documents - A List that contains JSONObjects that represent the documents to update in the collection. The document's '_id' is used to determine which document to replace. If all documents could not be updated, a rollback is performed to a state where no documents were updated.
        options - Additional options to modify the replace operation.
        Returns:
        The number of replaced documents.
        Throws:
        JSONStoreReplaceException - The document could not be replaced. The message contains the reason.
        JSONStoreDatabaseClosedException - The collection is currently closed.


© Copyright IBM Corp. 2006, 2015. All Rights Reserved.