com.googlecode.objectify.cmd

Interface Loader

All Superinterfaces:

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

All Known Implementing Classes:

LoaderImpl

public interface Loader
extends SimpleQuery<Object>

The top element in the command chain for retrieving entities from the datastore.

At this point you can enable load groups with group(), start all-kinds queries by calling query-related methods (see SimpleQuery), load entities by key or ref, or narrow your interest to a specific kind by calling type().

All command objects are immutable.

Author:

Jeff Schnitzer

Method Summary

Modifier and Type	Method and Description
<E> Map<Key<E>,E>	entities(E... entities) A convenient substitute for entities(Iterable)
<E> Map<Key<E>,E>	entities(Iterable<E> entities) 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.
<T> T	fromEntity(com.google.appengine.api.datastore.Entity entity) Convert a native datastore Entity into a typed POJO.
Set<Class<?>>	getLoadGroups()
Objectify	getObjectify()
Loader	group(Class<?>... groups) Enables one or more fetch groups.
<E> LoadResult<E>	key(Key<E> key) Load a single entity by key.
<E> Map<Key<E>,E>	keys(Iterable<Key<E>> keys) Load multiple entities by key from the datastore in a batch.
<E> Map<Key<E>,E>	keys(Key<? extends E>... keys) A convenient substitute for keys(Iterable)
<E> LoadType<E>	kind(String kind) Restricts the find operation to entities of a particular kind.
<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(Iterable<Ref<E>> refs) Load multiple refs in a batch operation.
<E> Map<Key<E>,E>	refs(Ref<? extends E>... refs) A convenient substitute for refs(Iterable)
<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<?> keysOrEntities) Fetch multiple entities from the datastore in a batch.
<E> Map<Key<E>,E>	values(Object... keysOrEntities) A convenient substitute for values(Iterable)

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

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 java.lang.Iterable

forEach, spliterator

Method Detail

group

Loader group(Class<?>... groups)

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.

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

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

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.

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

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

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.

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

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

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.

Parameters:

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

Returns:

a result which can materialize the entity.

refs

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

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.

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.

refs

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

A convenient substitute for refs(Iterable)

key

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

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.

Parameters:

key - defines the entity to fetch

Returns:

a result which can materialize the entity

keys

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

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.

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.

keys

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

A convenient substitute for keys(Iterable)

entity

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

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.

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

entities

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

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.

Parameters:

entities - 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.

entities

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

A convenient substitute for entities(Iterable)

value

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

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.

Parameters:

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

Returns:

a Ref which holds the asynchronous result

values

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

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.

Parameters:

keysOrEntities - 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.

values

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

A convenient substitute for values(Iterable)

getObjectify

Objectify getObjectify()

Returns:

the parent Objectify instance

getLoadGroups

Set<Class<?>> getLoadGroups()

Returns:

the currently enabled load groups in an unmodifiable list

fromEntity

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

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.

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.

now

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

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.