com.holonplatform.core.datastore

## Interface Datastore

- All Superinterfaces:
    DataContextBound, ExpressionResolver.ExpressionResolverSupport, Serializable

      public interface Datastore
      extends ExpressionResolver.ExpressionResolverSupport, DataContextBound, Serializable

  Datastore interface represents a generic data store abstraction and provides methods to perform data manipulation operations.

  This is the central interface to be used for persitent data management in a platform/vendor independent way.

  To preserve abstraction and independence from the underlying persistence context, query and persistence methods rely on `Property` to represent data attributes and `PropertyBox` to transport data values int both directions.

  In addition to default data manipulation methods, a Datastore can provide a set of commodities which can be used to perform specific data operations. The default `Query` Datastore commodity is provided by any Datastore implementation and it is the main interface to configure and execute queries on the data model using the default and implementation-independent `DataTarget`, `QueryFilter`, `QuerySort` and `QueryAggregation` expressions. To obtain a `Query` builder, the `query()` method is made available.

  Since:
    5.0.0
  See Also:
    `Query`, `DatastoreCommodityFactory`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Datastore.Builder<D extends Datastore,B extends Datastore.Builder<D,B>>` Base `Datastore` builder.
    `static interface` | `Datastore.OperationResult` Represents the result of a `Datastore` operation, providing informatons about the operation outcome.
    `static class` | `Datastore.OperationType` Enumeration of `Datastore` operation types.
    `static interface` | `Datastore.WriteOption` Represents a write operation option.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `BulkDelete` | `bulkDelete(DataTarget<?> target, Datastore.WriteOption... options)` Create a `BulkDelete` clause for bulk DELETE operations.
    `BulkInsert` | `bulkInsert(DataTarget<?> target, PropertySet<?> propertySet, Datastore.WriteOption... options)` Create a `BulkInsert` clause for bulk INSERT operations.
    `BulkUpdate` | `bulkUpdate(DataTarget<?> target, Datastore.WriteOption... options)` Create a `BulkUpdate` clause for bulk UPDATE operations.
    `<C extends DatastoreCommodity> C` | `create(Class<C> commodityType)` Create a new `DatastoreCommodity` of given `commodityType` type.
    `Datastore.OperationResult` | `delete(DataTarget<?> target, PropertyBox propertyBox, Datastore.WriteOption... options)` Remove a persistent element from datastore, using given `target` to denote persistent entity to delete and given `PropertyBox` to provide key property values
    `Collection<Class<? extends DatastoreCommodity>>` | `getAvailableCommodities()` Get the available `DatastoreCommodity` types for this Datastore.
    `Datastore.OperationResult` | `insert(DataTarget<?> target, PropertyBox propertyBox, Datastore.WriteOption... options)` Insert a `PropertyBox` using given `target` to denote persistent entity of datastore.
    `default Query` | `query()` Convenience method to create the default `Query` Datastore commodity, to be used to query the data store using default `DataTarget`, `QueryFilter`, `QuerySort` and `QueryAggregation` expressions.
    `PropertyBox` | `refresh(DataTarget<?> target, PropertyBox propertyBox)` Refresh a `PropertyBox`, updating all its model properties to current value in datastore and using given `target` to denote persistent entity of datastore
    `Datastore.OperationResult` | `save(DataTarget<?> target, PropertyBox propertyBox, Datastore.WriteOption... options)` Save a `PropertyBox` using given `target` to denote persistent entity of datastore: insert data if not exists, update it otherwise.
    `Datastore.OperationResult` | `update(DataTarget<?> target, PropertyBox propertyBox, Datastore.WriteOption... options)` Update a `PropertyBox` using given `target` to denote persistent entity of datastore.

    - ### Methods inherited from interface com.holonplatform.core.ExpressionResolver.ExpressionResolverSupport

      `addExpressionResolver, getExpressionResolvers, removeExpressionResolver`

    - ### Methods inherited from interface com.holonplatform.core.datastore.DataContextBound

      `getDataContextId`

- - ### Method Detail

    - #### refresh

          PropertyBox refresh(DataTarget<?> target,
                              PropertyBox propertyBox)

      Refresh a `PropertyBox`, updating all its model properties to current value in datastore and using given `target` to denote persistent entity of datastore
      Parameters:
        `target` - `DataTarget` to identify data entity to refresh
        `propertyBox` - PropertyBox to refresh
      Returns:
        Refreshed PropertyBox
      Throws:
        `DataAccessException` - If underlying Datastore implementation throws an Exception executing operation

    - #### insert

          Datastore.OperationResult insert(DataTarget<?> target,
                                           PropertyBox propertyBox,
                                           Datastore.WriteOption... options)

      Insert a `PropertyBox` using given `target` to denote persistent entity of datastore.
      Parameters:
        `target` - `DataTarget` to identify data entity to insert
        `propertyBox` - PropertyBox to insert
        `options` - Optional write options. The write options are specific for each concrete Datastore implementation.
      Returns:
        the result of the operation execution
      Throws:
        `DataAccessException` - If underlying Datastore implementation throws an Exception executing operation

    - #### update

          Datastore.OperationResult update(DataTarget<?> target,
                                           PropertyBox propertyBox,
                                           Datastore.WriteOption... options)

      Update a `PropertyBox` using given `target` to denote persistent entity of datastore.
      Parameters:
        `target` - `DataTarget` to identify data entity to update
        `propertyBox` - PropertyBox to update
        `options` - Optional write options. The write options are specific for each concrete Datastore implementation.
      Returns:
        the result of the operation execution
      Throws:
        `DataAccessException` - If underlying Datastore implementation throws an Exception executing operation

    - #### save

          Datastore.OperationResult save(DataTarget<?> target,
                                         PropertyBox propertyBox,
                                         Datastore.WriteOption... options)

      Save a `PropertyBox` using given `target` to denote persistent entity of datastore: insert data if not exists, update it otherwise.
      Parameters:
        `target` - `DataTarget` to identify data entity to save
        `propertyBox` - PropertyBox to save
        `options` - Optional write options. The write options are specific for each concrete Datastore implementation.
      Returns:
        the result of the operation execution
      Throws:
        `DataAccessException` - If underlying Datastore implementation throws an Exception executing operation

    - #### delete

          Datastore.OperationResult delete(DataTarget<?> target,
                                           PropertyBox propertyBox,
                                           Datastore.WriteOption... options)

      Remove a persistent element from datastore, using given `target` to denote persistent entity to delete and given `PropertyBox` to provide key property values
      Parameters:
        `target` - `DataTarget` to identify data entity to delete
        `propertyBox` - PropertyBox which contains key property values to identify element to delete
        `options` - Optional write options. The write options are specific for each concrete Datastore implementation.
      Returns:
        the result of the operation execution
      Throws:
        `DataAccessException` - If underlying Datastore implementation throws an Exception executing operation

    - #### bulkInsert

          BulkInsert bulkInsert(DataTarget<?> target,
                                PropertySet<?> propertySet,
                                Datastore.WriteOption... options)

      Create a `BulkInsert` clause for bulk INSERT operations.
      Parameters:
        `target` - `DataTarget` to identify data entity to insert
        `propertySet` - The property set to use to perform insert operations. Only the properties contained in given property set will be taken into account to insert the `PropertyBox` values
        `options` - Optional write options. The write options are specific for each concrete Datastore implementation.
      Returns:
        `BulkInsert` clause

    - #### bulkUpdate

          BulkUpdate bulkUpdate(DataTarget<?> target,
                                Datastore.WriteOption... options)

      Create a `BulkUpdate` clause for bulk UPDATE operations.
      Parameters:
        `target` - `DataTarget` to identify data entity to update
        `options` - Optional write options. The write options are specific for each concrete Datastore implementation.
      Returns:
        `BulkUpdate` clause

    - #### bulkDelete

          BulkDelete bulkDelete(DataTarget<?> target,
                                Datastore.WriteOption... options)

      Create a `BulkDelete` clause for bulk DELETE operations.
      Parameters:
        `target` - `DataTarget` to identify data entity to delete
        `options` - Optional write options. The write options are specific for each concrete Datastore implementation.
      Returns:
        `BulkDelete` clause

    - #### getAvailableCommodities

          Collection<Class<? extends DatastoreCommodity>> getAvailableCommodities()

      Get the available `DatastoreCommodity` types for this Datastore.
      Returns:
        Available `DatastoreCommodity` types collection, empty if none

    - #### create

          <C extends DatastoreCommodity> C create(Class<C> commodityType)

      Create a new `DatastoreCommodity` of given `commodityType` type.
      Type Parameters:
        `C` - Commodity type
      Parameters:
        `commodityType` - Commodity type to create (not null)
      Returns:
        The commodity instance
      Throws:
        `DatastoreCommodityContext.CommodityNotAvailableException` - If a commodity of the required type is not available for this Datastore
        `DatastoreCommodityContext.CommodityConfigurationException` - If a commodity configuration error occurred

    - #### query

          default Query query()

      Convenience method to create the default `Query` Datastore commodity, to be used to query the data store using default `DataTarget`, `QueryFilter`, `QuerySort` and `QueryAggregation` expressions.
      Returns:
        A new `Query` representation and builder
      See Also:
        `Query`

Copyright © 2017 The Holon Platform. All rights reserved.