Package com.googlecode.objectify.impl

Class ObjectifyImpl<O extends Objectify>

java.lang.Object
com.googlecode.objectify.impl.ObjectifyImpl<O>
All Implemented Interfaces:
Objectify, Cloneable
public class ObjectifyImpl<O extends Objectify>
extends Object
implements Objectify, Cloneable

Implementation of the Objectify interface. This is also suitable for subclassing; you can return your own subclass by overriding ObjectifyFactory.begin().

Note we *always* use the AsyncDatastoreService methods that use transactions to avoid the confusion of implicit transactions.

Author:
Jeff Schnitzer

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected boolean
    cache
    Our options
    protected com.google.appengine.api.datastore.ReadPolicy.Consistency
    consistency
     
    protected Double
    deadline
     
    protected ObjectifyFactory
    factory
    The factory that produced us
    protected boolean
    mandatoryTransactions
     
    protected Transactor<O>
    transactor
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    ObjectifyImpl​(ObjectifyImpl<O> other)
    Copy constructor
    ObjectifyImpl​(ObjectifyFactory fact)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    O
    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.
    protected ObjectifyImpl<O>
    clone()
     
    O
    consistency​(com.google.appengine.api.datastore.ReadPolicy.Consistency value)
    Provides a new Objectify instance with the specified Consistency.
    protected com.google.appengine.api.datastore.AsyncDatastoreService
    createAsyncDatastoreService()
    Make a datastore service config that corresponds to our options.
    protected com.google.appengine.api.datastore.DatastoreServiceConfig
    createDatastoreServiceConfig()
    Make a datastore service config that corresponds to our options.
    protected WriteEngine
    createWriteEngine()
    Use this once for one operation and then throw it away
    O
    deadline​(Double value)
    Provides a new Objectify instance with a limit, in seconds, for datastore calls.
    Deferred
    defer()
    Start a deferred command chain, which lets you make multiple save or delete calls on a single entity without incurring multiple datastore operations.
    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.
    void
    flush()
    Synchronously flushes any deferred operations to the datastore.
    boolean
    getCache()
     
    protected Session
    getSession()
     
    TransactionImpl
    getTransaction()
    Get the underlying transaction object associated with this Objectify instance.
    boolean
    isLoaded​(Key<?> key)
     
    Loader
    load()
    Start a load command chain.
    protected Object
    makeFilterable​(Object value)
    Translates the value of a filter clause into something the datastore understands.
    O
    mandatoryTransactions​(boolean value)
    Provides a new Objectify instance which throws an exception whenever save() or delete() is called from outside a transaction context.
    Saver
    save()
    Start a save command chain.
    <R> R
    transact​(Work<R> work)
    Executes work in a transaction.
    void
    transact​(Runnable work)
    Exactly the same behavior as the Work version, but doesn't return anything.
    O
    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.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • factory

      protected ObjectifyFactory factory
      The factory that produced us

    • cache

      protected boolean cache
      Our options

    • consistency

      protected com.google.appengine.api.datastore.ReadPolicy.Consistency consistency

    • deadline

      protected Double deadline

    • mandatoryTransactions

      protected boolean mandatoryTransactions

    • transactor

      protected Transactor<O extends Objectify> transactor

  • Constructor Details

  • Method Details

    • factory

      public ObjectifyFactory factory()
      Description copied from interface: Objectify
      Obtain the ObjectifyFactory from which this Objectify instance was created.
      Specified by:
      factory in interface Objectify
      Returns:
      the ObjectifyFactory associated with this Objectify instance.

    • load

      public Loader load()
      Description copied from interface: Objectify

      Start a load command chain. This is where you begin for any request that fetches data from the datastore: gets and queries.

      A quick example: Map<Key<Thing>, Thing> things = ofy().load().type(Thing.class).parent(par).ids(123L, 456L);

      All command objects are immutable; this method returns a new object rather than modifying the current command object.

      Specified by:
      load in interface Objectify
      Returns:
      the next step in the immutable command chain.

    • save

      public Saver save()
      Description copied from interface: Objectify

      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();

      All command objects are immutable; this method returns a new object rather than modifying the current command object.

      Specified by:
      save in interface Objectify
      Returns:
      the next step in the immutable command chain.

    • delete

      public Deleter delete()
      Description copied from interface: Objectify

      Start a delete command chain. Lets you delete entities or keys.

      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();

      All command objects are immutable; this method returns a new object rather than modifying the current command object.

      Specified by:
      delete in interface Objectify
      Returns:
      the next step in the immutable command chain.

    • defer

      public Deferred defer()
      Description copied from interface: Objectify

      Start a deferred command chain, which lets you make multiple save or delete calls on a single entity without incurring multiple datastore operations. Deferred operations are executed at the end of a unit-of-work (transaction, or http request if not in a transaction).

      Deferred operations are reflected in the session cache immediately. However query operations may not reflect these changes. For example, newly indexed entities may not show up, even with an otherwise strongly consistent ancestor query. This should not be surprising since the actual save operation has not occurred yet.

      In the case of deferred save() and delete() operations on the same entity, the last one wins.

      Specified by:
      defer in interface Objectify
      Returns:
      the next step in the immutable command chain.

    • consistency

      public O consistency​(com.google.appengine.api.datastore.ReadPolicy.Consistency value)
      Description copied from interface: Objectify

      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.

      All command objects are immutable; this method returns a new object rather than modifying the current command object.

      Specified by:
      consistency in interface Objectify
      Parameters:
      value - the consistency policy to use. STRONG load()s are more consistent but EVENTUAL load()s are faster.
      Returns:
      a new immutable Objectify instance with the consistency policy replaced

    • deadline

      public O deadline​(Double value)
      Description copied from interface: Objectify

      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.

      All command objects are immutable; this method returns a new object rather than modifying the current command object.

      Specified by:
      deadline in interface Objectify
      Parameters:
      value - - limit in seconds, or null to indicate no deadline (other than the standard whole request deadline of 30s/10m).
      Returns:
      a new immutable Objectify instance with the specified deadline

    • cache

      public O cache​(boolean value)
      Description copied from interface: Objectify

      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.

      All command objects are immutable; this method returns a new object rather than modifying the current command object.

      Specified by:
      cache in interface Objectify
      Returns:
      a new immutable Objectify instance which will (or won't) use the global cache

    • mandatoryTransactions

      public O mandatoryTransactions​(boolean value)
      Description copied from interface: Objectify

      Provides a new Objectify instance which throws an exception whenever save() or delete() is called from outside a transaction context. This is a reasonable sanity check for most business workloads; you may wish to enable it globally by overriding ObjectifyFactory.begin() to twiddle this flag on the returned object.

      Objectify instances are mandatoryTransactions(false) by default.

      All command objects are immutable; this method returns a new object rather than modifying the current command object.

      Specified by:
      mandatoryTransactions in interface Objectify
      Returns:
      a new immutable Objectify instance which will (or won't) require transactions for save() and delete().

    • transactionless

      public O transactionless()
      Description copied from interface: Objectify

      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.

      All command objects are immutable; this method returns a new object instead of modifying the current command object.

      Specified by:
      transactionless in interface Objectify
      Returns:
      an immutable Objectify instance outside of a transaction, with the session as it was before txn start.

    • clone

      protected ObjectifyImpl<O> clone()
      Overrides:
      clone in class Object

    • getTransaction

      public TransactionImpl getTransaction()
      Description copied from interface: Objectify

      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.

      Specified by:
      getTransaction in interface Objectify
      Returns:
      the low-level transaction associated with this Objectify instance, or null if no transaction is associated with this instance.

    • execute

      public <R> R execute​(TxnType txnType, Work<R> work)
      Description copied from interface: Objectify

      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()

      Specified by:
      execute in interface Objectify
      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

    • transact

      public <R> R transact​(Work<R> work)
      Description copied from interface: Objectify

      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.

      Specified by:
      transact in interface Objectify
      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

    • transact

      public void transact​(Runnable work)
      Description copied from interface: Objectify

      Exactly the same behavior as the Work version, but doesn't return anything. Convenient for Java8 so you don't have to return something from the lambda.

      Specified by:
      transact in interface Objectify

    • transactNew

      public <R> R transactNew​(Work<R> work)
      Description copied from interface: Objectify

      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()

      Specified by:
      transactNew in interface Objectify
      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

      public <R> R transactNew​(int limitTries, Work<R> work)
      Description copied from interface: Objectify

      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()

      Specified by:
      transactNew in interface Objectify
      Parameters:
      limitTries - is the max # of tries. Must be > 0. A value of 1 means "try only once".
      work - defines the work to be done in a transaction. After the method exits, the transaction will commit.
      Returns:
      the result of the work

    • clear

      public void clear()
      Description copied from interface: Objectify

      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.

      Specified by:
      clear in interface Objectify

    • createDatastoreServiceConfig

      protected com.google.appengine.api.datastore.DatastoreServiceConfig createDatastoreServiceConfig()
      Make a datastore service config that corresponds to our options.

    • createAsyncDatastoreService

      protected com.google.appengine.api.datastore.AsyncDatastoreService createAsyncDatastoreService()
      Make a datastore service config that corresponds to our options.

    • createWriteEngine

      protected WriteEngine createWriteEngine()
      Use this once for one operation and then throw it away
      Returns:
      a fresh engine that handles fundamental datastore operations for saving and deleting

    • makeFilterable

      protected Object makeFilterable​(Object value)

      Translates the value of a filter clause into something the datastore understands. Key goes to native Key, entities go to native Key, java.sql.Date goes to java.util.Date, etc. It uses the same translation system that is used for standard entity fields, but does no checking to see if the value is appropriate for the field.

      Unrecognized types are returned as-is.

      A future version of this method might check for type validity.

      Returns:
      whatever can be put into a filter clause.

    • getSession

      protected Session getSession()

    • getCache

      public boolean getCache()
      Returns:
      true if cache is enabled

    • isLoaded

      public boolean isLoaded​(Key<?> key)
      Specified by:
      isLoaded in interface Objectify
      Returns:
      true if the key has been loaded into the session; false if loading the key would result in a datastore (or memcache) fetch.

    • flush

      public void flush()
      Description copied from interface: Objectify
      Synchronously flushes any deferred operations to the datastore. Objectify does this for you at the end of transactions and requests, but if you need data to be written immediately - say, you're about to perform a strongly-consistent ancestor query and you need to see the updated indexes immediately - you can call this method. If there are no deferred operations, this does nothing.
      Specified by:
      flush in interface Objectify