org.chromattic.api
Interface ChromatticSession

public interface ChromatticSession

The session manages Chromattic objects at runtime, it is obtained from a Chromattic instance. A session is meant to be used by one thread and not shared among threads.

Version:

$Revision$

Author:

Julien Viet

Method Summary

void	addEventListener(EventListener listener) Adds an event listener to this session.
void	close() Close and dispose the session.
<O> O	copy(java.lang.Object parent, O o, java.lang.String name) Clones a persistent object into a new persistent object.
<O> O	copy(O o, java.lang.String name) Clones a persistent object into a new persistent object.
<O> O	create(java.lang.Class<O> clazz) Creates a transient instance of the specified object.
<O> O	create(java.lang.Class<O> clazz, java.lang.String name) Creates a transient instance of the specified object.
<O> QueryBuilder<O>	createQueryBuilder(java.lang.Class<O> fromClass) Create a query builder.
<O> O	findById(java.lang.Class<O> clazz, java.lang.String id) Finds an object from its identifier or return null if no such object can be found.
<O> O	findByNode(java.lang.Class<O> clazz, javax.jcr.Node node) Finds an object mapped to the provided node.
<O> O	findByPath(java.lang.Class<O> clazz, java.lang.String relPath) Finds an object with a path relative to a chromattic root object.
<O> O	findByPath(java.lang.Class<O> clazz, java.lang.String path, boolean absolute) Finds an object given its specified path.
<O> O	findByPath(java.lang.Object origin, java.lang.Class<O> clazz, java.lang.String relPath) Finds an object with a path relative to a specified origin object.
<E> E	getEmbedded(java.lang.Object o, java.lang.Class<E> embeddedType) Returns a specified embedded object.
java.lang.String	getId(java.lang.Object o) Returns the id of a specified entity.
javax.jcr.Session	getJCRSession() Returns the underlying JCR session or null if the session is closed.
java.lang.String	getName(java.lang.Object o) Returns the name of a specified entity.
java.lang.String	getPath(java.lang.Object o) Returns the path of a specified entity.
Status	getStatus(java.lang.Object o) Returns the status of a specified object.
<O> O	insert(java.lang.Class<O> clazz, java.lang.String name) Creates a persistent instance of the specified object.
<O> O	insert(java.lang.Class<O> clazz, java.lang.String prefix, java.lang.String localName) Creates a persistent instance of the specified object.
<O> O	insert(java.lang.Object parent, java.lang.Class<O> clazz, java.lang.String name) Creates a persistent instance of the specified object.
<O> O	insert(java.lang.Object parent, java.lang.Class<O> clazz, java.lang.String prefix, java.lang.String localName) Creates a persistent instance of the specified object.
boolean	isClosed()
java.lang.String	persist(java.lang.Object o) Persists a transient object relative to the root node.
java.lang.String	persist(java.lang.Object parent, java.lang.Object o) Persists a transient object as a child of the specified parent.
java.lang.String	persist(java.lang.Object parent, java.lang.Object o, java.lang.String name) Persists a transient object as a child of the specified parent with the specified name.
java.lang.String	persist(java.lang.Object parent, java.lang.Object o, java.lang.String prefix, java.lang.String localName) Persists a transient object as a child of the specified parent with the specified name.
java.lang.String	persist(java.lang.Object o, java.lang.String name) Persists a transient object with the specified name.
java.lang.String	persist(java.lang.Object o, java.lang.String prefix, java.lang.String localName) Persists a transient object with the specified name.
void	remove(java.lang.Object o) Removes a specified entity.
void	save() Save the transient changes.
<E> void	setEmbedded(java.lang.Object o, java.lang.Class<E> embeddedType, E embedded) Attach or detach the specified embedded object on the specified object.
void	setName(java.lang.Object o, java.lang.String name) Rename a chromattic object, the behavior of this method depends on the current object status: Status.TRANSIENT: the object is merely associated with the name until it is persisted. Status.PERSISTENT: the object will be renamed with the new name. Status.REMOVED: An illegal state exception is thrown.

Method Detail

create

<O> O create(java.lang.Class<O> clazz)
         throws java.lang.NullPointerException,
                java.lang.IllegalArgumentException,
                ChromatticException

Creates a transient instance of the specified object.

Parameters:

clazz - the object class

Returns:

the instance

Throws:

java.lang.NullPointerException - if the specified clazz is null

java.lang.IllegalArgumentException - if the specified class is not a chromattic class

ChromatticException - any chromattic exception

create

<O> O create(java.lang.Class<O> clazz,
             java.lang.String name)
         throws java.lang.NullPointerException,
                java.lang.IllegalArgumentException,
                ChromatticException

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 NodeMapping annotation.

Type Parameters:

O - the object class parameter

Parameters:

clazz - the object class

name - the node name

Returns:

the transient object

Throws:

java.lang.NullPointerException - if the clazz argument is null

java.lang.IllegalArgumentException - if the name format is not valid or the class is not a chromattic class

ChromatticException - any chromattic exception

insert

<O> O insert(java.lang.Class<O> clazz,
             java.lang.String name)
         throws java.lang.NullPointerException,
                java.lang.IllegalArgumentException,
                ChromatticException

Creates a persistent instance of the specified object.

Type Parameters:

O - the object class parameter

Parameters:

clazz - the object class

name - the name under root node

Returns:

the persistent object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the name is not valid or the class is not a chromattic class

ChromatticException - any chromattic exception

insert

<O> O insert(java.lang.Class<O> clazz,
             java.lang.String prefix,
             java.lang.String localName)
         throws java.lang.NullPointerException,
                java.lang.IllegalArgumentException,
                ChromatticException

Creates a persistent instance of the specified object.

Type Parameters:

O - the object class parameter

Parameters:

clazz - the object class

prefix - the prefix under the root node

localName - the local name under root node

Returns:

the persistent object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the name is not valid or the class is not a chromattic class

ChromatticException - any chromattic exception

insert

<O> O insert(java.lang.Object parent,
             java.lang.Class<O> clazz,
             java.lang.String name)
         throws java.lang.NullPointerException,
                java.lang.IllegalArgumentException,
                ChromatticException

Creates a persistent instance of the specified object.

Type Parameters:

O - the object class parameter

Parameters:

parent - the parent object

clazz - the object class

name - the object name

Returns:

the persistent object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the name is not valid or the class is not a chromattic class or the parent is not a persistent object

ChromatticException - any chromattic exception

insert

<O> O insert(java.lang.Object parent,
             java.lang.Class<O> clazz,
             java.lang.String prefix,
             java.lang.String localName)
         throws java.lang.NullPointerException,
                java.lang.IllegalArgumentException,
                ChromatticException

Creates a persistent instance of the specified object.

Type Parameters:

O - the object class parameter

Parameters:

parent - the parent object

clazz - the object class

prefix - the object prefix

localName - the object local name

Returns:

the persistent object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the name is not valid or the class is not a chromattic class or the parent is not a persistent object

ChromatticException - any chromattic exception

persist

java.lang.String persist(java.lang.Object o,
                         java.lang.String name)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                ChromatticException

Persists a transient object with the specified name. The parent of the persisted object will implicitely be the root node of the session.

Parameters:

o - the object to persist

name - the object relative path to the root

Returns:

the id of the inserted object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the name is not valid or the object is not a chromattic transient object

ChromatticException - any chromattic exception

persist

java.lang.String persist(java.lang.Object o,
                         java.lang.String prefix,
                         java.lang.String localName)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                ChromatticException

Persists a transient object with the specified name. The parent of the persisted object will implicitely be the root node of the session.

Parameters:

o - the object to persist

prefix - the object prefix

localName - the object relative path to the root

Returns:

the id of the inserted object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the name is not valid or the object is not a chromattic transient object

ChromatticException - any chromattic exception

persist

java.lang.String persist(java.lang.Object parent,
                         java.lang.Object o)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                ChromatticException

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 persist(Object) method. Since no name is provided, this method implicitely expects a name associated with the object.

Parameters:

parent - the parent object

o - the object to persist

Returns:

the id of the inserted object

Throws:

java.lang.NullPointerException - if the child argument is null

java.lang.IllegalArgumentException - if the parent is not a persistent object or the object is not a chromattic transient object

ChromatticException - any chromattic exception

persist

java.lang.String persist(java.lang.Object o)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                ChromatticException

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.

Parameters:

o - the object to persist

Returns:

the id of the inserted object

Throws:

java.lang.NullPointerException - if any argument is not valid

java.lang.IllegalArgumentException - if the object is not a chromattic transient object

ChromatticException - any chromattic exception

persist

java.lang.String persist(java.lang.Object parent,
                         java.lang.Object o,
                         java.lang.String name)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                ChromatticException

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 persist(Object, String) method.

Parameters:

parent - the parent object

o - the object to persist

name - the object relative name to the parent

Returns:

the id of the inserted object

Throws:

java.lang.NullPointerException - if the object argument is null

java.lang.IllegalArgumentException - if the parent is not a persistent object or the name is not valid or the object is not a chromattic transient object

ChromatticException - any chromattic exception

persist

java.lang.String persist(java.lang.Object parent,
                         java.lang.Object o,
                         java.lang.String prefix,
                         java.lang.String localName)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                ChromatticException

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 persist(Object, String) method.

Parameters:

parent - the parent object

o - the object to persist

prefix - the object prefix

localName - the object relative local name to the parent

Returns:

the id of the inserted object

Throws:

java.lang.NullPointerException - if the object argument is null

java.lang.IllegalArgumentException - if the parent is not a persistent object or the name is not valid or the object is not a chromattic transient object

ChromatticException - any chromattic exception

copy

<O> O copy(java.lang.Object parent,
           O o,
           java.lang.String name)
       throws java.lang.NullPointerException,
              java.lang.IllegalArgumentException,
              ChromatticException

Clones a persistent object into a new persistent object.

Type Parameters:

O - the object type

Parameters:

parent - the parent object

o - the object to clone

name - the object name

Returns:

the cloned object

Throws:

java.lang.NullPointerException - if the parent or object argument is null

java.lang.IllegalArgumentException - if the parent is not a persistent object or the name is not valid or the object is not a chromattic persistent object

ChromatticException - any chromattic exception

copy

<O> O copy(O o,
           java.lang.String name)
       throws java.lang.NullPointerException,
              java.lang.IllegalArgumentException,
              ChromatticException

Clones a persistent object into a new persistent object.

Type Parameters:

O - the object type

Parameters:

o - the object to clone

name - the object name

Returns:

the cloned object

Throws:

java.lang.NullPointerException - if the parent or object argument is null

java.lang.IllegalArgumentException - if the parent is not a persistent object or the name is not valid or the object is not a chromattic persistent object

ChromatticException - any chromattic exception

findByPath

<O> O findByPath(java.lang.Object origin,
                 java.lang.Class<O> clazz,
                 java.lang.String relPath)
             throws java.lang.IllegalArgumentException,
                    java.lang.NullPointerException,
                    java.lang.ClassCastException,
                    ChromatticException

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 findById(Class, String) method.

Type Parameters:

O - the object type

Parameters:

origin - the origin object

clazz - the expected class

relPath - the path relative to the origin

Returns:

the object

Throws:

java.lang.IllegalArgumentException - if the origin object is not a chromattic object

java.lang.NullPointerException - if any argument except the origin is null

java.lang.ClassCastException - if the object cannot be cast to the specified class

ChromatticException - any chromattic exception

findByPath

<O> O findByPath(java.lang.Class<O> clazz,
                 java.lang.String relPath)
             throws java.lang.NullPointerException,
                    java.lang.ClassCastException,
                    ChromatticException

Finds an object with a path relative to a chromattic root object. If the object is not found then the method returns null.

Type Parameters:

O - the object type

Parameters:

clazz - the expected class

relPath - the path relative to the chromattic root

Returns:

the object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.ClassCastException - if the object cannot be cast to the specified class

ChromatticException - any chromattic exception

findByPath

<O> O findByPath(java.lang.Class<O> clazz,
                 java.lang.String path,
                 boolean absolute)
             throws java.lang.NullPointerException,
                    java.lang.ClassCastException,
                    ChromatticException

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 absolute method parameter. When the object is not found the method returns null.

Type Parameters:

O - the object type

Parameters:

clazz - the expected class

path - the path relative to the chromattic root

absolute - true when an absolute path must be provided

Returns:

the object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.ClassCastException - if the object cannot be cast to the specified class

ChromatticException - any chromattic exception

findByNode

<O> O findByNode(java.lang.Class<O> clazz,
                 javax.jcr.Node node)
             throws java.lang.NullPointerException,
                    java.lang.ClassCastException,
                    ChromatticException

Finds an object mapped to the provided node.

Type Parameters:

O - the object type

Parameters:

clazz - the expected class

node - the node

Returns:

the object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.ClassCastException - if the mapped object cannot be cast to the specified class

ChromatticException - any chromattic exception

findById

<O> O findById(java.lang.Class<O> clazz,
               java.lang.String id)
           throws java.lang.NullPointerException,
                  java.lang.ClassCastException,
                  ChromatticException

Finds an object from its identifier or return null if no such object can be found.

Type Parameters:

O - the object type

Parameters:

clazz - the expected class

id - the id

Returns:

the object

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.ClassCastException - if the mapped object cannot be cast to the specified class

ChromatticException - any chromattic exception

createQueryBuilder

<O> QueryBuilder<O> createQueryBuilder(java.lang.Class<O> fromClass)
                                   throws java.lang.NullPointerException,
                                          java.lang.IllegalArgumentException,
                                          ChromatticException

Create a query builder.

Type Parameters:

O - the object type parameter

Parameters:

fromClass - the node type of the from clause

Returns:

a query builder

Throws:

java.lang.NullPointerException - if the argument is null

java.lang.IllegalArgumentException - if the from class cannot be mapped to a node type

ChromatticException - any chromattic exception

remove

void remove(java.lang.Object o)
            throws java.lang.NullPointerException,
                   java.lang.IllegalArgumentException,
                   ChromatticException

Removes a specified entity.

Parameters:

o - the entity to remove

Throws:

ChromatticException - any chromattic exception

java.lang.NullPointerException - if the specified object is null

java.lang.IllegalArgumentException - if the specified object is not a chromattic object

getStatus

Status getStatus(java.lang.Object o)
                 throws java.lang.NullPointerException,
                        java.lang.IllegalArgumentException,
                        ChromatticException

Returns the status of a specified object. If the object is an entity it may return:

• Status.TRANSIENT when the entity is created but not yet in correspondance with a node
• Status.PERSISTENT when the entity is in correspondance with a non removed node
• Status.REMOVED when the entity is in correspondance with a removed node

If the object is embedded it may return:

• Status.TRANSIENT when the embedded is created but not yet in correspondance with a node
• Status.PERSISTENT or Status.REMOVED when the embedded is attached to a node according to this node's status

Parameters:

o - the object to get the status

Returns:

the object status

Throws:

ChromatticException - any chromattic exception

java.lang.NullPointerException - if the specified object is null

java.lang.IllegalArgumentException - if the specified object is not a chromattic object

getId

java.lang.String getId(java.lang.Object o)
                       throws java.lang.NullPointerException,
                              java.lang.IllegalArgumentException,
                              ChromatticException

Returns the id of a specified entity.

Parameters:

o - the entity to get the id

Returns:

the entity id

Throws:

ChromatticException - any chromattic exception

java.lang.NullPointerException - if the specified object is null

java.lang.IllegalArgumentException - if the specified object is not a chromattic object

getName

java.lang.String getName(java.lang.Object o)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                ChromatticException

Returns the name of a specified entity.

Parameters:

o - the entity to get the name

Returns:

the entity status

Throws:

ChromatticException - any chromattic exception

java.lang.NullPointerException - if the specified object is null

java.lang.IllegalArgumentException - if the specified object is not a chromattic object

setName

void setName(java.lang.Object o,
             java.lang.String name)
             throws java.lang.NullPointerException,
                    java.lang.IllegalArgumentException,
                    ChromatticException

Rename a chromattic object, the behavior of this method depends on the current object status:

• Status.TRANSIENT: the object is merely associated with the name until it is persisted.
• Status.PERSISTENT: the object will be renamed with the new name.
• Status.REMOVED: An illegal state exception is thrown.

• Parameters:

  o - the entity to get the name

  name - the new entity name

  Throws:

  ChromatticException - any chromattic exception

  java.lang.NullPointerException - if the specified object is null

  java.lang.IllegalArgumentException - if the specified object is not a chromattic object or has been destroyed.

getPath

java.lang.String getPath(java.lang.Object o)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                ChromatticException

Returns the path of a specified entity.

Parameters:

o - the entity to get the path

Returns:

the entity path

Throws:

ChromatticException - any chromattic exception

java.lang.NullPointerException - if the specified object is null

java.lang.IllegalArgumentException - if the specified object is not a chromattic object

getEmbedded

<E> E getEmbedded(java.lang.Object o,
                  java.lang.Class<E> embeddedType)
              throws java.lang.NullPointerException,
                     java.lang.IllegalArgumentException,
                     ChromatticException

Returns a specified embedded object.

Type Parameters:

E - the embedded type

Parameters:

o - the object to get the embedded from

embeddedType - the embedded type class

Returns:

the related embedded

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the specified object is not a chromattic object

ChromatticException - any chromattic exception

setEmbedded

<E> void setEmbedded(java.lang.Object o,
                     java.lang.Class<E> embeddedType,
                     E embedded)
                 throws java.lang.NullPointerException,
                        java.lang.IllegalArgumentException,
                        ChromatticException

Attach or detach the specified embedded object on the specified object. When the embedded argument is not null and in Status.TRANSIENT state the embedded is attached to the object if the underlying type system allows it. When the embedded argument is null, the embedded is removed from the object when the underlying type system allows it.

Type Parameters:

E - the embedded type

Parameters:

o - the object

embeddedType - the embedded type class

embedded - the embedded

Throws:

java.lang.NullPointerException - if the object or type is null

java.lang.IllegalArgumentException - if the object or the embedded are not chromattic objects

ChromatticException - any chromattic exception

addEventListener

void addEventListener(EventListener listener)
                      throws java.lang.NullPointerException

Adds an event listener to this session.

Parameters:

listener - the listener to add

Throws:

java.lang.NullPointerException - if the provided listener is null

save

void save()
          throws ChromatticException

Save the transient changes.

Throws:

ChromatticException - any chromattic exception

close

void close()

Close and dispose the session.

isClosed

boolean isClosed()

getJCRSession

javax.jcr.Session getJCRSession()

Returns the underlying JCR session or null if the session is closed.

Returns:

the JCR session.