Objectify (Objectify App Engine 5.0 API)

All Known Implementing Classes:

ObjectifyImpl
```
public interface Objectify
```
This is the main "business end" of Objectify. It lets you load, save, and delete your typed POJO entities.

Objectify instances are obtained by calling the static method ObjectifyService.ofy(). This method will always provide the correct Objectify instance for a given transactional context. You can run transactions by calling Objectify.transact() or Objectify.transactNew(); calling ObjectifyService.ofy() within Work.run() will produce the correct Objectify instance associated with the correct transaction.

Objectify instances are immutable but they are NOT thread-safe. The instance contains a session cache of entities that have been loaded from the instance. You should never access an Objectify from more than one thread simultaneously.

Author:

Jeff Schnitzer

Method Summary

Methods
Modifier and Type	Method and Description
`Objectify`	`cache(boolean value)` Provides a new Objectify instance which uses (or doesn't use) a 2nd-level memcache.
`void`	`clear()` Clears the session; all subsequent requests (or Ref.get() calls) will go to the datastore/memcache to repopulate the session.
`Objectify`	`consistency(com.google.appengine.api.datastore.ReadPolicy.Consistency policy)` Provides a new Objectify instance with the specified Consistency.
`Objectify`	`deadline(Double value)` Provides a new Objectify instance with a limit, in seconds, for datastore calls.
`Deleter`	`delete()` Start a delete command chain.
`<R> R`	`execute(TxnType txnType, Work<R> work)` Executes the work with the transactional behavior defined by the parameter txnType.
`ObjectifyFactory`	`factory()` Obtain the ObjectifyFactory from which this Objectify instance was created.
`com.google.appengine.api.datastore.Transaction`	`getTransaction()` Get the underlying transaction object associated with this Objectify instance.
`boolean`	`isLoaded(Key<?> key)`
`Loader`	`load()` Start a load command chain.
`Saver`	`save()` Start a save command chain.
`<R> R`	`transact(Work<R> work)` Executes work in a transaction.
`Objectify`	`transactionless()` If you are in a transaction, this provides you an objectify instance which is outside of the current transaction and works with the session prior to the transaction start.
`<R> R`	`transactNew(int limitTries, Work<R> work)` Executes the work in a new transaction, repeating up to limitTries times when a ConcurrentModificationException is thrown.
`<R> R`	`transactNew(Work<R> work)` Executes work in a new transaction.

- Method Detail
  - load
```
Loader load()
```
    Start a load command chain. This is where you begin for any request that fetches data from the datastore: gets and queries. Note that all command objects are immutable.
    
    A quick example: Map<Key<Thing>, Thing> things = ofy.load().type(Thing.class).parent(par).ids(123L, 456L);
    
    Returns:
    the next step in the immutable command chain.
  - save
```
Saver save()
```
    Start a save command chain. Allows you to save (or re-save) entity objects. Note that all command chain objects are immutable.
    
    Saves do NOT cascade; if you wish to save an object graph, you must save each individual entity.
    
    A quick example: ofy.save().entities(e1, e2, e3).now();
    
    Returns:
    the next step in the immutable command chain.
  - delete
```
Deleter delete()
```
    Start a delete command chain. Lets you delete entities or keys. Note that all command chain objects are immutable.
    
    Deletes do NOT cascade; if you wish to delete an object graph, you must delete each individual entity.
    
    A quick example: ofy.delete().entities(e1, e2, e3).now();
    
    Returns:
    the next step in the immutable command chain.
  - factory
```
ObjectifyFactory factory()
```
    Obtain the ObjectifyFactory from which this Objectify instance was created.
    
    Returns:
    the ObjectifyFactory associated with this Objectify instance.
  - consistency
```
Objectify consistency(com.google.appengine.api.datastore.ReadPolicy.Consistency policy)
```
    Provides a new Objectify instance with the specified Consistency. Generally speaking, STRONG consistency provides more consistent results more slowly; EVENTUAL consistency produces results quickly but they might be out of date. See the Appengine Docs for more explanation.
    
    The new instance will inherit all other characteristics (transaction, cache policy, session cache contents, etc) from this instance.
    
    Parameters:
    policy - the consistency policy to use. STRONG load()s are more consistent but EVENTUAL load()s are faster.
    
    Returns:
    a new Objectify instance with the consistency policy replaced
  - deadline
```
Objectify deadline(Double value)
```
    Provides a new Objectify instance with a limit, in seconds, for datastore calls. If datastore calls take longer than this amount, a timeout exception will be thrown.
    
    The new instance will inherit all other characteristics (transaction, cache policy, session cache contents, etc) from this instance.
    
    Parameters:
    value - - limit in seconds, or null to indicate no deadline (other than the standard whole request deadline of 30s/10m).
    
    Returns:
    a new Objectify instance with the specified deadline
  - cache
```
Objectify cache(boolean value)
```
    Provides a new Objectify instance which uses (or doesn't use) a 2nd-level memcache. If true, Objectify will obey the @Cache annotation on entity classes, saving entity data to the GAE memcache service. Fetches from the datastore for @Cache entities will look in the memcache service first. This cache is shared across all versions of your application across the entire GAE cluster.
    
    Objectify instances are cache(true) by default.
    
    Returns:
    a new Objectify instance which will (or won't) use the global cache
  - getTransaction
```
com.google.appengine.api.datastore.Transaction getTransaction()
```
    Get the underlying transaction object associated with this Objectify instance. You typically do not need to use this; use transact() instead.
    
    Note that this is *not* the same as DatastoreService.getCurrentTransaction(), which uses the Low-Level API's implicit transaction management. Every transactional Objectify instance is associated with a specific Transaction object.
    
    Returns:
    the low-level transaction associated with this Objectify instance, or null if no transaction is associated with this instance.
  - transactionless
```
Objectify transactionless()
```
    If you are in a transaction, this provides you an objectify instance which is outside of the current transaction and works with the session prior to the transaction start. Inherits any settings (consistency, deadline, etc) from the present Objectify instance.
    
    If you are not in a transaction, this simply returns "this".
    
    This allows code to quickly "escape" a transactional context for the purpose of loading manipulating data without creating or affecting XG transactions.
    
    Returns:
    an Objectify instance outside of a transaction, with the session as it was before txn start.
  - transact
```
<R> R transact(Work<R> work)
```
    Executes work in a transaction. If there is already a transaction context, that context will be inherited. If there is not already a transaction context, a new transaction will be started.
    
    Within Work.run(), obtain the correct transactional Objectify instance by calling ObjectifyService.ofy()
    
    ConcurrentModificationExceptions will cause the transaction to repeat as many times as necessary to finish the job. Work MUST idempotent.
    
    Parameters:
    work - defines the work to be done in a transaction. If this method started a new transaction, it will be committed when work is complete. If transactional context was inherited, no commit is issued until the full transaction completes normally.
    
    Returns:
    the result of the work
  - transactNew
```
<R> R transactNew(Work<R> work)
```
    Executes work in a new transaction. Note that this is equivalent to transactNew(Integer.MAX_VALUE, work);
    
    ConcurrentModificationExceptions will cause the transaction to repeat as many times as necessary to finish the job. Work MUST idempotent.
    
    Within Work.run(), obtain the new transactional Objectify instance by calling ObjectifyService.ofy()
    
    Parameters:
    work - defines the work to be done in a transaction. After the method exits, the transaction will commit.
    
    Returns:
    the result of the work
  - transactNew
```
<R> R transactNew(int limitTries,
                Work<R> work)
```
    Executes the work in a new transaction, repeating up to limitTries times when a ConcurrentModificationException is thrown. This requires your Work to be idempotent; otherwise limit tries to 1.
    Within Work.run(), obtain the new transactional Objectify instance by calling ObjectifyService.ofy()
    
    Parameters:
    work - defines the work to be done in a transaction. After the method exits, the transaction will commit.
    
    Returns:
    the result of the work
  - execute
```
<R> R execute(TxnType txnType,
            Work<R> work)
```
    Executes the work with the transactional behavior defined by the parameter txnType. This is very similar to EJB semantics. The work can inherit a transaction, create a new transaction, prevent transactions, etc.
    
    This method principally exists to facilitate implementation of AOP interceptors that provide EJB-like behavior. Usually you will call transact() or transactNew() when writing code.
    
    Note that ConcurrentModificationExceptions will cause the transaction to repeat as many times as necessary to finish the job. Work MUST idempotent.
    
    Within Work.run(), obtain the correct Objectify instance by calling ObjectifyService.ofy()
    
    Parameters:
    txnType - defines what kind of transaction context the work should be executed in.
    work - defines the work to be done; possibly in a transaction, possibly not as defined by txnType
    
    Returns:
    the result of the work
  - clear
```
void clear()
```
    Clears the session; all subsequent requests (or Ref.get() calls) will go to the datastore/memcache to repopulate the session. This should rarely, if ever be necessary. Note that if you iterate query results you should only perform this action on chunk boundaries, otherwise performance will suffer. This is a "use only if you really know what you are doing" feature.
  - isLoaded
```
boolean isLoaded(Key<?> key)
```
    Returns:
    true if the key has been loaded into the session; false if loading the key would result in a datastore (or memcache) fetch.

Interface Objectify

Method Summary

Method Detail

load

save

delete

factory

consistency

deadline

cache

getTransaction

transactionless

transact

transactNew

transactNew

execute

clear

isLoaded