Package com.mysql.cj.xdevapi

Interface Collection

All Superinterfaces:
DatabaseObject
All Known Implementing Classes:
CollectionImpl
public interface Collection
extends DatabaseObject
Representation of a document collection. This interface allows access to and manipulation of the collection through add/find/modify/remove statements.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface com.mysql.cj.xdevapi.DatabaseObject

    DatabaseObject.DbObjectStatus, DatabaseObject.DbObjectType

  • Method Summary

    Modifier and Type Method Description
    AddStatement add​(DbDoc document)
    Add a document in the form of a DbDoc.
    AddStatement add​(DbDoc... documents)
    Add a sequence of documents.
    AddStatement add​(java.lang.String... jsonStrings)
    Add one or more documents.
    AddStatement add​(java.util.Map<java.lang.String,​?> doc)
    Add a document in the form of a Map.
    Result addOrReplaceOne​(java.lang.String id, DbDoc doc)
    Adds the document to the collection.
    Result addOrReplaceOne​(java.lang.String id, java.lang.String jsonString)
    Adds the document to the collection.
    long count()
    Query the number of documents in this collection.
    Result createIndex​(java.lang.String indexName, DbDoc indexDefinition)
    Create a new statement defining the creation of an index on this collection.
    Result createIndex​(java.lang.String indexName, java.lang.String jsonIndexDefinition)
    Create a new statement defining the creation of an index on this collection.
    void dropIndex​(java.lang.String indexName)
    Create a new statement defining the removal of an index on this collection.
    FindStatement find()
    Create a new find statement retrieving all documents in the collection.
    FindStatement find​(java.lang.String searchCondition)
    Create a new find statement retrieving documents matching the given search condition.
    DbDoc getOne​(java.lang.String id)
    Return the document with the given id.
    ModifyStatement modify​(java.lang.String searchCondition)
    Create a new modify statement affecting documents matching the given search condition.
    DbDoc newDoc()
    Create a new document.
    RemoveStatement remove​(java.lang.String searchCondition)
    Create a new removal statement affecting documents matching the given search condition.
    Result removeOne​(java.lang.String id)
    Removes the document with the given id.
    Result replaceOne​(java.lang.String id, DbDoc doc)
    Takes in a document object that will replace the matching document.
    Result replaceOne​(java.lang.String id, java.lang.String jsonString)
    Takes in a document object that will replace the matching document.

    Methods inherited from interface com.mysql.cj.xdevapi.DatabaseObject

    existsInDatabase, getName, getSchema, getSession

  • Method Details

    • add

      AddStatement add​(java.util.Map<java.lang.String,​?> doc)
      Add a document in the form of a Map.
      Parameters:
      doc - map of key-value parameters representing the document fields
      Returns:
      AddStatement

    • add

      AddStatement add​(java.lang.String... jsonStrings)
      Add one or more documents.
      Parameters:
      jsonStrings - one or more documents given as JSON strings
      Returns:
      AddStatement

    • add

      AddStatement add​(DbDoc document)
      Add a document in the form of a DbDoc.
      Parameters:
      document - DbDoc
      Returns:
      AddStatement

    • add

      AddStatement add​(DbDoc... documents)
      Add a sequence of documents.
      Parameters:
      documents - one or more documents given as DbDoc
      Returns:
      AddStatement

    • find

      FindStatement find()
      Create a new find statement retrieving all documents in the collection.
      Returns:
      FindStatement

    • find

      FindStatement find​(java.lang.String searchCondition)
      Create a new find statement retrieving documents matching the given search condition.
      Parameters:
      searchCondition - condition expression
      Returns:
      FindStatement

    • modify

      ModifyStatement modify​(java.lang.String searchCondition)
      Create a new modify statement affecting documents matching the given search condition.
      Parameters:
      searchCondition - condition expression
      Returns:
      ModifyStatement

    • remove

      RemoveStatement remove​(java.lang.String searchCondition)
      Create a new removal statement affecting documents matching the given search condition.
      Parameters:
      searchCondition - condition expression
      Returns:
      RemoveStatement

    • createIndex

      Result createIndex​(java.lang.String indexName, DbDoc indexDefinition)
      Create a new statement defining the creation of an index on this collection.

      Example: collection.createIndex("myIndex", "{\"fields\": [{\"field\": \"$.myGeoJsonField\", \"type\": \"GEOJSON\", \"required\": true, \"options\": 2, \"srid\": 4326}], \"type\":\"SPATIAL\"}");

      Parameters:
      indexName - index name
      indexDefinition - JSON document with the following fields:
      • fields: array of IndexField objects, each describing a single document member to be included in the index (see below)
      • type: string, (optional) the type of index. One of INDEX or SPATIAL (case insensitive). Default is INDEX and may be omitted.
      where single IndexField description consists of the following fields:
      • field: string, the full document path to the document member or field to be indexed
      • type: string, one of the supported SQL column types to map the field into (see below for a list). For numeric types, the optional UNSIGNED keyword may follow. For the TEXT type, the length to consider for indexing may be added. Type descriptions are case insensitive.
      • required: bool, (optional) true if the field is required to exist in the document. Defaults to false, except for GEOJSON where it defaults to true
      • options: int, (optional) special option flags for use when decoding GEOJSON data
      • srid: int, (optional) srid value for use when decoding GEOJSON data
      Returns:
      Result

    • createIndex

      Result createIndex​(java.lang.String indexName, java.lang.String jsonIndexDefinition)
      Create a new statement defining the creation of an index on this collection.

      Example: collection.createIndex("myIndex", "{\"fields\": [{\"field\": \"$.myGeoJsonField\", \"type\": \"GEOJSON\", \"required\": true, \"options\": 2, \"srid\": 4326}], \"type\":\"SPATIAL\"}");

      Parameters:
      indexName - index name
      jsonIndexDefinition - JSON document with the following fields:
      • fields: array of IndexField objects, each describing a single document member to be included in the index (see below)
      • type: string, (optional) the type of index. One of INDEX or SPATIAL. Default is INDEX and may be omitted.
      where single IndexField description consists of the following fields:
      • field: string, the full document path to the document member or field to be indexed
      • type: string, one of the supported SQL column types to map the field into (see below for a list). For numeric types, the optional UNSIGNED keyword may follow. For the TEXT type, the length to consider for indexing may be added.
      • required: bool, (optional) true if the field is required to exist in the document. Defaults to false, except for GEOJSON where it defaults to true
      • options: int, (optional) special option flags for use when decoding GEOJSON data
      • srid: int, (optional) srid value for use when decoding GEOJSON data
      Returns:
      Result

    • dropIndex

      void dropIndex​(java.lang.String indexName)
      Create a new statement defining the removal of an index on this collection.
      Parameters:
      indexName - index name

    • count

      long count()
      Query the number of documents in this collection.
      Returns:
      The number of documents in this collection

    • newDoc

      DbDoc newDoc()
      Create a new document.
      Returns:
      DbDoc

    • replaceOne

      Result replaceOne​(java.lang.String id, DbDoc doc)
      Takes in a document object that will replace the matching document. If no matches are found, the function returns normally with no changes being made.
      Parameters:
      id - the document id of the document to be replaced
      doc - the new document, which may contain expressions. If document contains an _id value, it is ignored.
      Returns:
      Result object, which will indicate the number of affected documents (1 or 0, if none)

    • replaceOne

      Result replaceOne​(java.lang.String id, java.lang.String jsonString)
      Takes in a document object that will replace the matching document. If no matches are found, the function returns normally with no changes being made.
      Parameters:
      id - the document id of the document to be replaced
      jsonString - the new document, given as JSON string, which may contain expressions. If document contains an _id value, it is ignored.
      Returns:
      Result object, which will indicate the number of affected documents (1 or 0, if none)

    • addOrReplaceOne

      Result addOrReplaceOne​(java.lang.String id, DbDoc doc)
      Adds the document to the collection. The following algorithm applies:
      Parameters:
      id - the document id of the document to be replaced
      doc - the new document, which may contain expressions. If doc contains an _id value and it does not match the given id then the error will be thrown.
      Returns:
      Result object, which will indicate the number of affected documents (0 - if none, 1 - if added, 2 - if replaced)

    • addOrReplaceOne

      Result addOrReplaceOne​(java.lang.String id, java.lang.String jsonString)
      Adds the document to the collection. The following algorithm applies:
      Parameters:
      id - the document id of the document to be replaced
      jsonString - the new document, given as JSON string, which may contain expressions. If doc contains an _id value and it does not match the given id then the error will be thrown.
      Returns:
      Result object, which will indicate the number of affected documents (0 - if none, 1 - if added, 2 - if replaced)

    • getOne

      DbDoc getOne​(java.lang.String id)
      Return the document with the given id.
      Parameters:
      id - the document id of the document to be retrieved
      Returns:
      the document, or NULL if no match found

    • removeOne

      Result removeOne​(java.lang.String id)
      Removes the document with the given id.
      Parameters:
      id - the document id of the document to be removed
      Returns:
      Returns a Result object, which will indicate the number of removed documents (1 or 0, if none)