com.googlecode.objectify.Objectify Maven / Gradle / Ivy
Show all versions of objectify Show documentation
package com.googlecode.objectify;
import java.util.Map;
import com.google.appengine.api.datastore.DatastoreService;
import com.google.appengine.api.datastore.Transaction;
/**
* This is the main "business end" of Objectify. It lets you get(), put(), delete(),
* and query() your typed POJO entities.
*
* You can create an {@code Objectify} instance using {@code ObjectifyFactory.begin()}
* or {@code 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
*/
public interface Objectify
{
/**
* 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.
*
* @param keys are the keys to fetch; you can mix and match the types of objects.
* @return 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 DatastoreService#get(Iterable)
*/
Map, T> get(Iterable> keys);
/**
* Varargs version of get(Iterable)
*/
Map, T> get(Key... keys);
/**
* Gets one instance of your entity.
*
* @throws NotFoundException if the key does not exist in the datastore
*
* @see DatastoreService#get(Key)
*/
T get(Key key) throws NotFoundException;
/**
* A convenience method, shorthand for creating a key and calling get()
* @throws NotFoundException if the key does not exist in the datastore
*/
T get(Class 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
*/
T get(Class clazz, String name) throws NotFoundException;
/**
* A convenience method that prevents you from having to assemble all the Keys
* yourself and calling {@code get(Iterable)}.
*
* Note that unlike the standard batch get method, this method only gets a
* homogeneous set of objects.
*
* @param idsOrNames must be of type Iterable (which translates to id keys)
* or of type Iterable (which translates to name keys).
* @return a map of the id/name to the entity pojo.
* @throws IllegalArgumentException if ids is not Iterable or Iterable
*/
Map get(Class clazz, Iterable idsOrNames);
/**
* Convenient varargs alias for get(Class, Iterable)
*/
Map get(Class clazz, S... idsOrNames);
/** Same as {@code get(Key)} but returns null instead of throwing NotFoundException */
T find(Key key);
/** Same as {@code get(Class, long)} but returns null instead of throwing NotFoundException */
T find(Class clazz, long id);
/** Same as {@code get(Class, name)} but returns null instead of throwing NotFoundException */
T find(Class clazz, String name);
/**
* 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.
*
* @param obj must be an object of a registered entity type.
* @return the key associated with the object.
*
* @see DatastoreService#put(com.google.appengine.api.datastore.Entity)
*/
Key put(T obj);
/**
* Saves multiple entities to the datastore in a single parallel batch
* operation.
*
* All the rules regarding generated ids in {@code put()} apply.
*
* Note that the iteration order of the return value will be the same
* as the order of the parameter.
*
* @param objs must all be objects of registered entity type
* @return a map of the keys to the very same object instances passed in
*
* @see DatastoreService#put(Iterable)
*/
Map, T> put(Iterable objs);
/**
* Convenient varargs alias for put(Iterable)
*/
Map, T> put(T... objs);
/**
* Deletes the specified entity.
*
* @param keysOrEntities can be Keys, datastore Keys, or pojo entities.
* If it includes entities, only the id fields are relevant.
*/
void delete(Object... keysOrEntities);
/**
* Deletes the specified entities in a parallel batch operation. This is faster
* and more efficient than deleting them one by one.
*
* @param 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 DatastoreService#delete(Iterable)
*/
void delete(Iterable keysOrEntities);
/**
* A convenience method, shorthand for creating a key and deleting it.
*/
void delete(Class clazz, long id);
/**
* A convenience method, shorthand for creating a key and deleting it.
*/
void delete(Class clazz, String name);
/**
* Create a typesafe query across all kinds of entities.
*/
Query query();
/**
* Create a typesafe query across one specific kind of entity.
*/
Query query(Class clazz);
/**
* Get the underlying transaction object associated with this Objectify instance.
*
* Note that this is *not* the same as {@code DatastoreService.getCurrentTransaction()},
* which uses implicit transaction management. Objectify does not use implicit (thread
* local) transactions.
*
* @return the transaction associated with this Objectify instance,
* or null if no transaction is associated with this instance.
*/
public Transaction getTxn();
/**
* 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.
*/
public DatastoreService getDatastore();
/**
* Obtain the ObjectifyFactory from which this Objectify instance was created.
*
* @return the ObjectifyFactory associated with this Objectify instance.
*/
public ObjectifyFactory getFactory();
/**
* 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.
*/
public AsyncObjectify async();
}