com.google.appengine.api.datastore

## Class DatastoreServiceConfig

- java.lang.Object
- - com.google.appengine.api.datastore.DatastoreServiceConfig

-     public final class DatastoreServiceConfig
      extends java.lang.Object

  User-configurable properties of the datastore.

  Notes on usage:
  The recommended way to instantiate a `DatastoreServiceConfig` object is to statically import `DatastoreServiceConfig.Builder`.* and invoke a static creation method followed by an instance mutator (if needed):

       import static com.google.appengine.api.datastore.DatastoreServiceConfig.Builder.*;
       import com.google.appengine.api.datastore.ReadPolicy.Consistency;

       ...

       // eventually consistent reads
       DatastoreServiceConfig config = withReadPolicy(new ReadPolicy(Consistency.EVENTUAL));

       // eventually consistent reads with a 5 second deadline
       DatastoreServiceConfig config =
         withReadPolicy(new ReadPolicy(Consistency.EVENTUAL)).deadline(5.0);

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DatastoreServiceConfig.Builder` Contains static creation methods for `DatastoreServiceConfig`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DATASTORE_EMPTY_LIST_SUPPORT` This is the name of a system property that determines how the Java SDK writes/reads empty lists to/from Datastore.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DatastoreServiceConfig` | `deadline(double deadline)` Sets the deadline, in seconds, for all rpcs initiated by the `DatastoreService` with which this config is associated.
    `java.lang.Double` | `getDeadline()`
    `static boolean` | `getEmptyListSupport()` Returns whether or not empty list support is enabled; see `DATASTORE_EMPTY_LIST_SUPPORT`.
    `ImplicitTransactionManagementPolicy` | `getImplicitTransactionManagementPolicy()`
    `java.lang.Integer` | `getMaxEntityGroupsPerRpc()`
    `ReadPolicy` | `getReadPolicy()`
    `DatastoreServiceConfig` | `implicitTransactionManagementPolicy(ImplicitTransactionManagementPolicy p)` Sets the implicit transaction management policy.
    `DatastoreServiceConfig` | `maxEntityGroupsPerRpc(int maxEntityGroupsPerRpc)` Sets the maximum number of entity groups that can be represented in a single rpc.
    `DatastoreServiceConfig` | `readPolicy(ReadPolicy readPolicy)` Sets the read policy.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DATASTORE_EMPTY_LIST_SUPPORT

          public static final java.lang.String DATASTORE_EMPTY_LIST_SUPPORT

      This is the name of a system property that determines how the Java SDK writes/reads empty lists to/from Datastore.

      Historically Datastore has not had the ability to represent an empty list in its persistent store. Different SDKs have made different decisions on what to write to Datastore when a client attempts to insert an empty list to the persistent store. The Java SDK has historically written both empty lists and null values as null values to the persistent store.

      With the release of this flag, Datastore can now represent empty lists within its persistent store. This means that Datastore SDKs can distinguish between empty lists and null values. This property controls whether this SDK writes an empty list as empty list or null to the persistent store.

      A note on queries: Null values can be indexed by Datastore which means they can interact with queries. For example queries that find all entities with null values or order by a property will include null values. Empty lists are not indexable by Datastore and so cannot appear in similar queries.

      Thus, if this flag was unset (the old behavior) and an empty list was stored into the persistent store, it could appear in query results because it was really stored as a null value.

      If this flag is set (the new behavior) and an empty list is stored into the persistent store, it will not appear it query results because it is stored as an empty list.

      When this variable is set to anything other than "true" the system provides legacy behavior.

      - Null properties are written as null to Datastore
      - Empty collections are written as null to Datastore
      - A null is read as null from Datastore
      - An empty collection is read as null. Note that a read modify write of an entity with an empty list will cause that list to be turned into a null value.

      When this variable is set to "true":

      - Null properties are written as null to Datastore
      - Empty collections (#`Collection.isEmpty()`) are written as empty list to Datastore
      - A null is read as null from Datastore
      - An empty collection is read as null
      - When reading from Datastore an empty list is returned as an empty `Collection`.

      It is strongly recommended that this property be set to true in order to provide compatibility with other Datastore SDK's, as well as future versions of Datastore.

      To set the flag: `System.setProperty(DatastoreServiceConfig.DATASTORE_EMPTY_LIST_SUPPORT, Boolean.TRUE.toString());`

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getEmptyListSupport

          public static boolean getEmptyListSupport()

      Returns whether or not empty list support is enabled; see `DATASTORE_EMPTY_LIST_SUPPORT`.

    - #### implicitTransactionManagementPolicy

          public DatastoreServiceConfig implicitTransactionManagementPolicy(ImplicitTransactionManagementPolicy p)

      Sets the implicit transaction management policy.
      Parameters:
        `p` - the implicit transaction management policy to set.
      Returns:
        `this` (for chaining)

    - #### readPolicy

          public DatastoreServiceConfig readPolicy(ReadPolicy readPolicy)

      Sets the read policy.
      Parameters:
        `readPolicy` - the read policy to set.
      Returns:
        `this` (for chaining)

    - #### deadline

          public DatastoreServiceConfig deadline(double deadline)

      Sets the deadline, in seconds, for all rpcs initiated by the `DatastoreService` with which this config is associated.
      Parameters:
        `deadline` - the deadline to set.
      Returns:
        `this` (for chaining)
      Throws:
        `java.lang.IllegalArgumentException` - if deadline is not positive

    - #### maxEntityGroupsPerRpc

          public DatastoreServiceConfig maxEntityGroupsPerRpc(int maxEntityGroupsPerRpc)

      Sets the maximum number of entity groups that can be represented in a single rpc.

      For a non-transactional operation that involves more entity groups than the maximum, the operation will be performed by executing multiple, asynchronous rpcs to the datastore, each of which has no more entity groups represented than the maximum. So, if a put() operation has 8 entity groups and the maximum is 3, we will send 3 rpcs, 2 with 3 entity groups and 1 with 2 entity groups. This is a performance optimization - in many cases multiple, small, asynchronous rpcs will finish faster than a single large asynchronous rpc. The optimal value for this property will be application-specific, so experimentation is encouraged.

      Parameters:
        `maxEntityGroupsPerRpc` - the maximum number of entity groups per rpc
      Returns:
        `this` (for chaining)
      Throws:
        `java.lang.IllegalArgumentException` - if maxEntityGroupsPerRpc is not greater than zero

    - #### getImplicitTransactionManagementPolicy

          public ImplicitTransactionManagementPolicy getImplicitTransactionManagementPolicy()

      Returns:
        The `ImplicitTransactionManagementPolicy` to use.

    - #### getReadPolicy

          public ReadPolicy getReadPolicy()

      Returns:
        The `ReadPolicy` to use.

    - #### getMaxEntityGroupsPerRpc

          public java.lang.Integer getMaxEntityGroupsPerRpc()

      Returns:
        The maximum number of entity groups per rpc.

    - #### getDeadline

          public java.lang.Double getDeadline()

      Returns:
        The deadline, in seconds, to use. Can be `null`.