Package com.googlecode.objectify.impl

Class LoaderImpl<L extends Loader>

java.lang.Object

com.googlecode.objectify.impl.SimpleQueryImpl<T>

com.googlecode.objectify.impl.LoaderImpl<L>

All Implemented Interfaces:

com.google.appengine.api.datastore.QueryResultIterable<Object>, Loader, QueryExecute<Object>, SimpleQuery<Object>, Cloneable, Iterable<Object>

public class LoaderImpl<L extends Loader>
extends SimpleQueryImpl<T>
implements Loader, Cloneable

Implementation of the Loader interface. This is also suitable for subclassing; you can return your own subclass by overriding ObjectifyImpl.load().

Author:

Jeff Schnitzer

Field Summary

Fields

Modifier and Type	Field	Description
protected LoadArrangement	loadArrangement
protected ObjectifyImpl<?>	ofy

Fields inherited from class com.googlecode.objectify.impl.SimpleQueryImpl

loader

Constructor Summary

Constructors

Constructor	Description
LoaderImpl(ObjectifyImpl<?> ofy)

Method Summary

Modifier and Type	Method	Description
protected LoaderImpl<L>	clone()
int	count()	Count the total number of values in the result.
<E> Map<Key<E>,E>	entities(E... entities)	A convenient substitute for entities(Iterable)
<E> Map<Key<E>,E>	entities(Iterable<E> values)	Load multiple entities from the datastore in a batch.
<E> LoadResult<E>	entity(E entity)	Load a single entity which has the same id/parent as the specified entity.
LoadResult<T>	first()	Gets the first entity in the result set.
<T> T	fromEntity(com.google.appengine.api.datastore.Entity entity)	Convert a native datastore Entity into a typed POJO.
Set<Class<?>>	getLoadGroups()
Objectify	getObjectify()
ObjectifyImpl<?>	getObjectifyImpl()
L	group(Class<?>... groups)	Enables one or more fetch groups.
com.google.appengine.api.datastore.QueryResultIterable<T>	iterable()	Starts an asynchronous query which will return entities.
com.google.appengine.api.datastore.QueryResultIterator<T>	iterator()
<E> LoadResult<E>	key(Key<E> key)	Load a single entity by key.
<E> Map<Key<E>,E>	keys(Key<? extends E>... keys)	A convenient substitute for keys(Iterable)
<E> Map<Key<E>,E>	keys(Iterable<Key<E>> keys)	Load multiple entities by key from the datastore in a batch.
<E> LoadType<E>	kind(String kind)	Restricts the find operation to entities of a particular kind.
List<T>	list()	Execute the query and get the results as a List.
<E> E	now(Key<E> key)	Get the entity for a key immediately.
<E> LoadResult<E>	ref(Ref<E> ref)	Load a single entity ref.
<E> Map<Key<E>,E>	refs(Ref<? extends E>... refs)	A convenient substitute for refs(Iterable)
<E> Map<Key<E>,E>	refs(Iterable<Ref<E>> refs)	Load multiple refs in a batch operation.
<E> LoadType<E>	type(Class<E> type)	Restricts the find operation to entities of a particular type.
<E> LoadResult<E>	value(Object key)	Load a single entity given any of a variety of acceptable key-like structures.
<E> Map<Key<E>,E>	values(Iterable<?> values)	Fetch multiple entities from the datastore in a batch.
<E> Map<Key<E>,E>	values(Object... values)	A convenient substitute for values(Iterable)

Methods inherited from class com.googlecode.objectify.impl.SimpleQueryImpl

ancestor, chunk, chunkAll, distinct, endAt, filterKey, filterKey, hybrid, keys, limit, offset, orderKey, project, reverse, startAt

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface com.googlecode.objectify.cmd.QueryExecute

first, iterable, list

Methods inherited from interface com.google.appengine.api.datastore.QueryResultIterable

iterator

Methods inherited from interface com.googlecode.objectify.cmd.SimpleQuery

ancestor, chunk, chunkAll, count, distinct, endAt, filterKey, filterKey, hybrid, keys, limit, offset, orderKey, project, reverse, startAt, toString

Field Detail

ofy

protected ObjectifyImpl<?> ofy

loadArrangement

protected LoadArrangement loadArrangement

Constructor Detail

LoaderImpl

public LoaderImpl(ObjectifyImpl<?> ofy)

Method Detail

group

public L group(Class<?>... groups)

Description copied from interface: Loader

Enables one or more fetch groups. This will cause any entity fields (or Ref fields) which are annotated with @Load(XYZGroup.class) to be fetched along with your entities. The class definition can be any arbitrary class, but inheritance is respected - if you have a class Foo extends Bar, then group(Foo.class) will cause loading of all @Load(Bar.class) properties.

Calling this method multiple times is the same as passing all the groups into one call.

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

Specified by:

group in interface Loader

Parameters:

groups - are one or more load groups to enable. They can be any arbitrary class.

Returns:

a continuation of the immutable command pattern, enabled for fetching this group.

type

public <E> LoadType<E> type(Class<E> type)

Description copied from interface: Loader

Restricts the find operation to entities of a particular type. The type may be the base of a polymorphic class hierarchy. This is optional.

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

Specified by:

type in interface Loader

Parameters:

type - is the type of entity (or entities) to retrieve, possibly a base class for a polymorphic hierarchy

Returns:

the next step in the immutable command chain, which allows you to start a query or define keys for a batch get.

kind

public <E> LoadType<E> kind(String kind)

Description copied from interface: Loader

Restricts the find operation to entities of a particular kind. This is similar to type() but lets you specify any arbitrary kind string. You'll typically only use this if you are also working with the low level api directly.

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

Specified by:

kind in interface Loader

Parameters:

kind - is the kind of entity (or entities) to retrieve

Returns:

the next step in the immutable command chain, which allows you to start a query or define keys for a batch get.

ref

public <E> LoadResult<E> ref(Ref<E> ref)

Description copied from interface: Loader

Load a single entity ref. This starts an asynchronous fetch operation.

Since fetching is asynchronous, datastore exceptions (DatastoreTimeoutException, ConcurrentModificationException, DatastoreFailureException) can be thrown from Result operations.

Specified by:

ref in interface Loader

Parameters:

ref - holds the key to fetch and will receive the asynchronous result.

Returns:

a result which can materialize the entity.

refs

public <E> Map<Key<E>,E> refs(Ref<? extends E>... refs)

Description copied from interface: Loader

A convenient substitute for refs(Iterable)

Specified by:

refs in interface Loader

refs

public <E> Map<Key<E>,E> refs(Iterable<Ref<E>> refs)

Description copied from interface: Loader

Load multiple refs in a batch operation. This starts an asynchronous fetch.

Since fetching is asynchronous, datastore exceptions (DatastoreTimeoutException, ConcurrentModificationException, DatastoreFailureException) can be thrown from the map operations.

Specified by:

refs in interface Loader

Parameters:

refs - provide the keys to fetch and will receive the asynchronous result.

Returns:

as an alternative to accessing the Refs directly, a Map of the asynchronous result.

key

public <E> LoadResult<E> key(Key<E> key)

Description copied from interface: Loader

Load a single entity by key. This starts an asynchronous fetch.

Since fetching is asynchronous, datastore exceptions (DatastoreTimeoutException, ConcurrentModificationException, DatastoreFailureException) can be thrown from Result operations.

Specified by:

key in interface Loader

Parameters:

key - defines the entity to fetch

Returns:

a result which can materialize the entity

entity

public <E> LoadResult<E> entity(E entity)

Description copied from interface: Loader

Load a single entity which has the same id/parent as the specified entity. This starts an asynchronous fetch.

This is a shortcut for key(Key.create(entity)).

Since fetching is asynchronous, datastore exceptions (DatastoreTimeoutException, ConcurrentModificationException, DatastoreFailureException) may be thrown from Result operations.

Specified by:

entity in interface Loader

Parameters:

entity - defines the entity to fetch; it must be of a registered entity type and have valid id/parent fields.

Returns:

a result which can materialize the entity

value

public <E> LoadResult<E> value(Object key)

Description copied from interface: Loader

Load a single entity given any of a variety of acceptable key-like structures. This starts an asynchronous fetch.

The parameter can be any key-like structure, including:

• Standard Objectify Key objects.
• Native datastore Key objects.
• Ref objects.
• Registered entity instances which have id and parent fields populated.

Since fetching is asynchronous, datastore exceptions (DatastoreTimeoutException, ConcurrentModificationException, DatastoreFailureException) may be thrown from Result operations.

Specified by:

value in interface Loader

Parameters:

key - defines the entity to fetch; can be anything that represents a key structure

Returns:

a Ref which holds the asynchronous result

keys

public <E> Map<Key<E>,E> keys(Key<? extends E>... keys)

Description copied from interface: Loader

A convenient substitute for keys(Iterable)

Specified by:

keys in interface Loader

keys

public <E> Map<Key<E>,E> keys(Iterable<Key<E>> keys)

Description copied from interface: Loader

Load multiple entities by key from the datastore in a batch. This starts an asynchronous fetch.

Since fetching is asynchronous, datastore exceptions (DatastoreTimeoutException, ConcurrentModificationException, DatastoreFailureException) will be thrown when the Map is accessed.

Specified by:

keys in interface Loader

Parameters:

keys - are the keys to fetch

Returns:

a Map of the asynchronous result. The fetch will be completed when the Map is first accessed.

entities

public <E> Map<Key<E>,E> entities(E... entities)

Description copied from interface: Loader

A convenient substitute for entities(Iterable)

Specified by:

entities in interface Loader

entities

public <E> Map<Key<E>,E> entities(Iterable<E> values)

Description copied from interface: Loader

Load multiple entities from the datastore in a batch. This starts an asynchronous fetch.

Since fetching is asynchronous, datastore exceptions (DatastoreTimeoutException, ConcurrentModificationException, DatastoreFailureException) may be thrown when the Map is accessed.

Specified by:

entities in interface Loader

Parameters:

values - must be a list of objects which belong to registered entity types, and must have id & parent fields properly set.

Returns:

a Map of the asynchronous result. The fetch will be completed when the Map is first accessed.

values

public <E> Map<Key<E>,E> values(Object... values)

Description copied from interface: Loader

A convenient substitute for values(Iterable)

Specified by:

values in interface Loader

values

public <E> Map<Key<E>,E> values(Iterable<?> values)

Description copied from interface: Loader

Fetch multiple entities from the datastore in a batch. This starts an asynchronous fetch.

The parameters can be any mix of key-like structures, including:

• Standard Objectify Key objects.
• Native datastore Key objects.
• Ref objects.
• Registered entity instances which have id and parent fields populated.

Since fetching is asynchronous, datastore exceptions (DatastoreTimeoutException, ConcurrentModificationException, DatastoreFailureException) may be thrown when the Map is accessed.

Specified by:

values in interface Loader

Parameters:

values - defines a possibly heterogeneous mixture of Key, Ref, native datastore Key, or registered entity instances with valid id/parent fields.

Returns:

a Map of the asynchronous result. The fetch will be completed when the Map is first accessed.

getObjectify

public Objectify getObjectify()

Specified by:

getObjectify in interface Loader

Returns:

the parent Objectify instance

getLoadGroups

public Set<Class<?>> getLoadGroups()

Specified by:

getLoadGroups in interface Loader

Returns:

the currently enabled load groups in an unmodifiable list

getObjectifyImpl

public ObjectifyImpl<?> getObjectifyImpl()

now

public <E> E now(Key<E> key)

Description copied from interface: Loader

Get the entity for a key immediately. You rarely, if ever, should want to use this; it exists to support Ref behavior. Value will be loaded from the session if available, but will go to the datastore if necessary. It is synchronous.

Specified by:

now in interface Loader

fromEntity

public <T> T fromEntity(com.google.appengine.api.datastore.Entity entity)

Description copied from interface: Loader

Convert a native datastore Entity into a typed POJO. This is like a load() operation except that you start with the native datastore type instead of fetching it from the datastore. However, note that because of @Load annotations, it is possible that datastore operations will be executed during the translation.

Specified by:

fromEntity in interface Loader

Parameters:

entity - is a native datastore entity which has an appropriate kind registered in the ObjectifyFactory.

Returns:

the POJO equivalent, just as if you had loaded the entity directly from Objectify.

clone

protected LoaderImpl<L> clone()

Overrides:

clone in class Object

first

public LoadResult<T> first()

Description copied from interface: QueryExecute

Gets the first entity in the result set. Obeys the offset value.

Returns:

an asynchronous result containing the first result. The result will hold null if the result set is empty.

iterator

public com.google.appengine.api.datastore.QueryResultIterator<T> iterator()

iterable

public com.google.appengine.api.datastore.QueryResultIterable<T> iterable()

Description copied from interface: QueryExecute

Starts an asynchronous query which will return entities.

Note that since the Query itself is QueryResultIterable, you can iterate on the query object itself. However, if you want to start an async query and iterate on it later, you can use this method.

count

public int count()

Description copied from interface: SimpleQuery

Count the total number of values in the result. limit and offset are obeyed. This is somewhat faster than fetching, but the time still grows with the number of results. The datastore actually walks through the result set and counts for you.

Immediately executes the query; there is no async version of this method.

WARNING: Each counted entity is billed as a "datastore minor operation". Even though these are free, they may take significant time because they require an index walk.

list

public List<T> list()

Description copied from interface: QueryExecute

Execute the query and get the results as a List. The list will be equivalent to a simple ArrayList; you can iterate through it multiple times without incurring additional datastore cost.

Note that you must be careful about limit()ing the size of the list returned; you can easily exceed the practical memory limits of Appengine by querying for a very large dataset.