org.chromattic.api
Interface ChromatticSession

public interface ChromatticSession

Version:

$Revision$

Author:

Julien Viet

Method Summary

void	addEventListener(EventListener listener)
void	close()
<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()
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 entity.
<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.Object parent, java.lang.Class<O> clazz, java.lang.String name) Creates a persistent instance of the specified object.
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 child) Persists a transient object.
java.lang.String	persist(java.lang.Object parent, java.lang.Object o, java.lang.String name) Persists a transient object.
java.lang.String	persist(java.lang.Object o, java.lang.String name) Persists a transient object.
void	remove(java.lang.Object o) Removes a specified entity.
void	save()
<E> void	setEmbedded(java.lang.Object o, java.lang.Class<E> embeddedType, E embedded) Attach the specified embedded object on the specified object when the embedded argument.
void	setName(java.lang.Object o, java.lang.String name) Updates the name of the specified entity.

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

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.

Parameters:

o - the object to persist

name - the object relative path to the root

Returns:

the object id

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 child)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                ChromatticException

Persists a transient object.

Parameters:

parent - the parent object

child - the object to persist

Returns:

the object id

Throws:

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

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.

Parameters:

o - the object to persist

Returns:

the object id

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.

Parameters:

parent - the parent object

o - the object to persist

name - the object relative name to the parent

Returns:

the object id

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 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.NullPointerException,
                    java.lang.IllegalArgumentException,
                    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.

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.NullPointerException - if any argument is null

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

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 entity.

Parameters:

o - the entity to get the status

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

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

Updates the name of the specified entity.

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

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 the specified embedded object on the specified object when the embedded argument.

Type Parameters:

E - the embedded type

Parameters:

o - the object

embeddedType - the embedded type class

embedded - the embedded

Throws:

java.lang.NullPointerException - if any argument is null

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

ChromatticException - any chromattic exception

addEventListener

void addEventListener(EventListener listener)

save

void save()
          throws ChromatticException

Throws:

ChromatticException

close

void close()

getJCRSession

javax.jcr.Session getJCRSession()