ebean/src/main/java/com/avaje/ebean/EbeanServer.java

package com.avaje.ebean;

import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;

import javax.persistence.OptimisticLockException;
import javax.persistence.PersistenceException;

import com.avaje.ebean.annotation.CacheStrategy;
import com.avaje.ebean.cache.ServerCacheManager;
import com.avaje.ebean.config.ServerConfig;
import com.avaje.ebean.meta.MetaInfoManager;
import com.avaje.ebean.text.csv.CsvReader;
import com.avaje.ebean.text.json.JsonContext;

/**
 * Provides the API for fetching and saving beans to a particular DataSource.
 * <p>
 * <b>Registration with the Ebean Singleton:</b><br/>
 * When a EbeanServer is constructed it can be registered with the Ebean
 * singleton (see {@link ServerConfig#setRegister(boolean)}). The Ebean
 * singleton is essentially a map of EbeanServer's that have been registered
 * with it. The EbeanServer can then be retrieved later via
 * {@link Ebean#getServer(String)}.
 * </p>
 * <p>
 * <b>The 'default' EbeanServer</b><br/>
 * One EbeanServer can be designated as the 'default' or 'primary' EbeanServer
 * (see {@link ServerConfig#setDefaultServer(boolean)}. Many methods on Ebean
 * such as {@link Ebean#find(Class)} etc are actually just a convenient way to
 * call methods on the 'default/primary' EbeanServer. This is handy for
 * applications that use a single DataSource.
 * <p>
 * There is one EbeanServer per Database (javax.sql.DataSource). One EbeanServer
 * is referred to as the <em>'default'</em> server and that is the one that
 * Ebean methods such as {@link Ebean#find(Class)} use.
 * </p>
 * <p>
 * <b>Constructing a EbeanServer</b><br/>
 * EbeanServer's are constructed by the EbeanServerFactory. They can be created
 * programmatically via {@link EbeanServerFactory#create(ServerConfig)} or they
 * can be automatically constructed on demand using configuration information in
 * the ebean.properties file.
 * </p>
 * <p>
 * Example: Get a EbeanServer
 * </p>
 * 
 * <pre>{@code
 * // Get access to the Human Resources EbeanServer/Database
 * EbeanServer hrServer = Ebean.getServer("HR");
 * 
 * 
 * // fetch contact 3 from the HR database Contact contact =
 * hrServer.find(Contact.class, new Integer(3));
 * 
 * contact.setStatus("INACTIVE"); ...
 * 
 * // save the contact back to the HR database hrServer.save(contact);
 * }</pre>
 * 
 * <p>
 * <b>EbeanServer has more API than Ebean</b><br/>
 * EbeanServer provides additional API compared with Ebean. For example it
 * provides more control over the use of Transactions that is not available in
 * the Ebean API.
 * </p>
 * <p>
 * <em>External Transactions:</em> If you wanted to use transactions created
 * externally to eBean then EbeanServer provides additional methods where you
 * can explicitly pass a transaction (that can be created externally).
 * </p>
 * <p>
 * <em>Bypass ThreadLocal Mechanism:</em> If you want to bypass the built in
 * ThreadLocal transaction management you can use the createTransaction()
 * method. Example: a single thread requires more than one transaction.
 * </p>
 * 
 * @see Ebean
 * @see EbeanServerFactory
 * @see ServerConfig
 */
public interface EbeanServer {

  /**
   * Shutdown the EbeanServer programmatically.
   * <p>
   * This method is not normally required. Ebean registers a shutdown hook and shuts down cleanly.
   * </p>
   * <p>
   * If the under underlying DataSource is the Ebean implementation then you
   * also have the option of shutting down the DataSource and deregistering the
   * JDBC driver.
   * </p>
   * 
   * @param shutdownDataSource
   *          if true then shutdown the underlying DataSource if it is the EbeanORM
   *          DataSource implementation.
   * @param deregisterDriver
   *          if true then deregister the JDBC driver if it is the EbeanORM
   *          DataSource implementation.
   */
  public void shutdown(boolean shutdownDataSource, boolean deregisterDriver);
  
  /**
   * Return the AdminAutofetch which is used to control and configure the
   * Autofetch service at runtime.
   */
  public AdminAutofetch getAdminAutofetch();

  /**
   * Return the name. This is used with {@link Ebean#getServer(String)} to get a
   * EbeanServer that was registered with the Ebean singleton.
   */
  public String getName();

  /**
   * Return the ExpressionFactory for this server.
   */
  public ExpressionFactory getExpressionFactory();

  /**
   * Return the MetaInfoManager which is used to get meta data from the EbeanServer
   * such as query execution statistics.
   */
  public MetaInfoManager getMetaInfoManager();

  /**
   * Return the BeanState for a given entity bean.
   * <p>
   * This will return null if the bean is not an enhanced (or subclassed) entity
   * bean.
   * </p>
   */
  public BeanState getBeanState(Object bean);

  /**
   * Return the value of the Id property for a given bean.
   */
  public Object getBeanId(Object bean);

  /**
   * Return a map of the differences between two objects of the same type.
   * <p>
   * When null is passed in for b, then the 'OldValues' of a is used for the
   * difference comparison.
   * </p>
   */
  public Map<String, ValuePair> diff(Object a, Object b);

  /**
   * Create a new instance of T that is an EntityBean (for subclassing).
   * <p>
   * Note that if you are using enhancement (rather than subclassing) then you
   * do not need to use this method and just new up a bean.
   * </p>
   * <p>
   * Potentially useful when using subclassing and you wish to programmatically
   * load a entity bean . Otherwise this method is generally not required.
   * </p>
   */
  public <T> T createEntityBean(Class<T> type);

  /**
   * Create a CsvReader for a given beanType.
   */
  public <T> CsvReader<T> createCsvReader(Class<T> beanType);

  /**
   * Create a named query for an entity bean (refer
   * {@link Ebean#createQuery(Class, String)})
   * <p>
   * The query statement will be defined in a deployment orm xml file.
   * </p>
   * 
   * @see Ebean#createQuery(Class, String)
   */
  public <T> Query<T> createNamedQuery(Class<T> beanType, String namedQuery);

  /**
   * Create a query using the query language.
   * <p>
   * Note that you are allowed to add additional clauses using where() as well
   * as use fetch() and setOrderBy() after the query has been created.
   * </p>
   * <p>
   * Note that this method signature used to map to named queries and that has
   * moved to {@link #createNamedQuery(Class, String)}.
   * </p>
   * 
   * <pre>{@code
   *  EbeanServer ebeanServer = ... ;
   *  String q = "find order fetch details where status = :st";
   *  
   *  List<Order> newOrders
   *        = ebeanServer.createQuery(Order.class, q)
   *             .setParameter("st", Order.Status.NEW)
   *             .findList();
   * }</pre>
   * 
   * @param query
   *          the object query
   */
  public <T> Query<T> createQuery(Class<T> beanType, String query);

  /**
   * Create a query for an entity bean (refer {@link Ebean#createQuery(Class)}).
   * 
   * @see Ebean#createQuery(Class)
   */
  public <T> Query<T> createQuery(Class<T> beanType);

  /**
   * Create a query for a type of entity bean (the same as {@link EbeanServer#createQuery(Class)}).
   */
  public <T> Query<T> find(Class<T> beanType);

  /**
   * Return the next unique identity value for a given bean type.
   * <p>
   * This will only work when a IdGenerator is on the bean such as for beans
   * that use a DB sequence or UUID.
   * </p>
   * <p>
   * For DB's supporting getGeneratedKeys and sequences such as Oracle10 you do
   * not need to use this method generally. It is made available for more
   * complex cases where it is useful to get an ID prior to some processing.
   * </p>
   */
  public Object nextId(Class<?> beanType);

  /**
   * Create a filter for filtering lists of entity beans.
   */
  public <T> Filter<T> filter(Class<T> beanType);

  /**
   * Sort the list using the sortByClause.
   * 
   * @see Ebean#sort(List, String)
   * 
   * @param list
   *          the list of entity beans
   * @param sortByClause
   *          the properties to sort the list by
   */
  public <T> void sort(List<T> list, String sortByClause);

  /**
   * Create a named update for an entity bean (refer
   * {@link Ebean#createNamedUpdate(Class, String)}).
   */
  public <T> Update<T> createNamedUpdate(Class<T> beanType, String namedUpdate);

  /**
   * Create a update for an entity bean where you will manually specify the
   * insert update or delete statement.
   */
  public <T> Update<T> createUpdate(Class<T> beanType, String ormUpdate);

  /**
   * Create a sql query for executing native sql query statements (refer
   * {@link Ebean#createSqlQuery(String)}).
   * 
   * @see Ebean#createSqlQuery(String)
   */
  public SqlQuery createSqlQuery(String sql);

  /**
   * Create a named sql query (refer {@link Ebean#createNamedSqlQuery(String)}).
   * <p>
   * The query statement will be defined in a deployment orm xml file.
   * </p>
   * 
   * @see Ebean#createNamedSqlQuery(String)
   */
  public SqlQuery createNamedSqlQuery(String namedQuery);

  /**
   * Create a sql update for executing native dml statements (refer {@link Ebean#createSqlUpdate(String)}).
   * 
   * @see Ebean#createSqlUpdate(String)
   */
  public SqlUpdate createSqlUpdate(String sql);

  /**
   * Create a CallableSql to execute a given stored procedure.
   */
  public CallableSql createCallableSql(String callableSql);

  /**
   * Create a named sql update (refer {@link Ebean#createNamedSqlUpdate(String)}).
   * <p>
   * The statement (an Insert Update or Delete statement) will be defined in a
   * deployment orm xml file.
   * </p>
   * 
   * @see Ebean#createNamedSqlUpdate(String)
   */
  public SqlUpdate createNamedSqlUpdate(String namedQuery);

  /**
   * Register a TransactionCallback on the currently active transaction.
   * <p/>
   * If there is no currently active transaction then a PersistenceException is thrown.
   *
   * @param transactionCallback The transaction callback to be registered with the current transaction.
   *
   * @throws PersistenceException If there is no currently active transaction
   */
  public void register(TransactionCallback transactionCallback) throws PersistenceException;

  /**
   * Create a new transaction that is not held in TransactionThreadLocal.
   * <p>
   * You will want to do this if you want multiple Transactions in a single
   * thread or generally use transactions outside of the TransactionThreadLocal
   * management.
   * </p>
   */
  public Transaction createTransaction();

  /**
   * Create a new transaction additionally specifying the isolation level.
   * <p>
   * Note that this transaction is NOT stored in a thread local.
   * </p>
   */
  public Transaction createTransaction(TxIsolation isolation);

  /**
   * Start a new transaction putting it into a ThreadLocal.
   * 
   * @see Ebean#beginTransaction()
   */
  public Transaction beginTransaction();

  /**
   * Start a transaction additionally specifying the isolation level.
   */
  public Transaction beginTransaction(TxIsolation isolation);

  /**
   * Returns the current transaction or null if there is no current transaction in scope.
   */
  public Transaction currentTransaction();

  /**
   * Commit the current transaction.
   * 
   * @see Ebean#commitTransaction()
   */
  public void commitTransaction();

  /**
   * Rollback the current transaction.
   * 
   * @see Ebean#rollbackTransaction()
   */
  public void rollbackTransaction();

  /**
   * If the current transaction has already been committed do nothing otherwise
   * rollback the transaction.
   * <p>
   * Useful to put in a finally block to ensure the transaction is ended, rather
   * than a rollbackTransaction() in each catch block.
   * </p>
   * <p>
   * Code example:
   * 
   * <pre>{@code
   *   ebeanServer.startTransaction();
   *   try {
   *     // do some fetching and or persisting ...
   * 
   *     // commit at the end
   *     ebeanServer.commitTransaction();
   * 
   *   } finally {
   *     // if commit didn't occur then rollback the transaction
   *     ebeanServer.endTransaction();
   *   }
   * }</pre>
   * 
   * </p>
   * 
   * @see Ebean#endTransaction()
   */
  public void endTransaction();

  /**
   * Refresh the values of a bean.
   * <p>
   * Note that this does not refresh any OneToMany or ManyToMany properties.
   * </p>
   * 
   * @see Ebean#refresh(Object)
   */
  public void refresh(Object bean);

  /**
   * Refresh a many property of an entity bean.
   * 
   * @param bean
   *          the entity bean containing the 'many' property
   * @param propertyName
   *          the 'many' property to be refreshed
   * 
   * @see Ebean#refreshMany(Object, String)
   */
  public void refreshMany(Object bean, String propertyName);

  /**
   * Find a bean using its unique id.
   * 
   * @see Ebean#find(Class, Object)
   */
  public <T> T find(Class<T> beanType, Object uid);

  /**
   * Get a reference bean (see {@link Ebean#getReference(Class, Object)}.
   * <p>
   * This will not perform a query against the database.
   * </p>
   * <pre>{@code
   * Product product = Ebean.getReference(Product.class, 1);
   * 
   * // You can get the id without causing a fetch/lazy load
   * Integer productId = product.getId();
   * 
   * // If you try to get any other property a fetch/lazy loading will occur
   * // This will cause a query to execute...
   * String name = product.getName();
   * }</pre>
   * 
   * @param beanType
   *          the type of entity bean
   * @param id
   *          the id value
   */
  public <T> T getReference(Class<T> beanType, Object id);

  /**
   * Return the number of 'top level' or 'root' entities this query should
   * return.
   */
  public <T> int findRowCount(Query<T> query, Transaction transaction);

  /**
   * Return the Id values of the query as a List.
   */
  public <T> List<Object> findIds(Query<T> query, Transaction transaction);

  /**
   * Return a QueryIterator for the query. This is similar to findVisit in that
   * not all the result beans need to be held in memory at the same time and as
   * such is go for processing large queries.
   */
  public <T> QueryIterator<T> findIterate(Query<T> query, Transaction transaction);

  /**
   * Execute the query visiting the results. This is similar to findIterate in
   * that not all the result beans need to be held in memory at the same time
   * and as such is go for processing large queries.
   *
   * @see Query#findEach(QueryEachConsumer)
   */
  public <T> void findEach(Query<T> query, QueryEachConsumer<T> consumer, Transaction transaction);

  /**
   * Execute the query visiting the results. This is similar to findIterate in
   * that not all the result beans need to be held in memory at the same time
   * and as such is go for processing large queries.
   *
   * @see Query#findEachWhile(QueryEachWhileConsumer)
   */
  public <T> void findEachWhile(Query<T> query, QueryEachWhileConsumer<T> consumer, Transaction transaction);

  /**
   * Deprecated in favor of #findEachWhile which is functionally exactly the same
   * but has a much better name.
   * <p>
   * Execute the query visiting the results. This is similar to findIterate in
   * that not all the result beans need to be held in memory at the same time
   * and as such is go for processing large queries.
   * </p>
   *
   * @deprecated
   */
  public <T> void findVisit(Query<T> query, QueryResultVisitor<T> visitor, Transaction transaction);

  /**
   * Execute a query returning a list of beans.
   * <p>
   * Generally you are able to use {@link Query#findList()} rather than
   * explicitly calling this method. You could use this method if you wish to
   * explicitly control the transaction used for the query.
   * </p>
   * 
   * @param <T>
   *          the type of entity bean to fetch.
   * @param query
   *          the query to execute.
   * @param transaction
   *          the transaction to use (can be null).
   * @return the list of fetched beans.
   * @see Query#findList()
   */
  public <T> List<T> findList(Query<T> query, Transaction transaction);

  /**
   * Execute find row count query in a background thread.
   * <p>
   * This returns a Future object which can be used to cancel, check the
   * execution status (isDone etc) and get the value (with or without a
   * timeout).
   * </p>
   * 
   * @param query
   *          the query to execute the row count on
   * @param transaction
   *          the transaction (can be null).
   * @return a Future object for the row count query
   */
  public <T> FutureRowCount<T> findFutureRowCount(Query<T> query, Transaction transaction);

  /**
   * Execute find Id's query in a background thread.
   * <p>
   * This returns a Future object which can be used to cancel, check the
   * execution status (isDone etc) and get the value (with or without a
   * timeout).
   * </p>
   * 
   * @param query
   *          the query to execute the fetch Id's on
   * @param transaction
   *          the transaction (can be null).
   * @return a Future object for the list of Id's
   */
  public <T> FutureIds<T> findFutureIds(Query<T> query, Transaction transaction);

  /**
   * Execute find list query in a background thread.
   * <p>
   * This returns a Future object which can be used to cancel, check the
   * execution status (isDone etc) and get the value (with or without a
   * timeout).
   * </p>
   * 
   * @param query
   *          the query to execute in the background
   * @param transaction
   *          the transaction (can be null).
   * @return a Future object for the list result of the query
   * @deprecated
   */
  public <T> FutureList<T> findFutureList(Query<T> query, Transaction transaction);

  /**
   * Execute find list SQL query in a background thread.
   * <p>
   * This returns a Future object which can be used to cancel, check the
   * execution status (isDone etc) and get the value (with or without a
   * timeout).
   * </p>
   * 
   * @param query
   *          the query to execute in the background
   * @param transaction
   *          the transaction (can be null).
   * @return a Future object for the list result of the query
   * @deprecated 
   */
  public SqlFutureList findFutureList(SqlQuery query, Transaction transaction);

  /**
   * Find using a PagingList with explicit transaction and pageSize.
   * Deprecated in favour of findPagedList().
   * @deprecated 
   */  
  public <T> PagingList<T> findPagingList(Query<T> query, Transaction transaction, int pageSize);

  /**
   * Return a PagedList for this query.
   * <p>
   * The benefit of using this over just using the normal {@link Query#setFirstRow(int)} and
   * {@link Query#setMaxRows(int)} is that it additionally wraps an optional call to
   * {@link Query#findFutureRowCount()} to determine total row count, total page count etc.
   * </p>
   * <p>
   * Internally this works using {@link Query#setFirstRow(int)} and {@link Query#setMaxRows(int)} on
   * the query. This translates into SQL that uses limit offset, rownum or row_number
   * function to limit the result set.
   * </p>
   * 
   * @param pageIndex
   *          The zero based index of the page.
   * @param pageSize
   *          The number of beans to return per page.
   * @return The PagedList
   */
  public <T> PagedList<T> findPagedList(Query<T> query, Transaction transaction, int pageIndex, int pageSize);

  /**
   * Execute the query returning a set of entity beans.
   * <p>
   * Generally you are able to use {@link Query#findSet()} rather than
   * explicitly calling this method. You could use this method if you wish to
   * explicitly control the transaction used for the query.
   * </p>
   * 
   * @param <T>
   *          the type of entity bean to fetch.
   * @param query
   *          the query to execute
   * @param transaction
   *          the transaction to use (can be null).
   * @return the set of fetched beans.
   * @see Query#findSet()
   */
  public <T> Set<T> findSet(Query<T> query, Transaction transaction);

  /**
   * Execute the query returning the entity beans in a Map.
   * <p>
   * Generally you are able to use {@link Query#findMap()} rather than
   * explicitly calling this method. You could use this method if you wish to
   * explicitly control the transaction used for the query.
   * </p>
   * 
   * @param <T>
   *          the type of entity bean to fetch.
   * @param query
   *          the query to execute.
   * @param transaction
   *          the transaction to use (can be null).
   * @return the map of fetched beans.
   * @see Query#findMap()
   */
  public <T> Map<?, T> findMap(Query<T> query, Transaction transaction);

  /**
   * Execute the query returning at most one entity bean. This will throw a
   * PersistenceException if the query finds more than one result.
   * <p>
   * Generally you are able to use {@link Query#findUnique()} rather than
   * explicitly calling this method. You could use this method if you wish to
   * explicitly control the transaction used for the query.
   * </p>
   * 
   * @param <T>
   *          the type of entity bean to fetch.
   * @param query
   *          the query to execute.
   * @param transaction
   *          the transaction to use (can be null).
   * @return the list of fetched beans.
   * @see Query#findUnique()
   */
  public <T> T findUnique(Query<T> query, Transaction transaction);

  /**
   * Execute the sql query returning a list of MapBean.
   * <p>
   * Generally you are able to use {@link SqlQuery#findList()} rather than
   * explicitly calling this method. You could use this method if you wish to
   * explicitly control the transaction used for the query.
   * </p>
   * 
   * @param query
   *          the query to execute.
   * @param transaction
   *          the transaction to use (can be null).
   * @return the list of fetched MapBean.
   * @see SqlQuery#findList()
   */
  public List<SqlRow> findList(SqlQuery query, Transaction transaction);

  /**
   * Execute the sql query returning a set of MapBean.
   * <p>
   * Generally you are able to use {@link SqlQuery#findSet()} rather than
   * explicitly calling this method. You could use this method if you wish to
   * explicitly control the transaction used for the query.
   * </p>
   * 
   * @param query
   *          the query to execute.
   * @param transaction
   *          the transaction to use (can be null).
   * @return the set of fetched MapBean.
   * @see SqlQuery#findSet()
   */
  public Set<SqlRow> findSet(SqlQuery query, Transaction transaction);

  /**
   * Execute the sql query returning a map of MapBean.
   * <p>
   * Generally you are able to use {@link SqlQuery#findMap()} rather than
   * explicitly calling this method. You could use this method if you wish to
   * explicitly control the transaction used for the query.
   * </p>
   * 
   * @param query
   *          the query to execute.
   * @param transaction
   *          the transaction to use (can be null).
   * @return the set of fetched MapBean.
   * @see SqlQuery#findMap()
   */
  public Map<?, SqlRow> findMap(SqlQuery query, Transaction transaction);

  /**
   * Execute the sql query returning a single MapBean or null.
   * <p>
   * This will throw a PersistenceException if the query found more than one
   * result.
   * </p>
   * <p>
   * Generally you are able to use {@link SqlQuery#findUnique()} rather than
   * explicitly calling this method. You could use this method if you wish to
   * explicitly control the transaction used for the query.
   * </p>
   * 
   * @param query
   *          the query to execute.
   * @param transaction
   *          the transaction to use (can be null).
   * @return the fetched MapBean or null if none was found.
   * @see SqlQuery#findUnique()
   */
  public SqlRow findUnique(SqlQuery query, Transaction transaction);

  /**
   * Persist the bean by either performing an insert or update.
   * 
   * @see Ebean#save(Object)
   */
  public void save(Object bean) throws OptimisticLockException;

  /**
   * Save all the beans in the iterator.
   */
  public int save(Iterator<?> it) throws OptimisticLockException;

  /**
   * Save all the beans in the collection.
   */
  public int save(Collection<?> beans) throws OptimisticLockException;

  /**
   * Delete the bean.
   * 
   * @see Ebean#delete(Object)
   */
  public void delete(Object bean) throws OptimisticLockException;

  /**
   * Delete all the beans from an Iterator.
   */
  public int delete(Iterator<?> it) throws OptimisticLockException;

  /**
   * Delete all the beans in the collection.
   */
  public int delete(Collection<?> c) throws OptimisticLockException;

  /**
   * Delete the bean given its type and id.
   */
  public int delete(Class<?> beanType, Object id);

  /**
   * Delete the bean given its type and id with an explicit transaction.
   */
  public int delete(Class<?> beanType, Object id, Transaction transaction);

  /**
   * Delete several beans given their type and id values.
   */
  public void delete(Class<?> beanType, Collection<?> ids);

  /**
   * Delete several beans given their type and id values with an explicit
   * transaction.
   */
  public void delete(Class<?> beanType, Collection<?> ids, Transaction transaction);

  /**
   * Execute a SQL Update Delete or Insert statement using the current
   * transaction. This returns the number of rows that where updated, deleted or
   * inserted.
   * <p>
   * Refer to Ebean.execute(UpdateSql) for full documentation.
   * </p>
   * 
   * @see Ebean#execute(SqlUpdate)
   */
  public int execute(SqlUpdate updSql);

  /**
   * Execute a ORM insert update or delete statement using the current
   * transaction.
   * <p>
   * This returns the number of rows that where inserted, updated or deleted.
   * </p>
   */
  public int execute(Update<?> update);

  /**
   * Execute a ORM insert update or delete statement with an explicit
   * transaction.
   */
  public int execute(Update<?> update, Transaction t);

  /**
   * Call a stored procedure.
   * <p>
   * Refer to Ebean.execute(CallableSql) for full documentation.
   * </p>
   * 
   * @see Ebean#execute(CallableSql)
   */
  public int execute(CallableSql callableSql);

  /**
   * Process committed changes from another framework.
   * <p>
   * This notifies this instance of the framework that beans have been committed
   * externally to it. Either by another framework or clustered server. It uses
   * this to maintain its cache and text indexes appropriately.
   * </p>
   * 
   * @see Ebean#externalModification(String, boolean, boolean, boolean)
   */
  public void externalModification(String tableName, boolean inserted, boolean updated,
      boolean deleted);

  /**
   * Find a entity bean with an explicit transaction.
   * 
   * @param <T>
   *          the type of entity bean to find
   * @param beanType
   *          the type of entity bean to find
   * @param uid
   *          the bean id value
   * @param transaction
   *          the transaction to use (can be null)
   */
  public <T> T find(Class<T> beanType, Object uid, Transaction transaction);

  /**
   * Insert or update a bean with an explicit transaction.
   */
  public void save(Object bean, Transaction transaction) throws OptimisticLockException;

  /**
   * Save all the beans in the iterator with an explicit transaction.
   */
  public int save(Iterator<?> it, Transaction transaction) throws OptimisticLockException;

  /**
   * Save all the beans in the collection with an explicit transaction.
   */
  public int save(Collection<?> beans, Transaction transaction) throws OptimisticLockException;

  /**
   * Marks the entity bean as dirty.
   * <p>
   * This is used so that when a bean that is otherwise unmodified is updated the version
   * property is updated.
   * <p>
   * An unmodified bean that is saved or updated is normally skipped and this marks the bean as
   * dirty so that it is not skipped.
   * 
   * <pre>{@code
   * 
   * Customer customer = ebeanServer.find(Customer, id);
   * 
   * // mark the bean as dirty so that a save() or update() will
   * // increment the version property
   * ebeanServer.markAsDirty(customer);
   * ebeanServer.save(customer);
   * 
   * }</pre>
   */
  public void markAsDirty(Object bean);
  
  /**
   * Saves the bean using an update. If you know you are updating a bean then it is preferrable to
   * use this update() method rather than save().
   * <p>
   * <b>Stateless updates:</b> Note that the bean does not have to be previously fetched to call
   * update().You can create a new instance and set some of its properties programmatically for via
   * JSON/XML marshalling etc. This is described as a 'stateless update'.
   * </p>
   * <p>
   * <b>Optimistic Locking: </b> Note that if the version property is not set when update() is
   * called then no optimistic locking is performed (internally ConcurrencyMode.NONE is used).
   * </p>
   * <p>
   * <b>{@link ServerConfig#setUpdatesDeleteMissingChildren(boolean)}: </b> When cascade saving to a
   * OneToMany or ManyToMany the updatesDeleteMissingChildren setting controls if any other children
   * that are in the database but are not in the collection are deleted.
   * </p>
   * <p>
   * <b>{@link ServerConfig#setUpdateChangesOnly(boolean)}: </b> The updateChangesOnly setting
   * controls if only the changed properties are included in the update or if all the loaded
   * properties are included instead.
   * </p>
   * 
   * <pre>{@code
   * 
   * // A 'stateless update' example
   * Customer customer = new Customer();
   * customer.setId(7);
   * customer.setName("ModifiedNameNoOCC");
   * ebeanServer.update(customer);
   * 
   * }</pre>
   * 
   * @see ServerConfig#setUpdatesDeleteMissingChildren(boolean)
   * @see ServerConfig#setUpdateChangesOnly(boolean)
   */
  public void update(Object bean) throws OptimisticLockException;

  /**
   * Update a bean additionally specifying a transaction.
   */
  public void update(Object bean, Transaction t) throws OptimisticLockException;

  /**
   * Update a bean additionally specifying a transaction and the deleteMissingChildren setting.
   * 
   * @param bean
   *          the bean to update
   * @param transaction
   *          the transaction to use (can be null).
   * @param deleteMissingChildren
   *          specify false if you do not want 'missing children' of a OneToMany
   *          or ManyToMany to be automatically deleted.

   */
  public void update(Object bean, Transaction transaction, boolean deleteMissingChildren) throws OptimisticLockException;

  /**
   * Update a collection of beans. If there is no current transaction one is created and used to
   * update all the beans in the collection.
   */
  public void update(Collection<?> beans) throws OptimisticLockException;

  /**
   * Update a collection of beans with an explicit transaction.
   */
  public void update(Collection<?> beans, Transaction transaction) throws OptimisticLockException;
  
  /**
   * Insert the bean.
   */
  public void insert(Object bean);

  /**
   * Insert the bean with a transaction.
   */
  public void insert(Object bean, Transaction t);

  /**
   * Insert a collection of beans. If there is no current transaction one is created and used to
   * insert all the beans in the collection.
   */
  public void insert(Collection<?> beans);

  /**
   * Insert a collection of beans with an explicit transaction.
   */
  public void insert(Collection<?> beans, Transaction t);

  /**
   * Delete the associations (from the intersection table) of a ManyToMany given
   * the owner bean and the propertyName of the ManyToMany collection.
   * <p>
   * Typically these deletions occur automatically when persisting a ManyToMany
   * collection and this provides a way to invoke those deletions directly.
   * </p>
   * 
   * @return the number of associations deleted (from the intersection table).
   */
  public int deleteManyToManyAssociations(Object ownerBean, String propertyName);

  /**
   * Delete the associations (from the intersection table) of a ManyToMany given
   * the owner bean and the propertyName of the ManyToMany collection.
   * <p>
   * Additionally specify a transaction to use.
   * </p>
   * <p>
   * Typically these deletions occur automatically when persisting a ManyToMany
   * collection and this provides a way to invoke those deletions directly.
   * </p>
   * 
   * @return the number of associations deleted (from the intersection table).
   */
  public int deleteManyToManyAssociations(Object ownerBean, String propertyName, Transaction t);

  /**
   * Save the associations of a ManyToMany given the owner bean and the
   * propertyName of the ManyToMany collection.
   * <p>
   * Typically the saving of these associations (inserting into the intersection
   * table) occurs automatically when persisting a ManyToMany. This provides a
   * way to invoke those insertions directly.
   * </p>
   */
  public void saveManyToManyAssociations(Object ownerBean, String propertyName);

  /**
   * Save the associations of a ManyToMany given the owner bean and the
   * propertyName of the ManyToMany collection.
   * <p>
   * Typically the saving of these associations (inserting into the intersection
   * table) occurs automatically when persisting a ManyToMany. This provides a
   * way to invoke those insertions directly.
   * </p>
   */
  public void saveManyToManyAssociations(Object ownerBean, String propertyName, Transaction t);

  /**
   * Save the associated collection or bean given the property name.
   * <p>
   * This is similar to performing a save cascade on a specific property
   * manually.
   * </p>
   * <p>
   * Note that you can turn on/off cascading for a transaction via
   * {@link Transaction#setPersistCascade(boolean)}
   * </p>
   * 
   * @param ownerBean
   *          the bean instance holding the property we want to save
   * @param propertyName
   *          the property we want to save
   */
  public void saveAssociation(Object ownerBean, String propertyName);

  /**
   * Save the associated collection or bean given the property name with a
   * specific transaction.
   * <p>
   * This is similar to performing a save cascade on a specific property
   * manually.
   * </p>
   * <p>
   * Note that you can turn on/off cascading for a transaction via
   * {@link Transaction#setPersistCascade(boolean)}
   * </p>
   * 
   * @param ownerBean
   *          the bean instance holding the property we want to save
   * @param propertyName
   *          the property we want to save
   */
  public void saveAssociation(Object ownerBean, String propertyName, Transaction t);

  /**
   * Delete the bean with an explicit transaction.
   */
  public void delete(Object bean, Transaction t) throws OptimisticLockException;

  /**
   * Delete all the beans from an iterator.
   */
  public int delete(Iterator<?> it, Transaction t) throws OptimisticLockException;

  /**
   * Execute explicitly passing a transaction.
   */
  public int execute(SqlUpdate updSql, Transaction t);

  /**
   * Execute explicitly passing a transaction.
   */
  public int execute(CallableSql callableSql, Transaction t);

  /**
   * Execute a TxRunnable in a Transaction with an explicit scope.
   * <p>
   * The scope can control the transaction type, isolation and rollback
   * semantics.
   * </p>
   */
  public void execute(TxScope scope, TxRunnable r);

  /**
   * Execute a TxRunnable in a Transaction with the default scope.
   * <p>
   * The default scope runs with REQUIRED and by default will rollback on any
   * exception (checked or runtime).
   * </p>
   */
  public void execute(TxRunnable r);

  /**
   * Execute a TxCallable in a Transaction with an explicit scope.
   * <p>
   * The scope can control the transaction type, isolation and rollback
   * semantics.
   * </p>
   */
  public <T> T execute(TxScope scope, TxCallable<T> c);

  /**
   * Execute a TxCallable in a Transaction with the default scope.
   * <p>
   * The default scope runs with REQUIRED and by default will rollback on any
   * exception (checked or runtime).
   * </p>
   */
  public <T> T execute(TxCallable<T> c);

  /**
   * Return the manager of the server cache ("L2" cache).
   * 
   */
  public ServerCacheManager getServerCacheManager();

  /**
   * Return the BackgroundExecutor service for asynchronous processing of
   * queries.
   */
  public BackgroundExecutor getBackgroundExecutor();

  /**
   * Run the cache warming queries on all bean types that have one defined.
   * <p>
   * A cache warming query can be defined via {@link CacheStrategy}.
   * </p>
   */
  public void runCacheWarming();

  /**
   * Run the cache warming query for a specific bean type.
   * <p>
   * A cache warming query can be defined via {@link CacheStrategy}.
   * </p>
   */
  public void runCacheWarming(Class<?> beanType);

  /**
   * Return the JsonContext for reading/writing JSON.
   * @deprecated Please use #json instead.
   */
  public JsonContext createJsonContext();

  /**
   * Return the JsonContext for reading/writing JSON.
   */
  public JsonContext json();

}