com.googlecode.objectify
Class ObjectifyFactory

java.lang.Object
  extended by com.googlecode.objectify.ObjectifyFactory

public class ObjectifyFactory
extends java.lang.Object

Factory which allows us to construct implementations of the Objectify interface. Just call begin().

Note that unlike the DatastoreService, there is no implicit transaction management. You either create an Objectify without a transaction (by calling begin() or you create one with a transaction (by calling beginTransaction(). If you create an Objectify with a transaction, you should use it like this:

        Objectify data = factory.beginTransaction()
        try {
                // do work
                data.getTxn().commit();
        }
        finally {
                if (data.getTxn().isActive()) data.getTxn().rollback();
        }
 

It would be fairly easy for someone to implement a ScanningObjectifyFactory on top of this class that looks for @Entity annotations based on Scannotation or Reflections, but this would add extra dependency jars and need a hook for application startup.

Author:
Jeff Schnitzer

Field Summary
protected  Conversions conversions
          All the various converters
protected  EntityMemcache entityMemcache
          Manages caching of entities at a low level
static java.lang.String MEMCACHE_NAMESPACE
          Default memcache namespace; override getRawMemcacheService() to change
protected  EntityMemcacheStats memcacheStats
          Tracks stats
protected  Registrar registrar
          Encapsulates entity registration info
 
Constructor Summary
ObjectifyFactory()
           
 
Method Summary
<T> long
allocateId(java.lang.Class<T> clazz)
          Allocates a single id from the allocator for the specified kind.
<T> long
allocateId(java.lang.Object parentKeyOrEntity, java.lang.Class<T> clazz)
          Allocates a single id from the allocator for the specified kind.
<T> com.google.appengine.api.datastore.DatastoreService.KeyRangeState
allocateIdRange(KeyRange<T> range)
          Allocates a user-specified contiguous range of unique IDs, preventing the allocator from giving them out to entities (with autogeneration) or other calls to allocate methods.
<T> KeyRange<T>
allocateIds(java.lang.Class<T> clazz, long num)
          Preallocate a contiguous range of unique ids within the namespace of the specified entity class.
<T> KeyRange<T>
allocateIds(java.lang.Object parentKeyOrEntity, java.lang.Class<T> clazz, long num)
          Preallocate a contiguous range of unique ids within the namespace of the specified entity class and the parent key.
 Objectify begin()
          Create a lightweight Objectify instance with the default options.
 Objectify begin(ObjectifyOpts opts)
           
 Objectify beginTransaction()
           
protected  ObjectifyOpts createDefaultOpts()
          Creates the default options for begin() and beginTransaction().
protected  Objectify createObjectify(com.google.appengine.api.datastore.AsyncDatastoreService ds, ObjectifyOpts opts)
          Override this in your factory if you wish to use a different impl, say, one based on the ObjectifyWrapper.
 com.google.appengine.api.datastore.AsyncDatastoreService getAsyncDatastoreService(ObjectifyOpts opts)
          Get an AsyncDatastoreService facade appropriate to the options.
 Conversions getConversions()
           
 com.google.appengine.api.datastore.DatastoreService getDatastoreService(ObjectifyOpts opts)
          Get a DatastoreService facade appropriate to the options.
<T> Key<T>
getKey(java.lang.Object keyOrEntity)
          Gets the Key given an object that might be a Key, Key, or entity.
 EntityMemcacheStats getMemcacheStats()
          Get the object that tracks memcache stats.
<T> EntityMetadata<? extends T>
getMetadata(java.lang.Class<T> clazz)
           
<T> EntityMetadata<T>
getMetadata(com.google.appengine.api.datastore.Key key)
           
<T> EntityMetadata<T>
getMetadata(Key<T> key)
           
<T> EntityMetadata<T>
getMetadata(java.lang.String kind)
          Gets metadata for the specified kind, or throws an exception if the kind is unknown
<T> EntityMetadata<T>
getMetadataForEntity(T obj)
          Named differently so you don't accidentally use the Object form
protected  com.google.appengine.api.datastore.AsyncDatastoreService getRawAsyncDatastoreService(com.google.appengine.api.datastore.DatastoreServiceConfig cfg)
          You can override this to add behavior at the raw datastoreservice level.
protected  com.google.appengine.api.datastore.DatastoreService getRawDatastoreService(com.google.appengine.api.datastore.DatastoreServiceConfig cfg)
          You can override this to add behavior at the raw datastoreservice level.
 com.google.appengine.api.datastore.Key getRawKey(java.lang.Object keyOrEntity)
          Gets the raw datstore Key given an object that might be a Key, Key, or entity.
 java.lang.String keyToString(Key<?> key)
          Converts a Key into a web-safe string suitable for http parameters in URLs.
protected  com.google.appengine.api.datastore.DatastoreServiceConfig makeConfig(ObjectifyOpts opts)
          Make a datastore service config that corresponds to the specified options.
 java.lang.Object makeFilterable(java.lang.Object keyOrEntityOrOther)
          Translate Key or Entity objects into something that can be used in a filter clause.
<T> void
register(java.lang.Class<T> clazz)
          All POJO entity classes which are to be managed by Objectify must be registered first.
<T> Key<T>
stringToKey(java.lang.String stringifiedKey)
          Converts a String generated with keyToString() back into an Objectify Key.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MEMCACHE_NAMESPACE

public static final java.lang.String MEMCACHE_NAMESPACE
Default memcache namespace; override getRawMemcacheService() to change

See Also:
Constant Field Values

registrar

protected Registrar registrar
Encapsulates entity registration info


conversions

protected Conversions conversions
All the various converters


memcacheStats

protected EntityMemcacheStats memcacheStats
Tracks stats


entityMemcache

protected EntityMemcache entityMemcache
Manages caching of entities at a low level

Constructor Detail

ObjectifyFactory

public ObjectifyFactory()
Method Detail

createDefaultOpts

protected ObjectifyOpts createDefaultOpts()
Creates the default options for begin() and beginTransaction(). You can override this if, for example, you wanted to enable session caching by default.


createObjectify

protected Objectify createObjectify(com.google.appengine.api.datastore.AsyncDatastoreService ds,
                                    ObjectifyOpts opts)
Override this in your factory if you wish to use a different impl, say, one based on the ObjectifyWrapper.

Parameters:
ds - the DatastoreService
opts - the options for creating this Objectify
Returns:
an instance of Objectify configured appropriately

makeConfig

protected com.google.appengine.api.datastore.DatastoreServiceConfig makeConfig(ObjectifyOpts opts)
Make a datastore service config that corresponds to the specified options. Note that not all options are defined by the config; some options (e.g. caching) have no analogue in the native datastore.


getDatastoreService

public com.google.appengine.api.datastore.DatastoreService getDatastoreService(ObjectifyOpts opts)
Get a DatastoreService facade appropriate to the options. Note that Objectify does not itself use DatastoreService; this method solely exists to support Objectify.getDatastore().

Returns:
a DatastoreService configured per the specified options.

getAsyncDatastoreService

public com.google.appengine.api.datastore.AsyncDatastoreService getAsyncDatastoreService(ObjectifyOpts opts)
Get an AsyncDatastoreService facade appropriate to the options. All Objectify datastore interaction goes through an AsyncDatastoreService, even the synchronous methods. The GAE SDK works the same way; DatastoreService is a facade around AsyncDatastoreService.

Returns:
an AsyncDatastoreService configured per the specified options.

getRawDatastoreService

protected com.google.appengine.api.datastore.DatastoreService getRawDatastoreService(com.google.appengine.api.datastore.DatastoreServiceConfig cfg)
You can override this to add behavior at the raw datastoreservice level.


getRawAsyncDatastoreService

protected com.google.appengine.api.datastore.AsyncDatastoreService getRawAsyncDatastoreService(com.google.appengine.api.datastore.DatastoreServiceConfig cfg)
You can override this to add behavior at the raw datastoreservice level.


begin

public Objectify begin()
Create a lightweight Objectify instance with the default options. Equivalent to begin(new ObjectifyOpts()).


begin

public Objectify begin(ObjectifyOpts opts)
Returns:
an Objectify from the DatastoreService with the specified options. This is a lightweight operation and can be used freely.

beginTransaction

public Objectify beginTransaction()
Returns:
an Objectify which uses a transaction. The transaction supports cross-group access, but this has no extra overhead for a single-entity-group transaction.

register

public <T> void register(java.lang.Class<T> clazz)

All POJO entity classes which are to be managed by Objectify must be registered first. This method must be called in a single-threaded mode sometime around application initialization.


getMemcacheStats

public EntityMemcacheStats getMemcacheStats()
Get the object that tracks memcache stats.


getMetadata

public <T> EntityMetadata<T> getMetadata(com.google.appengine.api.datastore.Key key)
Returns:
the metadata for a kind of entity based on its key
Throws:
java.lang.IllegalArgumentException - if the kind has not been registered

getMetadata

public <T> EntityMetadata<T> getMetadata(Key<T> key)
Returns:
the metadata for a kind of entity based on its key
Throws:
java.lang.IllegalArgumentException - if the kind has not been registered

getMetadata

public <T> EntityMetadata<? extends T> getMetadata(java.lang.Class<T> clazz)
Returns:
the metadata for a kind of typed object
Throws:
java.lang.IllegalArgumentException - if the kind has not been registered

getMetadata

public <T> EntityMetadata<T> getMetadata(java.lang.String kind)
Gets metadata for the specified kind, or throws an exception if the kind is unknown


getMetadataForEntity

public <T> EntityMetadata<T> getMetadataForEntity(T obj)
Named differently so you don't accidentally use the Object form

Returns:
the metadata for a kind of typed object.
Throws:
java.lang.IllegalArgumentException - if the kind has not been registered

getKey

public <T> Key<T> getKey(java.lang.Object keyOrEntity)

Gets the Key given an object that might be a Key, Key, or entity.

Parameters:
keyOrEntity - must be a Key, Key, or registered entity.
Throws:
java.lang.NullPointerException - if keyOrEntity is null
java.lang.IllegalArgumentException - if keyOrEntity is not a Key, Key, or registered entity

getRawKey

public com.google.appengine.api.datastore.Key getRawKey(java.lang.Object keyOrEntity)

Gets the raw datstore Key given an object that might be a Key, Key, or entity.

Parameters:
keyOrEntity - must be a Key, Key, or registered entity.
Throws:
java.lang.NullPointerException - if keyOrEntity is null
java.lang.IllegalArgumentException - if keyOrEntity is not a Key, Key, or registered entity

makeFilterable

public java.lang.Object makeFilterable(java.lang.Object keyOrEntityOrOther)
Translate Key or Entity objects into something that can be used in a filter clause. Anything unknown (including null) is simply returned as-is and we hope that the filter works.

Returns:
whatever can be put into a filter clause.

keyToString

public java.lang.String keyToString(Key<?> key)

Converts a Key into a web-safe string suitable for http parameters in URLs. Note that you can convert back and forth with the keyToString() and stringToKey() methods.

The String is actually generated by using the KeyFactory keyToString() method on a raw version of the datastore key. You can, if you wanted, use these web safe strings interchangeably.

Parameters:
key - is any Objectify key
Returns:
a simple String which does not need urlencoding

stringToKey

public <T> Key<T> stringToKey(java.lang.String stringifiedKey)
Converts a String generated with keyToString() back into an Objectify Key. The String could also have been generated by the GAE KeyFactory.

Parameters:
stringifiedKey - is generated by either ObjectifyFactory.keyToString() or KeyFactory.keyToString().
Returns:
a Key

allocateId

public <T> long allocateId(java.lang.Class<T> clazz)
Allocates a single id from the allocator for the specified kind. Safe to use in concert with the automatic generator. This is just a convenience method for allocateIds().

Parameters:
clazz - must be a registered entity class with a Long or long id field.

allocateId

public <T> long allocateId(java.lang.Object parentKeyOrEntity,
                           java.lang.Class<T> clazz)
Allocates a single id from the allocator for the specified kind. Safe to use in concert with the automatic generator. This is just a convenience method for allocateIds(). Note that the id is only unique within the parent, not across the entire kind.

Parameters:
parentKeyOrEntity - must be a legitimate parent for the class type. It need not point to an existent entity, but it must be the correct type for clazz.
clazz - must be a registered entity class with a Long or long id field, and a parent key of the correct type.

allocateIds

public <T> KeyRange<T> allocateIds(java.lang.Class<T> clazz,
                                   long num)
Preallocate a contiguous range of unique ids within the namespace of the specified entity class. These ids can be used in concert with the normal automatic allocation of ids when put()ing entities with null Long id fields.

Parameters:
clazz - must be a registered entity class with a Long or long id field.
num - must be >= 1 and <= 1 billion

allocateIds

public <T> KeyRange<T> allocateIds(java.lang.Object parentKeyOrEntity,
                                   java.lang.Class<T> clazz,
                                   long num)
Preallocate a contiguous range of unique ids within the namespace of the specified entity class and the parent key. These ids can be used in concert with the normal automatic allocation of ids when put()ing entities with null Long id fields.

Parameters:
parentKeyOrEntity - must be a legitimate parent for the class type. It need not point to an existent entity, but it must be the correct type for clazz.
clazz - must be a registered entity class with a Long or long id field, and a parent key of the correct type.
num - must be >= 1 and <= 1 billion

allocateIdRange

public <T> com.google.appengine.api.datastore.DatastoreService.KeyRangeState allocateIdRange(KeyRange<T> range)
Allocates a user-specified contiguous range of unique IDs, preventing the allocator from giving them out to entities (with autogeneration) or other calls to allocate methods. This lets you specify a specific range to block out (for example, you are bulk-loading a collection of pre-existing entities). If you don't care about what id is allocated, use one of the other allocate methods.


getConversions

public Conversions getConversions()
Returns:
the repository of Converter objects


Copyright © 2011 Jeff Schnitzer and a gang of pirates. All Rights Reserved. Build version: 3.1