com.googlecode.objectify
Interface Objectify

All Known Implementing Classes:
ObjectifyImpl, ObjectifyWrapper

public interface Objectify

This is the main "business end" of Objectify. It lets you get(), put(), delete(), and query() your typed POJO entities.

You can create an Objectify instance using ObjectifyFactory.begin() or ObjectifyFactory.beginTransaction(). A transaction (or lack thereof) will be associated with the instance; by using multiple instances, you can interleave calls between several different transactions.

Author:
Jeff Schnitzer

Method Summary
 AsyncObjectify async()
          Obtain the asynchronous version of the Objectify interface.
<T> void
delete(java.lang.Class<T> clazz, long id)
          A convenience method, shorthand for creating a key and deleting it.
<T> void
delete(java.lang.Class<T> clazz, java.lang.String name)
          A convenience method, shorthand for creating a key and deleting it.
 void delete(java.lang.Iterable<?> keysOrEntities)
          Deletes the specified entities in a parallel batch operation.
 void delete(java.lang.Object... keysOrEntities)
          Deletes the specified entity.
<T> T
find(java.lang.Class<? extends T> clazz, long id)
          Same as get(Class, long) but returns null instead of throwing NotFoundException
<T> T
find(java.lang.Class<? extends T> clazz, java.lang.String name)
          Same as get(Class, name) but returns null instead of throwing NotFoundException
<T> T
find(Key<? extends T> key)
          Same as get(Key) but returns null instead of throwing NotFoundException
<S,T> java.util.Map<S,T>
get(java.lang.Class<? extends T> clazz, java.lang.Iterable<S> idsOrNames)
          A convenience method that prevents you from having to assemble all the Keys yourself and calling get(Iterable<Key>).
<T> T
get(java.lang.Class<? extends T> clazz, long id)
          A convenience method, shorthand for creating a key and calling get()
<S,T> java.util.Map<S,T>
get(java.lang.Class<? extends T> clazz, S... idsOrNames)
          Convenient varargs alias for get(Class, Iterable)
<T> T
get(java.lang.Class<? extends T> clazz, java.lang.String name)
          A convenience method, shorthand for creating a key and calling get()
<T> java.util.Map<Key<T>,T>
get(java.lang.Iterable<? extends Key<? extends T>> keys)
          Performs a parallel batch get, returning your entities.
<T> java.util.Map<Key<T>,T>
get(Key<? extends T>... keys)
          Varargs version of get(Iterable)
<T> T
get(Key<? extends T> key)
          Gets one instance of your entity.
 com.google.appengine.api.datastore.DatastoreService getDatastore()
          Obtain a DatastoreService with parameters roughly equivalent to this Objectify instance.
 ObjectifyFactory getFactory()
          Obtain the ObjectifyFactory from which this Objectify instance was created.
 com.google.appengine.api.datastore.Transaction getTxn()
          Get the underlying transaction object associated with this Objectify instance.
<T> java.util.Map<Key<T>,T>
put(java.lang.Iterable<? extends T> objs)
          Saves multiple entities to the datastore in a single parallel batch operation.
<T> java.util.Map<Key<T>,T>
put(T... objs)
          Convenient varargs alias for put(Iterable)
<T> Key<T>
put(T obj)
          Puts an entity in the datastore.
<T> Query<T>
query()
          Create a typesafe query across all kinds of entities.
<T> Query<T>
query(java.lang.Class<T> clazz)
          Create a typesafe query across one specific kind of entity.
 

Method Detail

get

<T> java.util.Map<Key<T>,T> get(java.lang.Iterable<? extends Key<? extends T>> keys)

Performs a parallel batch get, returning your entities. This is faster and more efficient than fetching entities one at a time.

You can fetch entities of many different kinds in a single call. Entities not present in the datastore will be absent from the returned map. Otherwise, the iteration order of the result will match the order in the parameter.

Parameters:
keys - are the keys to fetch; you can mix and match the types of objects.
Returns:
the keys that were found in the datastore, mapped to the related entity. The iteration order of the map will match the order of the keys argument. A empty map is returned if no keys are found in the datastore.
See Also:
DatastoreService.get(Iterable)

get

<T> java.util.Map<Key<T>,T> get(Key<? extends T>... keys)

Varargs version of get(Iterable)


get

<T> T get(Key<? extends T> key)
      throws NotFoundException

Gets one instance of your entity.

Throws:
NotFoundException - if the key does not exist in the datastore
See Also:
DatastoreService.get(Key)

get

<T> T get(java.lang.Class<? extends T> clazz,
          long id)
      throws NotFoundException

A convenience method, shorthand for creating a key and calling get()

Throws:
NotFoundException - if the key does not exist in the datastore

get

<T> T get(java.lang.Class<? extends T> clazz,
          java.lang.String name)
      throws NotFoundException

A convenience method, shorthand for creating a key and calling get()

Throws:
NotFoundException - if the key does not exist in the datastore

get

<S,T> java.util.Map<S,T> get(java.lang.Class<? extends T> clazz,
                             java.lang.Iterable<S> idsOrNames)

A convenience method that prevents you from having to assemble all the Keys yourself and calling get(Iterable<Key>).

Note that unlike the standard batch get method, this method only gets a homogeneous set of objects.

Parameters:
idsOrNames - must be of type Iterable (which translates to id keys) or of type Iterable (which translates to name keys).
Returns:
a map of the id/name to the entity pojo.
Throws:
java.lang.IllegalArgumentException - if ids is not Iterable or Iterable

get

<S,T> java.util.Map<S,T> get(java.lang.Class<? extends T> clazz,
                             S... idsOrNames)
Convenient varargs alias for get(Class, Iterable)


find

<T> T find(Key<? extends T> key)
Same as get(Key) but returns null instead of throwing NotFoundException


find

<T> T find(java.lang.Class<? extends T> clazz,
           long id)
Same as get(Class, long) but returns null instead of throwing NotFoundException


find

<T> T find(java.lang.Class<? extends T> clazz,
           java.lang.String name)
Same as get(Class, name) but returns null instead of throwing NotFoundException


put

<T> Key<T> put(T obj)

Puts an entity in the datastore.

If your entity has a null Long id, a fresh id will be generated and a new entity will be created in the database. If your entity already has an id (either long, Long, or String) value, any existing entity in the datastore with that id will be overwritten.

Generated ids are stored in the entity itself. If you put() an entity with a null Long id, it will be set before the method returns.

Parameters:
obj - must be an object of a registered entity type.
Returns:
the key associated with the object.
See Also:
DatastoreService.put(com.google.appengine.api.datastore.Entity)

put

<T> java.util.Map<Key<T>,T> put(java.lang.Iterable<? extends T> objs)

Saves multiple entities to the datastore in a single parallel batch operation.

All the rules regarding generated ids in put() apply.

Note that the iteration order of the return value will be the same as the order of the parameter.

Parameters:
objs - must all be objects of registered entity type
Returns:
a map of the keys to the very same object instances passed in
See Also:
DatastoreService.put(Iterable)

put

<T> java.util.Map<Key<T>,T> put(T... objs)
Convenient varargs alias for put(Iterable)


delete

void delete(java.lang.Object... keysOrEntities)
Deletes the specified entity.

Parameters:
keysOrEntities - can be Keys, datastore Keys, or pojo entities. If it includes entities, only the id fields are relevant.

delete

void delete(java.lang.Iterable<?> keysOrEntities)
Deletes the specified entities in a parallel batch operation. This is faster and more efficient than deleting them one by one.

Parameters:
keysOrEntities - can contain any mix of Key, datastore Key, or pojo entities. They need not be of the same type. If a pojo is used, only its id fields are relevant.
See Also:
DatastoreService.delete(Iterable)

delete

<T> void delete(java.lang.Class<T> clazz,
                long id)
A convenience method, shorthand for creating a key and deleting it.


delete

<T> void delete(java.lang.Class<T> clazz,
                java.lang.String name)
A convenience method, shorthand for creating a key and deleting it.


query

<T> Query<T> query()

Create a typesafe query across all kinds of entities.


query

<T> Query<T> query(java.lang.Class<T> clazz)

Create a typesafe query across one specific kind of entity.


getTxn

com.google.appengine.api.datastore.Transaction getTxn()

Get the underlying transaction object associated with this Objectify instance.

Note that this is *not* the same as DatastoreService.getCurrentTransaction(), which uses implicit transaction management. Objectify does not use implicit (thread local) transactions.

Returns:
the transaction associated with this Objectify instance, or null if no transaction is associated with this instance.

getDatastore

com.google.appengine.api.datastore.DatastoreService getDatastore()

Obtain a DatastoreService with parameters roughly equivalent to this Objectify instance.

This should not normally be necessary. It allows you to work with raw Entity objects, allocate ids, and examine thread local transactions.

Note that Objectify does not actually use this DatastoreService in any way; all requests go through an AsyncDatastoreService. Also, even Google's DatastoreService implementation is just a facade around AsyncDatastoreService.


getFactory

ObjectifyFactory getFactory()
Obtain the ObjectifyFactory from which this Objectify instance was created.

Returns:
the ObjectifyFactory associated with this Objectify instance.

async

AsyncObjectify async()
Obtain the asynchronous version of the Objectify interface. Provides async versions of get/put/delete calls. Note that all queries are automatically asynchronous; just create multiple Iterators before iterating them.



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