com.googlecode.objectify
Class ObjectifyFactory

java.lang.Object
  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();
        }
 

ObjectifyFactory is designed to be subclassed; much default behavior can be changed by overriding methods. In particular, see createObjectify(), construct(), getAsyncDatastoreService().

Author:

Jeff Schnitzer

Field Summary

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
protected TranslatorRegistry	translators All the various loaders

Constructor Summary

ObjectifyFactory()

Method Summary

<T> Key<T>	allocateId(java.lang.Class<T> clazz) Allocates a single id from the allocator for the specified kind.
<T> Key<T>	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() This is the beginning of any Objectify session.
<T> T	construct(java.lang.Class<T> type) Construct an instance of the specified type.
<T extends java.util.Collection<?>> T	constructCollection(java.lang.Class<T> type, int size) Construct a collection of the specified type and the specified size for use on a POJO field.
<T extends java.util.Map<?,?>> T	constructMap(java.lang.Class<T> type) Construct a map of the specified type for use on a POJO field.
com.google.appengine.api.datastore.AsyncDatastoreService	createAsyncDatastoreService(com.google.appengine.api.datastore.DatastoreServiceConfig cfg, boolean globalCache) Get an AsyncDatastoreService facade appropriate to the options.
protected com.google.appengine.api.datastore.AsyncDatastoreService	createRawAsyncDatastoreService(com.google.appengine.api.datastore.DatastoreServiceConfig cfg) You can override this to add behavior at the raw datastoreservice level.
<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<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, returning null if nothing registered
<T> EntityMetadata<T>	getMetadataForEntity(T obj) Named differently so you don't accidentally use the Object form
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.
TranslatorRegistry	getTranslators() Gets the master list of all registered TranslatorFactory objects.
<T> void	register(java.lang.Class<T> clazz) All POJO entity classes which are to be managed by Objectify must be registered first.

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

translators

protected TranslatorRegistry translators

All the various loaders

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

construct

public <T> T construct(java.lang.Class<T> type)

Construct an instance of the specified type. Objectify uses this method whenever possible to create instances of entities, condition classes, or other types; by overriding this method you can substitute Guice or other dependency injection mechanisms. By default it constructs with a simple no-args constructor.

constructCollection

public <T extends java.util.Collection<?>> T constructCollection(java.lang.Class<T> type,
                                                                 int size)

Construct a collection of the specified type and the specified size for use on a POJO field. You can override this with Guice or whatnot.

The default is to call construct(Class), with one twist - if a Set, SortedSet, or List interface is presented, Objectify will construct a HashSet, TreeSet, or ArrayList (respectively). If you override this method with dependency injection and you use uninitialized fields of these interface types in your entity pojos, you will need to bind these interfaces to concrete types.

constructMap

public <T extends java.util.Map<?,?>> T constructMap(java.lang.Class<T> type)

Construct a map of the specified type for use on a POJO field. You can override this with Guice or whatnot.

The default is to call construct(Class), with one twist - if a Map or SortedMap List interface is presented, Objectify will construct a HashMap or TreeMap (respectively). If you override this method with dependency injection and you use uninitialized fields of these interface types in your entity pojos, you will need to bind these interfaces to concrete types.

createAsyncDatastoreService

public com.google.appengine.api.datastore.AsyncDatastoreService createAsyncDatastoreService(com.google.appengine.api.datastore.DatastoreServiceConfig cfg,
                                                                                            boolean globalCache)

Get an AsyncDatastoreService facade appropriate to the options. All Objectify datastore interaction goes through an AsyncDatastoreService. This might or might not produce a CachingAsyncDatastoreService.

Returns:

an AsyncDatastoreService configured per the specified options.

createRawAsyncDatastoreService

protected com.google.appengine.api.datastore.AsyncDatastoreService createRawAsyncDatastoreService(com.google.appengine.api.datastore.DatastoreServiceConfig cfg)

You can override this to add behavior at the raw datastoreservice level.

begin

public Objectify begin()

This is the beginning of any Objectify session. It creates an Objectify instance with the default options, unless you override this method to alter the options. You can also override this method to produce a wholly different Objectify implementation (possibly using ObjectifyWrapper).

The default options are:

• Do NOT begin a transaction.
• Do NOT use a session cache.
• DO use a global cache.
• Use STRONG consistency.
• Apply no deadline to calls.

Returns:

a new Objectify instance

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.

Any extra translators must be added to the TranslatorRegistry *before* entity classes are registered.

Attempts to re-register entity classes are ignored.

getMemcacheStats

public EntityMemcacheStats getMemcacheStats()

Get the object that tracks memcache stats.

getMetadata

public <T> EntityMetadata<T> getMetadata(java.lang.Class<T> clazz)
                              throws java.lang.IllegalArgumentException

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(com.google.appengine.api.datastore.Key key)

Returns:

the metadata for a kind of entity based on its key, or null if the kind was not registered

getMetadata

public <T> EntityMetadata<T> getMetadata(Key<T> key)

Returns:

the metadata for a kind of entity based on its key, or null if the kind was not registered

getMetadata

public <T> EntityMetadata<T> getMetadata(java.lang.String kind)

Gets metadata for the specified kind, returning null if nothing registered

Returns:

null if the kind is not registered.

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

allocateId

public <T> Key<T> 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.

Returns:

a key with an id that is unique to the kind

allocateId

public <T> Key<T> 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.

Returns:

a key with a new id unique to the kind and parent

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.

getTranslators

public TranslatorRegistry getTranslators()

Gets the master list of all registered TranslatorFactory objects. By adding Translators, Objectify can process additional field types which are not part of the standard GAE SDK. You must add translators *before* registering entity pojo classes.

Returns:

the repository of TranslatorFactory objects, to which you can optionally add translators