Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.appengine.api.datastore
Interface DatastoreService

    public interface DatastoreService

The `DatastoreService` provides access to a schema-less data storage system. The fundamental unit of data in this system is the `Entity`, which has an immutable identity (represented by a `Key`) and zero of more mutable properties. `Entity` objects can be created, updated, deleted, retrieved by identifier, and queried via a combination of properties. The `DatastoreService` can be used transactionally and supports the notion of a "current" transaction. A current transaction is established by calling `beginTransaction()`. The transaction returned by this method ceases to be current when an attempt is made to commit or rollback or when another call is made to `beginTransaction()`. A transaction can only be current within the Thread that created it. The various overloads of put, get, and delete all support transactions. Users of this class have the choice of explicitly passing a (potentially `null`) `Transaction` to these methods or relying on the behavior governed by the `ImplicitTransactionManagementPolicy`. If a user explicitly provides a `Transaction` it is up to the user to call `Transaction.commit()` or `Transaction.rollback()` at the proper time. If a user relies on implicit transaction management and the installed policy creates a transaction, that transaction will be committed (in the case of a success) or rolled back (in the case of a failure) before the operation returns to the user. The methods that manage transactions according to `ImplicitTransactionManagementPolicy` are: `delete(Key[])`, `delete(Iterable)`, `get(Key)`, `get(Iterable)`, `put(Entity)`, and `put(Iterable)`. The overload of prepare that takes a `Transaction` parameter behaves the same as the overloads of put, get, and delete that take a `Transaction` parameter. However, the overload of prepare that does not take a `Transaction` parameter, unlike put, get, and delete, does not use an existing `Transaction` if one is already running and does not consult the `ImplicitTransactionManagementPolicy` if one is not already running.

Nested Class Summary
`static class` | `DatastoreService.KeyRangeState` Indicates the state of a `KeyRange`.

Method Summary
`DatastoreService.KeyRangeState` | `allocateIdRange(KeyRange range)` This method allocates a user-specified contiguous range of unique IDs.
`KeyRange` | `allocateIds(Key parent, java.lang.String kind, long num)` IDs are allocated within a namespace defined by a parent key and a kind.
`KeyRange` | `allocateIds(java.lang.String kind, long num)` IDs are allocated within a namespace defined by a parent key and a kind.
`Transaction` | `beginTransaction()` Begins a transaction against the datastore.
`void` | `delete(java.lang.Iterable<Key> keys)` Equivalent to `delete(Key...)`.
`void` | `delete(Key... keys)` Deletes the `Entity entities` specified by `keys`.
`void` | `delete(Transaction txn, java.lang.Iterable<Key> keys)` Exhibits the same behavior as `delete(Iterable)`, but executes within the provided transaction.
`void` | `delete(Transaction txn, Key... keys)` Exhibits the same behavior as `delete(Key[])`, but executes within the provided transaction.
`java.util.Map<Key,Entity>` | `get(java.lang.Iterable<Key> keys)` Retrieves the set of `Entities` matching `keys`.
`Entity` | `get(Key key)` Retrieves the `Entity` with the specified `Key`.
`java.util.Map<Key,Entity>` | `get(Transaction txn, java.lang.Iterable<Key> keys)` Exhibits the same behavior as `get(Iterable)`, but executes within the provided transaction.
`Entity` | `get(Transaction txn, Key key)` Exhibits the same behavior as `get(Key)`, but executes within the provided transaction.
`java.util.Collection<Transaction>` | `getActiveTransactions()`
`Transaction` | `getCurrentTransaction()` Returns the current transaction for this thread, or throws an exception if there is no current transaction.
`Transaction` | `getCurrentTransaction(Transaction returnedIfNoTxn)` Returns the current transaction for this thread, or returns the parameter if there is no current transaction.
`PreparedQuery` | `prepare(Query query)` Prepares a query for execution.
`PreparedQuery` | `prepare(Transaction txn, Query query)` Exhibits the same behavior as `prepare(Query)`, but executes within the provided transaction.
`Key` | `put(Entity entity)` If the specified `Entity` does not yet exist in the data store, create it and assign its `Key`.
`java.util.List<Key>` | `put(java.lang.Iterable<Entity> entities)` Performs a batch `put` of all `entities`.
`Key` | `put(Transaction txn, Entity entity)` Exhibits the same behavior as `put(Entity)`, but executes within the provided transaction.
`java.util.List<Key>` | `put(Transaction txn, java.lang.Iterable<Entity> entities)` Exhibits the same behavior as `put(Iterable)`, but executes within the provided transaction.

Method Detail

### get

    Entity get(Key key)
               throws EntityNotFoundException

  Retrieves the `Entity` with the specified `Key`. If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the `ImplicitTransactionManagementPolicy` available on the `DatastoreServiceConfig`.

  Throws:
    `EntityNotFoundException` - If the specified entity could not be found.
    `java.lang.IllegalArgumentException` - If the specified key is invalid.
    `DatastoreFailureException` - If any other datastore error occurs.

### get

    Entity get(Transaction txn,
               Key key)
               throws EntityNotFoundException

  Exhibits the same behavior as `get(Key)`, but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.

  Throws:
    `java.lang.IllegalStateException` - If `txn` is not null and not active.
    `EntityNotFoundException`

### get

    java.util.Map<Key,Entity> get(java.lang.Iterable<Key> keys)

  Retrieves the set of `Entities` matching `keys`. The result `Map` will only contain `Keys` for which `Entities` could be found. If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the `ImplicitTransactionManagementPolicy` available on the `DatastoreServiceConfig`.

  Throws:
    `java.lang.IllegalArgumentException` - If any `Key` in keys is invalid.
    `DatastoreFailureException` - If any other datastore error occurs.

### get

    java.util.Map<Key,Entity> get(Transaction txn,
                                  java.lang.Iterable<Key> keys)

  Exhibits the same behavior as `get(Iterable)`, but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.

  Throws:
    `java.lang.IllegalStateException` - If `txn` is not null and not active.

### put

    Key put(Entity entity)

  If the specified `Entity` does not yet exist in the data store, create it and assign its `Key`. If the specified `Entity` already exists in the data store, save the new version.

  The `Key` is returned, and is also returned by future calls to `entity.getKey()`. If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the `ImplicitTransactionManagementPolicy` available on the `DatastoreServiceConfig`.

  Throws:
    `java.lang.IllegalArgumentException` - If the specified entity was incomplete.
    `java.util.ConcurrentModificationException` - If this entity was modified concurrently in another transaction.
    `DatastoreFailureException` - If any other datastore error occurs.

### put

    Key put(Transaction txn,
            Entity entity)

  Exhibits the same behavior as `put(Entity)`, but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.

  Throws:
    `java.lang.IllegalStateException` - If `txn` is not null and not active.

### put

    java.util.List<Key> put(java.lang.Iterable<Entity> entities)

  Performs a batch `put` of all `entities`. If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the `ImplicitTransactionManagementPolicy` available on the `DatastoreServiceConfig`.

  Returns:
    The `Key`s that were assigned to the entities that were put. If the `Iterable` that was provided as an argument has a stable iteration order the `Key`s in the `List` we return are in that same order. If the `Iterable` that was provided as an argument does not have a stable iteration order the order of the `Key`s in the `List` we return is undefined.
  Throws:
    `java.lang.IllegalArgumentException` - If any entity is incomplete.
    `java.util.ConcurrentModificationException` - If any entity was modified concurrently in another transaction.
    `DatastoreFailureException` - If any other datastore error occurs.

### put

    java.util.List<Key> put(Transaction txn,
                            java.lang.Iterable<Entity> entities)

  Exhibits the same behavior as `put(Iterable)`, but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.

  Returns:
    The `Key`s that were assigned to the entities that were put. If the `Iterable` that was provided as an argument has a stable iteration order the `Key`s in the `List` we return are in that same order. If the `Iterable` that was provided as an argument does not have a stable iteration order the order of the `Key`s in the `List` we return is undefined.
  Throws:
    `java.lang.IllegalStateException` - If `txn` is not null and not

### delete

    void delete(Key... keys)

  Deletes the `Entity entities` specified by `keys`. If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the `ImplicitTransactionManagementPolicy` available on the `DatastoreServiceConfig`.

  Throws:
    `java.lang.IllegalArgumentException` - If the specified key was invalid.
    `java.util.ConcurrentModificationException` - If this entity was modified concurrently modified in another transaction.
    `DatastoreFailureException` - If any other datastore error occurs.

### delete

    void delete(Transaction txn,
                Key... keys)

  Exhibits the same behavior as `delete(Key[])`, but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.

  Throws:
    `java.lang.IllegalStateException` - If `txn` is not null and not

### delete

    void delete(java.lang.Iterable<Key> keys)

  Equivalent to `delete(Key...)`.

### delete

    void delete(Transaction txn,
                java.lang.Iterable<Key> keys)

  Exhibits the same behavior as `delete(Iterable)`, but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.

  Throws:
    `java.lang.IllegalStateException` - If `txn` is not null and not

### prepare

    PreparedQuery prepare(Query query)

  Prepares a query for execution.

  This method returns a `PreparedQuery` which can be used to execute and retrieve results from the datastore for `query`. This operation will not execute in a transaction even if there is a current transaction and it is an ancestor query. This operation also ignores the `ImplicitTransactionManagementPolicy`. If you are preparing an ancestory query and you want it to execute in a transaction, use `prepare(Transaction, Query)`.

  Parameters:
    `query` - a not `null Query`.
  Returns:
    a not `null PreparedQuery`.

### prepare

    PreparedQuery prepare(Transaction txn,
                          Query query)

  Exhibits the same behavior as `prepare(Query)`, but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.

  Throws:
    `java.lang.IllegalArgumentException` - If txn is not null and query is not an ancestor query
    `java.lang.IllegalStateException` - If txn is not null and the txn is not active

### beginTransaction

    Transaction beginTransaction()

  Begins a transaction against the datastore. Callers are responsible for explicitly calling `Transaction.commit()` or `Transaction.rollback()` when they no longer need the `Transaction`. The `Transaction` returned by this call will be considered the current transaction and will be returned by subsequent, same-thread calls to `getCurrentTransaction()` and `getCurrentTransaction(Transaction)` until one of the following happens: 1) `beginTransaction()` is invoked from the same thread. In this case `getCurrentTransaction()` and `getCurrentTransaction(Transaction)` will return the result of the more recent call to `beginTransaction()`. 2) `Transaction.commit()` is invoked on the `Transaction` returned by this method. Whether or not the commit returns successfully, the `Transaction` will no longer be the current transaction. 3) `Transaction.rollback()` ()} is invoked on the `Transaction` returned by this method. Whether or not the rollback returns successfully, the `Transaction` will no longer be the current transaction.

  Returns:
    the `Transaction` that was started.
  Throws:
    `DatastoreFailureException` - If a datastore error occurs.
  See Also:
    `getCurrentTransaction()`

### getCurrentTransaction

    Transaction getCurrentTransaction()

  Returns the current transaction for this thread, or throws an exception if there is no current transaction. The current transaction is defined as the result of the most recent, same-thread invocation of `beginTransaction()` that has not been committed or rolled back. Use this method for when you expect there to be a current transaction and consider it an error if there isn't.

  Returns:
    The current transaction.
  Throws:
    `java.util.NoSuchElementException` - If there is no current transaction.

### getCurrentTransaction

    Transaction getCurrentTransaction(Transaction returnedIfNoTxn)

  Returns the current transaction for this thread, or returns the parameter if there is no current transaction. You can use `null` or provide your own object to represent null. See `getCurrentTransaction()` for a definition of "current transaction." Use this method when you're not sure if there is a current transaction.

  Parameters:
    `returnedIfNoTxn` - The return value of this method if there is no current transaction. Can be null.
  Returns:
    The current transaction, or the parameter that was passed in if there is no current transaction.

### getActiveTransactions

    java.util.Collection<Transaction> getActiveTransactions()

  Returns:
    All `Transaction`s started by this thread upon which no attempt to commit or rollback has been made.

### allocateIds

    KeyRange allocateIds(java.lang.String kind,
                         long num)

  IDs are allocated within a namespace defined by a parent key and a kind. This method allocates a contiguous range of unique IDs of size `num` within the namespace defined by a null parent key (root entities) and the given kind. IDs allocated in this manner may be provided manually to newly created entities. They will not be used by the datastore's automatic ID allocator for root entities of the same kind.

  Parameters:
    `kind` - The kind for which the root entity IDs should be allocated.
    `num` - The number of IDs to allocate.
  Returns:
    A `KeyRange` of size `num`.
  Throws:
    `java.lang.IllegalArgumentException` - If `num` is less than 1 or if `num` is greater than 1 billion.

### allocateIds

    KeyRange allocateIds(Key parent,
                         java.lang.String kind,
                         long num)

  IDs are allocated within a namespace defined by a parent key and a kind. This method allocates a contiguous range of unique IDs of size `num` within the namespace defined by the given parent key and the given kind. IDs allocated in this manner may be provided manually to newly created entities. They will not be used by the datastore's automatic ID allocator for entities with the same kind and parent.

  Parameters:
    `parent` - The kind for which the child entity IDs should be allocated. Can be null.
    `kind` - The kind for which the child entity IDs should be allocated.
    `num` - The number of IDs to allocate.
  Returns:
    A range of IDs of size `num` that are guaranteed to be unique.
  Throws:
    `java.lang.IllegalArgumentException` - If `parent` is not a complete key, if `num` is less than 1, or if `num` is greater than 1 billion.

### allocateIdRange

    DatastoreService.KeyRangeState allocateIdRange(KeyRange range)

  This method allocates a user-specified contiguous range of unique IDs.

  Once these IDs have been allocated they may be provided manually to newly created entities.

  Since the datastore's automatic ID allocator will never assign a key to a new entity that will cause an existing entity to be overwritten, entities written to the given `KeyRange` will never be overwritten. However, writing entities with manually assigned keys in this range may overwrite existing entities (or new entities written by a separate request) depending on the `DatastoreService.KeyRangeState` returned.

  This method should only be used if you have an existing numeric id range that you want to reserve, e.g. bulk loading entities that already have IDs. If you don't care about which IDs you receive, use `allocateIds(java.lang.String, long)` instead.

  Parameters:
    `range` - The key range to allocate.
  Returns:
    The state of the id range allocated.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD