org.chromattic.api
Interface ChromatticSession

public interface ChromatticSession

Version:

$Revision$

Author:

Julien Viet

Method Summary

void	addEventListener(EventListener listener)
void	close()
<O> O	create(Class<O> clazz) Creates a transient instance of the specified object.
<O> O	create(Class<O> clazz, String name) Creates a transient instance of the specified object.
<O> QueryBuilder<O>	createQueryBuilder(Class<O> fromClass) Create a query builder.
<O> O	findById(Class<O> clazz, String id) Finds an object from its identifier or return null if no such object can be found.
<O> O	findByNode(Class<O> clazz, javax.jcr.Node node) Finds an object mapped to the provided node.
<O> O	findByPath(Class<O> clazz, String relPath) Finds an object with a path relative to a chromattic root object.
<O> O	findByPath(Object origin, Class<O> clazz, String relPath) Finds an object with a path relative to a specified origin object.
<E> E	getEmbedded(Object o, Class<E> embeddedType) Returns a specified embedded object.
String	getId(Object o) Returns the id of a specified entity.
javax.jcr.Session	getJCRSession()
String	getName(Object o) Returns the name of a specified entity.
String	getPath(Object o) Returns the path of a specified entity.
Status	getStatus(Object o) Returns the status of a specified entity.
<O> O	insert(Class<O> clazz, String name) Creates a persistent instance of the specified object.
<O> O	insert(Object parent, Class<O> clazz, String name) Creates a persistent instance of the specified object.
String	persist(Object o) Persists a transient object relative to the root node.
String	persist(Object parent, Object child) Persists a transient object.
String	persist(Object parent, Object o, String name) Persists a transient object.
String	persist(Object o, String name) Persists a transient object.
void	remove(Object o) Removes a specified entity.
void	save()
<E> void	setEmbedded(Object o, Class<E> embeddedType, E embedded) Attach the specified embedded object on the specified object when the embedded argument.

Method Detail

create

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

Creates a transient instance of the specified object.

Parameters:

clazz - the object class

Returns:

the instance

Throws:

NullPointerException - if the specified clazz is null

IllegalArgumentException - if the specified class is not a chromattic class

ChromatticException - any chromattic exception

create

<O> O create(Class<O> clazz,
             String name)
         throws NullPointerException,
                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:

NullPointerException - if the clazz argument is null

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

ChromatticException - any chromattic exception

insert

<O> O insert(Class<O> clazz,
             String name)
         throws NullPointerException,
                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:

NullPointerException - if any argument is null

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

ChromatticException - any chromattic exception

insert

<O> O insert(Object parent,
             Class<O> clazz,
             String name)
         throws NullPointerException,
                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:

NullPointerException - if any argument is null

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

String persist(Object o,
               String name)
               throws NullPointerException,
                      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:

NullPointerException - if any argument is null

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

ChromatticException - any chromattic exception

persist

String persist(Object parent,
               Object child)
               throws NullPointerException,
                      IllegalArgumentException,
                      ChromatticException

Persists a transient object.

Parameters:

parent - the parent object

child - the object to persist

Returns:

the object id

Throws:

NullPointerException - if any argument is not valid

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

ChromatticException - any chromattic exception

persist

String persist(Object o)
               throws NullPointerException,
                      IllegalArgumentException,
                      ChromatticException

Persists a transient object relative to the root node.

Parameters:

o - the object to persist

Returns:

the object id

Throws:

NullPointerException - if any argument is not valid

IllegalArgumentException - if the object is not a chromattic transient object

ChromatticException - any chromattic exception

persist

String persist(Object parent,
               Object o,
               String name)
               throws NullPointerException,
                      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:

NullPointerException - if the parent or object argument is null

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

findByPath

<O> O findByPath(Object origin,
                 Class<O> clazz,
                 String relPath)
             throws NullPointerException,
                    IllegalArgumentException,
                    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:

NullPointerException - if any argument is null

IllegalArgumentException - if the origin object is not a chromattic object

ClassCastException - if the object cannot be cast to the specified class

ChromatticException - any chromattic exception

findByPath

<O> O findByPath(Class<O> clazz,
                 String relPath)
             throws NullPointerException,
                    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:

NullPointerException - if any argument is null

ClassCastException - if the object cannot be cast to the specified class

ChromatticException - any chromattic exception

findByNode

<O> O findByNode(Class<O> clazz,
                 javax.jcr.Node node)
             throws NullPointerException,
                    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:

NullPointerException - if any argument is null

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

ChromatticException - any chromattic exception

findById

<O> O findById(Class<O> clazz,
               String id)
           throws NullPointerException,
                  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:

NullPointerException - if any argument is null

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

ChromatticException - any chromattic exception

createQueryBuilder

<O> QueryBuilder<O> createQueryBuilder(Class<O> fromClass)
                                   throws NullPointerException,
                                          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:

NullPointerException - if the argument is null

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

ChromatticException - any chromattic exception

remove

void remove(Object o)
            throws NullPointerException,
                   IllegalArgumentException,
                   ChromatticException

Removes a specified entity.

Parameters:

o - the entity to remove

Throws:

ChromatticException - any chromattic exception

NullPointerException - if the specified object is null

IllegalArgumentException - if the specified object is not a chromattic object

getStatus

Status getStatus(Object o)
                 throws NullPointerException,
                        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

NullPointerException - if the specified object is null

IllegalArgumentException - if the specified object is not a chromattic object

getId

String getId(Object o)
             throws NullPointerException,
                    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

NullPointerException - if the specified object is null

IllegalArgumentException - if the specified object is not a chromattic object

getName

String getName(Object o)
               throws NullPointerException,
                      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

NullPointerException - if the specified object is null

IllegalArgumentException - if the specified object is not a chromattic object

getPath

String getPath(Object o)
               throws NullPointerException,
                      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

NullPointerException - if the specified object is null

IllegalArgumentException - if the specified object is not a chromattic object

getEmbedded

<E> E getEmbedded(Object o,
                  Class<E> embeddedType)
              throws NullPointerException,
                     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:

NullPointerException - if any argument is null

IllegalArgumentException - if the specified object is not a chromattic object

ChromatticException - any chromattic exception

setEmbedded

<E> void setEmbedded(Object o,
                     Class<E> embeddedType,
                     E embedded)
                 throws NullPointerException,
                        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:

NullPointerException - if any argument is null

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()