org.nuiton.topia

Interface TopiaContext

All Known Subinterfaces:

TopiaContextImplementor

All Known Implementing Classes:

TopiaContextImpl

public interface TopiaContext

The TopiaContext is the most important class of ToPIA. It contains all the methods to manipulate data : transaction management, entities querying, event firing, schema management, services management, ...

To get an instance of TopiaContext, see TopiaContextFactory.getContext(java.util.Properties)

Created: 3 janv. 2006 21:18:34

Version:

$Id: TopiaContext.java 2778 2013-07-22 23:57:38Z athimel $

Author:

poussin , tchemit , athimel

Method Summary

Methods

Modifier and Type	Method and Description
void	add(TopiaEntity e) Add into this TopiaContext an entity created by another TopiaContext
void	addPropertyChangeListener(PropertyChangeListener listener) Register to the context a PropertyChangeListener about some entity's property change.
void	addTopiaContextListener(TopiaContextListener listener) Deprecated. Use addTopiaSchemaListener
void	addTopiaEntitiesVetoable(TopiaEntitiesVetoable vetoable) Register to the context a TopiaEntitiesVetoable about any TopiaEntity.
void	addTopiaEntityListener(Class<? extends TopiaEntity> entityClass, TopiaEntityListener listener) Register to the context a TopiaEntityListener about the given entity class.
void	addTopiaEntityListener(TopiaEntityListener listener) Register to the context a TopiaEntityListener about any TopiaEntity.
void	addTopiaEntityVetoable(Class<? extends TopiaEntity> entityClass, TopiaEntityVetoable vetoable) Register to the context a TopiaEntityVetoable about the given entity class.
void	addTopiaEntityVetoable(TopiaEntityVetoable vetoable) Register to the context a TopiaEntityVetoable about any TopiaEntity.
void	addTopiaSchemaListener(TopiaSchemaListener listener) Register to the context a TopiaSchemaListener about any schema modification.
void	addTopiaTransactionListener(TopiaTransactionListener listener) Register to the context a TopiaTransactionListener about the transaction.
void	addTopiaTransactionVetoable(TopiaTransactionVetoable vetoable) Register to the context a TopiaTransactionVetoable about the transaction.
void	backup(File file, boolean compress) Deprecated. Only H2 compatible : remove it, or move to another class
TopiaContext	beginTransaction() Returns a new context containing its own transaction.
void	clear(boolean dropDatabase) Deprecated. Only H2 compatible : remove it, or move to another class
void	clearCache() Clear persistence implementation cache.
void	closeContext() Closes the context.
void	commitTransaction() Applies all the modifications made to this context on the persistence device.
void	createSchema() Triggers database schema creation
void	dropSchema() Triggers database schema drop
void	evict(TopiaEntity e) Detaches the given entity from the session
int	execute(String hql, Object... propertyNamesAndValues) Execute HQL operation on data (Update, Delete).
void	executeSQL(String sqlScript) Execute a given sql code inside this transaction.
<E> List<E>	find(String hql, int startIndex, int endIndex, Object... propertyNamesAndValues) Allow to do some JPA-QL query using the given bounds.
<E> List<E>	findAll(String hql, Object... propertyNamesAndValues) Allow to do some HQL query WARNING : Depending on the registered service, this method may not support something else than queries on TopiaEntity
<E extends TopiaEntity> E	findByTopiaId(String topiaId) Retrieve TopiaEntity using its unique id.
<E> E	findUnique(String hql, Object... propertyNamesAndValues) Allow to do some HQL query and return an unique result.
<E extends TopiaService> E	getService(Class<E> interfaceService) Return the service.
boolean	isClosed() Tells if the context is closed
void	removePropertyChangeListener(PropertyChangeListener listener) Unregister the given PropertyChangeListener about some entity's property change from the context
void	removeTopiaContextListener(TopiaContextListener listener) Deprecated. Use removeTopiaSchemaListener
void	removeTopiaEntitiesVetoable(TopiaEntitiesVetoable vetoable) Unregister the given TopiaEntitiesVetoable about any TopiaEntity from the context
void	removeTopiaEntityListener(Class<? extends TopiaEntity> entityClass, TopiaEntityListener listener) Unregister the given TopiaEntityListener about the given entity class from the context
void	removeTopiaEntityListener(TopiaEntityListener listener) Unregister the given TopiaEntityListener about any TopiaEntity from the context
void	removeTopiaEntityVetoable(Class<? extends TopiaEntity> entityClass, TopiaEntityVetoable vetoable) Unregister the given TopiaEntityVetoable about the given entity class from the context
void	removeTopiaEntityVetoable(TopiaEntityVetoable vetoable) Unregister the given TopiaEntityVetoable about any TopiaEntity from the context
void	removeTopiaSchemaListener(TopiaSchemaListener listener) Unregister the given TopiaSchemaListener about any schema modification from the context
void	removeTopiaTransactionListener(TopiaTransactionListener listener) Unregister the given TopiaTransactionListener about the transaction from the context
void	removeTopiaTransactionVetoable(TopiaTransactionVetoable vetoable) Unregister the given TopiaTransactionVetoable about the transaction from the context
void	replicate(TopiaContext destinationContext, Object... entityAndCondition) Makes a replication of some entities from this context to the given context without any entity modification.
<T extends TopiaEntity> void	replicateEntities(TopiaContext destinationContext, List<T> entities) Makes a replication of some entities from this context to the given context without any entity modification.
<T extends TopiaEntity> void	replicateEntity(TopiaContext destinationContext, T entity) Replicate a given entity from this context to the given context.
void	restore(File file) Deprecated. Only H2 compatible : remove it, or move to another class
void	rollbackTransaction() Cancels all the modifications made to this context, coming back to the state on the last beginTransaction.
<E extends TopiaService> boolean	serviceEnabled(Class<E> interfaceService) Return true if specific service is available.
void	showCreateSchema() Displays the SQL queries that would be used for a schema creation
void	updateSchema() Triggers database schema update

Method Detail

beginTransaction

TopiaContext beginTransaction()
                              throws TopiaException

Returns a new context containing its own transaction.

Returns:

new context with transaction

Throws:

TopiaException - if any exception

commitTransaction

void commitTransaction()
                       throws TopiaException

Applies all the modifications made to this context on the persistence device. Once commit is done, a new transaction is started.

Throws:

TopiaException - if any exception

rollbackTransaction

void rollbackTransaction()
                         throws TopiaException

Cancels all the modifications made to this context, coming back to the state on the last beginTransaction. Once rollback is done, a new transaction is started.

Throws:

TopiaException - if any exception

closeContext

void closeContext()
                  throws TopiaException

Closes the context. All the children contexts will be closed in the same time.

Throws:

TopiaException - if any exception

isClosed

boolean isClosed()

Tells if the context is closed

Returns:

true if the context is closed, false otherwise

addTopiaEntityListener

void addTopiaEntityListener(TopiaEntityListener listener)

Register to the context a TopiaEntityListener about any TopiaEntity. listener instance will be notified AFTER any operation on the entity.

Parameters:

listener - the listener instance to register

addTopiaEntityListener

void addTopiaEntityListener(Class<? extends TopiaEntity> entityClass,
                          TopiaEntityListener listener)

Register to the context a TopiaEntityListener about the given entity class. listener instance will be notified AFTER any operation on the entity.

Parameters:

entityClass - the TopiaEntity's class to listen

listener - the listener instance to register

removeTopiaEntityListener

void removeTopiaEntityListener(TopiaEntityListener listener)

Unregister the given TopiaEntityListener about any TopiaEntity from the context

Parameters:

listener - the listener instance to unregister

removeTopiaEntityListener

void removeTopiaEntityListener(Class<? extends TopiaEntity> entityClass,
                             TopiaEntityListener listener)

Unregister the given TopiaEntityListener about the given entity class from the context

Parameters:

entityClass - the listened TopiaEntity's class

listener - the listener instance to unregister

addTopiaEntityVetoable

void addTopiaEntityVetoable(TopiaEntityVetoable vetoable)

Register to the context a TopiaEntityVetoable about any TopiaEntity. vetoable instance will be notified BEFORE any operation on the entity.

Parameters:

vetoable - the vetoable instance to register

addTopiaEntityVetoable

void addTopiaEntityVetoable(Class<? extends TopiaEntity> entityClass,
                          TopiaEntityVetoable vetoable)

Register to the context a TopiaEntityVetoable about the given entity class. vetoable instance will be notified BEFORE any operation on the entity.

Parameters:

entityClass - the TopiaEntity's class to listen

vetoable - the vetoable instance to register

removeTopiaEntityVetoable

void removeTopiaEntityVetoable(TopiaEntityVetoable vetoable)

Unregister the given TopiaEntityVetoable about any TopiaEntity from the context

Parameters:

vetoable - the vetoable instance to unregister

removeTopiaEntityVetoable

void removeTopiaEntityVetoable(Class<? extends TopiaEntity> entityClass,
                             TopiaEntityVetoable vetoable)

Unregister the given TopiaEntityVetoable about the given entity class from the context

Parameters:

entityClass - the listened TopiaEntity's class

vetoable - the vetoable instance to unregister

addTopiaEntitiesVetoable

void addTopiaEntitiesVetoable(TopiaEntitiesVetoable vetoable)

Register to the context a TopiaEntitiesVetoable about any TopiaEntity. vetoable instance will be notified BEFORE any entity load

Parameters:

vetoable - the vetoable instance to register

removeTopiaEntitiesVetoable

void removeTopiaEntitiesVetoable(TopiaEntitiesVetoable vetoable)

Unregister the given TopiaEntitiesVetoable about any TopiaEntity from the context

Parameters:

vetoable - the vetoable instance to unregister

addTopiaTransactionListener

void addTopiaTransactionListener(TopiaTransactionListener listener)

Register to the context a TopiaTransactionListener about the transaction. listener instance will be notified AFTER any operation on the transaction.

Parameters:

listener - the listener instance to register

removeTopiaTransactionListener

void removeTopiaTransactionListener(TopiaTransactionListener listener)

Unregister the given TopiaTransactionListener about the transaction from the context

Parameters:

listener - the listener instance to unregister

addTopiaTransactionVetoable

void addTopiaTransactionVetoable(TopiaTransactionVetoable vetoable)

Register to the context a TopiaTransactionVetoable about the transaction. vetoable instance will be notified BEFORE any operation on the transaction.

Parameters:

vetoable - the vetoable instance to register

removeTopiaTransactionVetoable

void removeTopiaTransactionVetoable(TopiaTransactionVetoable vetoable)

Unregister the given TopiaTransactionVetoable about the transaction from the context

Parameters:

vetoable - the vetoable instance to unregister

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)

Register to the context a PropertyChangeListener about some entity's property change. listener instance will be notified AFTER any change on the entity's property

Parameters:

listener - the listener instance to register

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)

Unregister the given PropertyChangeListener about some entity's property change from the context

Parameters:

listener - the listener instance to unregister

addTopiaSchemaListener

void addTopiaSchemaListener(TopiaSchemaListener listener)

Register to the context a TopiaSchemaListener about any schema modification. listener instance will be notified BEFORE and AFTER any change on the schema

Parameters:

listener - the listener instance to register

removeTopiaSchemaListener

void removeTopiaSchemaListener(TopiaSchemaListener listener)

Unregister the given TopiaSchemaListener about any schema modification from the context

Parameters:

listener - the listener instance to unregister

addTopiaContextListener

@Deprecated
void addTopiaContextListener(TopiaContextListener listener)

Deprecated. Use addTopiaSchemaListener

Register to the context a TopiaContextListener about any schema modification. listener instance will be notified BEFORE and AFTER any change on the schema

Parameters:

listener - the listener instance to register

removeTopiaContextListener

@Deprecated
void removeTopiaContextListener(TopiaContextListener listener)

Deprecated. Use removeTopiaSchemaListener

Unregister the given TopiaContextListener about any schema modification from the context

Parameters:

listener - the listener instance to unregister

findByTopiaId

<E extends TopiaEntity> E findByTopiaId(String topiaId)
                                    throws TopiaException

Retrieve TopiaEntity using its unique id.

Parameters:

topiaId - unique identifier of the entity in all the application.

Returns:

the entity found or null

Throws:

TopiaException - for errors on retrieving the entity

findAll

<E> List<E> findAll(String hql,
                  Object... propertyNamesAndValues)
                throws TopiaException

Allow to do some HQL query

WARNING : Depending on the registered service, this method may not support something else than queries on TopiaEntity

Parameters:

hql - the HQL query

propertyNamesAndValues - the query parameters. Arguments are key-value paired : [propertyName;value;propertyName;value;...]

Returns:

The result list

Throws:

TopiaException - for any error during querying

find

<E> List<E> find(String hql,
               int startIndex,
               int endIndex,
               Object... propertyNamesAndValues)
             throws TopiaException

Allow to do some JPA-QL query using the given bounds.

No lower bound : startIndex = 0.
No upper bound : endIndex = -1.

WARNING : Depending on the registered service, this method may not support something else than queries on TopiaEntity

Parameters:

hql - the HQL query

startIndex - first index of entity to return

endIndex - last index of entity to return

propertyNamesAndValues - the query parameters. Arguments are key-value paired : [propertyName;value;propertyName;value;...]

Returns:

The result list

Throws:

TopiaException - for any error during querying

findUnique

<E> E findUnique(String hql,
               Object... propertyNamesAndValues)
             throws TopiaException

Allow to do some HQL query and return an unique result. If nothing if found by the query, will return null. If more than one result is found, will throw an exception.

WARNING : Depending on the registered service, this method may not support something else than queries on TopiaEntity

Parameters:

hql - the HQL query

propertyNamesAndValues - the query parameters. Arguments are key-value paired : [propertyName;value;propertyName;value;...]

Returns:

The result instance or null

Throws:

TopiaException - for any error during querying or if the the query returns more than one result.

add

void add(TopiaEntity e)
         throws TopiaException

Add into this TopiaContext an entity created by another TopiaContext

Parameters:

e - the entity to add

Throws:

TopiaException - if any exception

evict

void evict(TopiaEntity e)
           throws TopiaException

Detaches the given entity from the session

Parameters:

e - the entity to detach

Throws:

TopiaException - if any exception

Since:

3.0

clearCache

void clearCache()
                throws TopiaException

Clear persistence implementation cache.

Throws:

TopiaException

Since:

2.6.13

execute

int execute(String hql,
          Object... propertyNamesAndValues)
            throws TopiaException

Execute HQL operation on data (Update, Delete).

Parameters:

hql - the HQL query

propertyNamesAndValues - the query parameters. Arguments are key-value paired : [propertyName;value;propertyName;value;...]

Returns:

The number of entities updated or deleted.

Throws:

TopiaException - if any exception

executeSQL

void executeSQL(String sqlScript)
                throws TopiaException

Execute a given sql code inside this transaction.

Parameters:

sqlScript - the sql script to execute

Throws:

TopiaException - if any problem occurred while executing the sql script.

createSchema

void createSchema()
                  throws TopiaException

Triggers database schema creation

Throws:

TopiaException - if any exception

showCreateSchema

void showCreateSchema()
                      throws TopiaException

Displays the SQL queries that would be used for a schema creation

Throws:

TopiaException - if any exception

updateSchema

void updateSchema()
                  throws TopiaException

Triggers database schema update

Throws:

TopiaException - if any exception

dropSchema

void dropSchema()
                throws TopiaException

Triggers database schema drop

Throws:

TopiaException - if any exception

Since:

3.0

serviceEnabled

<E extends TopiaService> boolean serviceEnabled(Class<E> interfaceService)

Return true if specific service is available.

Type Parameters:

E - type of service

Parameters:

interfaceService - fqn of the service

Returns:

the service

getService

<E extends TopiaService> E getService(Class<E> interfaceService)
                                  throws TopiaNotFoundException

Return the service. This service must be valid with public static final SERVICE_NAME property.

Type Parameters:

E - type of service

Parameters:

interfaceService - class of the service

Returns:

the service

Throws:

TopiaNotFoundException - if service can't be retrieved

replicate

void replicate(TopiaContext destinationContext,
             Object... entityAndCondition)
               throws TopiaException,
                      IllegalArgumentException

Makes a replication of some entities from this context to the given context without any entity modification.

Note: If the entityAndCondition parameter is empty, all the database will be replicated

Note 2: The simple replication may not be sufficent. You may want to replicate only a part of some entities : use the method replicateEntities(TopiaContext, List).

Parameters:

destinationContext - the destination context

entityAndCondition - [key;value;...] parameter which key is the entity class to replicate, and value the "where" condition to use when querying entities

Throws:

TopiaException - if any problem occurred during replicate

IllegalArgumentException - if one of the context is closed or if trying to replicate within the same database

replicateEntity

<T extends TopiaEntity> void replicateEntity(TopiaContext destinationContext,
                                           T entity)
                     throws TopiaException,
                            IllegalArgumentException

Replicate a given entity from this context to the given context.

Type Parameters:

T - type of the entity to replicate

Parameters:

destinationContext - the destination context

entity - the entity instance to replicate

Throws:

TopiaException - if any problem occurred during replicate

IllegalArgumentException - if one of the context is closed or if trying to replicate within the same database

replicateEntities

<T extends TopiaEntity> void replicateEntities(TopiaContext destinationContext,
                                             List<T> entities)
                       throws TopiaException,
                              IllegalArgumentException

Makes a replication of some entities from this context to the given context without any entity modification.

Type Parameters:

T - type of the entities to replicate

Parameters:

destinationContext - the destination context

entities - the list of entities instance to replicate

Throws:

TopiaException - if any problem occurred during replicate

IllegalArgumentException - if one of the context is closed or if trying to replicate within the same database

backup

@Deprecated
void backup(File file,
                     boolean compress)
            throws TopiaException

Deprecated. Only H2 compatible : remove it, or move to another class

Sauve la base de données dans un format natif a la base, la representation n'est pas portable d'une base a l'autre. Cette methode ne doit être utilisé que pour un stockage temporaire utile à une application.

Parameters:

file - le nom du fichier ou stocker les informations

compress - si vrai compress le fichier avec gzip

Throws:

TopiaException - if any exception

restore

@Deprecated
void restore(File file)
             throws TopiaException

Deprecated. Only H2 compatible : remove it, or move to another class

l'inverse de la methode backup(File,boolean).

Parameters:

file - le fichier ou prendre les informations, il peut-etre compressé avec gzip ou non.

Throws:

TopiaException - if any exception

clear

@Deprecated
void clear(boolean dropDatabase)
           throws TopiaException

Deprecated. Only H2 compatible : remove it, or move to another class

Supprime toutes les tables et autres elements de la database.

Parameters:

dropDatabase - si vrai alors supprime aussi la base de données si la base utilise des fichiers les fichiers seront supprimé (ex: h2) ou sera fait sur la base (postgresql)

Throws:

TopiaException - if any exception