ORMSession.java

package org.etk.orm.api;

import javax.jcr.Node;
import javax.jcr.Session;

import org.etk.orm.api.event.EventListener;
import org.etk.orm.plugins.query.QueryBuilder;

/**
 * The session manages ORM objects at runtime, it is obtained from a {@link org.etk.orm.api.ORM}
 * instance.  A session is meant to be used by one thread and not shared among threads. 
 *
 */
public interface ORMSession {

  /**
   * Creates a transient instance of the specified object.
   *
   * @param clazz the object class
   * @return the instance
   * @throws NullPointerException if the specified clazz is null
   * @throws IllegalArgumentException if the specified class is not a ORM class
   * @throws ORMException any orm exception
   */
  <O> O create(Class<O> clazz) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Creates a transient instance of the specified object. The name if it is not null will be used
   * later when the object is inserted in the JCR session. The clazz argument must be annotated class with
   * the <tt>NodeMapping</tt> annotation.
   *
   * @param clazz the object class
   * @param name the node name
   * @param <O> the object class parameter
   * @return the transient object
   * @throws NullPointerException if the clazz argument is null
   * @throws IllegalArgumentException if the name format is not valid or the class is not a orm class
   * @throws ORMException any orm exception
   */
  <O> O create(Class<O> clazz, String name) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Creates a persistent instance of the specified object.
   *
   * @param clazz the object class
   * @param name the name under root node
   * @param <O> the object class parameter
   * @return the persistent object
   * @throws NullPointerException if any argument is null
   * @throws IllegalArgumentException if the name is not valid or the class is not a orm class
   * @throws ORMException any orm exception
   */
  <O> O insert(Class<O> clazz, String name) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Creates a persistent instance of the specified object.
   *
   * @param clazz the object class
   * @param prefix the prefix under the root node
   * @param localName the local name under root node
   * @param <O> the object class parameter
   * @return the persistent object
   * @throws NullPointerException if any argument is null
   * @throws IllegalArgumentException if the name is not valid or the class is not a orm class
   * @throws ORMException any orm exception
   */
  <O> O insert(Class<O> clazz, String prefix, String localName) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Creates a persistent instance of the specified object.
   *
   * @param parent the parent object
   * @param clazz the object class
   * @param name the object name
   * @param <O> the object class parameter
   * @return the persistent object
   * @throws NullPointerException if any argument is null
   * @throws IllegalArgumentException if the name is not valid or the class is not a orm class or the parent is
   * not a persistent object
   * @throws ORMException any orm exception
   */
  <O> O insert(Object parent, Class<O> clazz, String name) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Creates a persistent instance of the specified object.
   *
   * @param parent the parent object
   * @param clazz the object class
   * @param prefix the object prefix
   * @param localName the object local name
   * @param <O> the object class parameter
   * @return the persistent object
   * @throws NullPointerException if any argument is null
   * @throws IllegalArgumentException if the name is not valid or the class is not a orm class or the parent is
   * not a persistent object
   * @throws ORMException any orm exception
   */
  <O> O insert(Object parent, Class<O> clazz, String prefix, String localName) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Persists a transient object with the specified name. The parent of the persisted object will implicitely be the
   * root node of the session.
   *
   * @param o the object to persist
   * @param name the object relative path to the root
   * @return the id of the inserted object
   * @throws NullPointerException if any argument is null
   * @throws IllegalArgumentException if the name is not valid or the object is not a orm transient object
   * @throws ORMException any orm exception
   */
  String persist(Object o, String name) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Persists a transient object with the specified name. The parent of the persisted object will implicitely be the
   * root node of the session.
   *
   * @param o the object to persist
   * @param prefix the object prefix
   * @param localName the object relative path to the root
   * @return the id of the inserted object
   * @throws NullPointerException if any argument is null
   * @throws IllegalArgumentException if the name is not valid or the object is not a orm transient object
   * @throws ORMException any orm exception
   */
  String persist(Object o, String prefix, String localName) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Persists a transient object as a child of the specified parent. The parent argument is optional and null can be
   * passed, in that case it is equivalent to call the {@link #persist(Object)} method. Since no name is provided, this
   * method implicitely expects a name associated with the object.
   *
   * @param parent the parent object
   * @param o the object to persist
   * @return the id of the inserted object
   * @throws NullPointerException if the child argument is null
   * @throws IllegalArgumentException if the parent is not a persistent object or the object is not a orm transient object
   * @throws ORMException any orm exception
   */
  String persist(Object parent, Object o) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Persists a transient object relative to the root node. The parent of the persisted object will implicitely be the
   * root node of the session. Since no name is provided, this method implicitely expects a name associated with the object.
   *
   * @param o the object to persist
   * @return the id of the inserted object
   * @throws NullPointerException if any argument is not valid
   * @throws IllegalArgumentException if the object is not a orm transient object
   * @throws ORMException any orm exception
   */
  String persist(Object o) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Persists a transient object as a child of the specified parent with the specified name. The parent argument is
   * optional and null can be passed, in that case it is equivalent to call the {@link #persist(Object, String)} method.
   *
   * @param parent the parent object
   * @param o the object to persist
   * @param name the object relative name to the parent
   * @return the id of the inserted object
   * @throws NullPointerException if the object argument is null
   * @throws IllegalArgumentException if the parent is not a persistent object or the name is not valid or the object
   * is not a orm transient object
   * @throws ORMException any orm exception
   */
  String persist(Object parent, Object o, String name) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Persists a transient object as a child of the specified parent with the specified name. The parent argument is
   * optional and null can be passed, in that case it is equivalent to call the {@link #persist(Object, String)} method.
   *
   * @param parent the parent object
   * @param o the object to persist
   * @param prefix the object prefix
   * @param localName the object relative local name to the parent
   * @return the id of the inserted object
   * @throws NullPointerException if the object argument is null
   * @throws IllegalArgumentException if the parent is not a persistent object or the name is not valid or the object
   * is not a orm transient object
   * @throws ORMException any orm exception
   */
  String persist(Object parent, Object o, String prefix, String localName) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Clones a persistent object into a new persistent object.
   *
   * @param parent the parent object
   * @param o the object to clone
   * @param name the object name
   * @param <O> the object type
   * @return the cloned object
   * @throws NullPointerException if the parent or object argument is null
   * @throws IllegalArgumentException if the parent is not a persistent object or the name is not valid or the object
   * is not a orm persistent object
   * @throws ORMException any orm exception
   */
  <O> O copy(Object parent, O o, String name) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Clones a persistent object into a new persistent object.
   *
   * @param o the object to clone
   * @param name the object name
   * @param <O> the object type
   * @return the cloned object
   * @throws NullPointerException if the parent or object argument is null
   * @throws IllegalArgumentException if the parent is not a persistent object or the name is not valid or the object
   * is not a orm persistent object
   * @throws ORMException any orm exception
   */
  <O> O copy(O o, String name) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Finds an object with a path relative to a specified origin object. If the object is not found then the method returns null.
   * The origin argument is optional and null can be passed, in that case it is equivalent to call the {@link #findById(Class, String)}
   * method.
   *
   * @param origin the origin object
   * @param clazz the expected class
   * @param relPath the path relative to the origin
   * @param <O> the object type
   * @return the object
   * @throws IllegalArgumentException if the origin object is not a orm object
   * @throws NullPointerException if any argument except the origin is null
   * @throws ClassCastException if the object cannot be cast to the specified class
   * @throws ORMException any orm exception
   */
  <O> O findByPath(Object origin, Class<O> clazz, String relPath) throws IllegalArgumentException, NullPointerException, ClassCastException, ORMException;

  /**
   * Finds an object with a path relative to a orm root object. If the object is not found then the method returns null.
   *
   * @param clazz the expected class
   * @param relPath the path relative to the orm root
   * @param <O> the object type
   * @return the object
   * @throws NullPointerException if any argument is null
   * @throws ClassCastException if the object cannot be cast to the specified class
   * @throws ORMException any orm exception
   */
  <O> O findByPath(Class<O> clazz, String relPath) throws NullPointerException, ClassCastException, ORMException;

  /**
   * Finds an object given its specified path. The provided path can either be absolute or relative to the
   * root node of the session according to the value of the <code>absolute</code> method parameter. When the object
   * is not found the method returns null.
   *
   * @param clazz the expected class
   * @param path the path relative to the orm root
   * @param <O> the object type
   * @param absolute true when an absolute path must be provided
   * @return the object
   * @throws NullPointerException if any argument is null
   * @throws ClassCastException if the object cannot be cast to the specified class
   * @throws ORMException any orm exception
   */
  <O> O findByPath(Class<O> clazz, String path, boolean absolute) throws NullPointerException, ClassCastException, ORMException;

  /**
   * Finds an object mapped to the provided node.
   *
   * @param clazz the expected class
   * @param node the node
   * @param <O> the object type
   * @return the object
   * @throws NullPointerException if any argument is null
   * @throws ClassCastException if the mapped object cannot be cast to the specified class
   * @throws ORMException any orm exception
   */
  <O> O findByNode(Class<O> clazz, Node node) throws NullPointerException, ClassCastException, ORMException;

  /**
   * Finds an object from its identifier or return null if no such object can be found.
   *
   * @param clazz the expected class
   * @param id the id
   * @param <O> the object type
   * @return the object
   * @throws NullPointerException if any argument is null
   * @throws ClassCastException if the mapped object cannot be cast to the specified class
   * @throws ORMException any orm exception
   */
  <O> O findById(Class<O> clazz, String id) throws NullPointerException, ClassCastException, ORMException;

  /**
   * Create a query builder.
   *
   * @param fromClass the node type of the from clause
   * @param <O> the object type parameter
   * @return a query builder
   * @throws NullPointerException if the argument is null
   * @throws IllegalArgumentException if the from class cannot be mapped to a node type
   * @throws ORMException any orm exception
   */
  <O> QueryBuilder<O> createQueryBuilder(Class<O> fromClass) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Removes a specified entity.
   *
   * @param o the entity to remove
   * @throws ORMException any orm exception
   * @throws NullPointerException if the specified object is null
   * @throws IllegalArgumentException if the specified object is not a orm object
   */
  void remove(Object o) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Returns the status of a specified entity.
   *
   * @param o the entity to get the status
   * @return the entity status
   * @throws ORMException any chromattic exception
   * @throws NullPointerException if the specified object is null
   * @throws IllegalArgumentException if the specified object is not a orm object
   */
  Status getStatus(Object o) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Returns the id of a specified entity.
   *
   * @param o the entity to get the id
   * @return the entity id
   * @throws ORMException any chromattic exception
   * @throws NullPointerException if the specified object is null
   * @throws IllegalArgumentException if the specified object is not a orm object
   */
  String getId(Object o) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Returns the name of a specified entity.
   *
   * @param o the entity to get the name
   * @return the entity status
   * @throws ORMException any chromattic exception
   * @throws NullPointerException if the specified object is null
   * @throws IllegalArgumentException if the specified object is not a orm object
   */
  String getName(Object o) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Rename a orm object, the behavior of this method depends on the current object status:
   *
   * <ul>
   * <li>{@link Status#TRANSIENT}: the object is merely associated with the name until it is persisted.</li>
   * <li>{@link Status#PERSISTENT}: the object will be renamed with the new name.</li>
   * <li>{@link Status#REMOVED}: An illegal state exception is thrown.</li>
   * <lI>
   *
   * @param o the entity to get the name
   * @param name the new entity name
   * @throws ORMException any chromattic exception
   * @throws NullPointerException if the specified object is null
   * @throws IllegalArgumentException if the specified object is not a orm object or has been destroyed.
   */
  void setName(Object o, String name) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Returns the path of a specified entity.
   *
   * @param o the entity to get the path
   * @return the entity path
   * @throws ORMException any chromattic exception
   * @throws NullPointerException if the specified object is null
   * @throws IllegalArgumentException if the specified object is not a orm object
   */
  String getPath(Object o) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Returns a specified embedded object.
   *
   * @param o the object to get the embedded from
   * @param embeddedType the embedded type class
   * @param <E> the embedded type
   * @return the related embedded
   * @throws NullPointerException if any argument is null
   * @throws IllegalArgumentException if the specified object is not a chromattic object
   * @throws ORMException any orm exception
   */
  <E> E getEmbedded(Object o, Class<E> embeddedType) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Attach the specified embedded object on the specified object when the embedded argument.
   *
   * @param o the object
   * @param embeddedType the embedded type class
   * @param embedded the embedded
   * @param <E> the embedded type
   * @throws NullPointerException if any argument is null
   * @throws IllegalArgumentException if the object or the embedded are not orm objects
   * @throws ORMException any orm exception
   */
  <E> void setEmbedded(Object o, Class<E> embeddedType, E embedded) throws NullPointerException, IllegalArgumentException, ORMException;

  /**
   * Adds an event listener to this session.
   *
   * @param listener the listener to add
   * @throws NullPointerException if the provided listener is null
   */
  void addEventListener(EventListener listener) throws NullPointerException;

  /**
   * Save the transient changes.
   *
   * @throws ORMException any orm exception
   */
  void save() throws ORMException;

  /**
   * Close and dispose the session.
   */
  void close();

  boolean isClosed();

  /**
   * Returns the underlying JCR session or null if the session is closed.
   *
   * @return the JCR session.
   */
  Session getJCRSession();
}