Author: athimel Date: 2012-05-23 18:25:48 +0200 (Wed, 23 May 2012) New Revision: 2519 Url: http://nuiton.org/repositories/revision/topia/2519 Log: Improve TopiaContext javadoc (still in progress) ; Rename TopiaContextListener by TopiaSchemaListener Added: trunk/topia-persistence/src/main/java/org/nuiton/topia/event/TopiaSchemaListener.java Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/TopiaContext.java trunk/topia-persistence/src/main/java/org/nuiton/topia/event/TopiaContextListener.java trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaContextImpl.java trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaFiresSupport.java trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaPredicates.java Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/TopiaContext.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/TopiaContext.java 2012-05-23 15:42:02 UTC (rev 2518) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/TopiaContext.java 2012-05-23 16:25:48 UTC (rev 2519) @@ -29,6 +29,7 @@ import org.nuiton.topia.event.TopiaEntitiesVetoable; import org.nuiton.topia.event.TopiaEntityListener; import org.nuiton.topia.event.TopiaEntityVetoable; +import org.nuiton.topia.event.TopiaSchemaListener; import org.nuiton.topia.event.TopiaTransactionListener; import org.nuiton.topia.event.TopiaTransactionVetoable; import org.nuiton.topia.framework.TopiaH2Util; @@ -53,52 +54,254 @@ */ public interface TopiaContext { - /* Adders */ + /** + * Returns a new context containing its own transaction. + * + * @return new context with transaction + * @throws TopiaException if any exception + */ + TopiaContext beginTransaction() 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 + */ + void commitTransaction() 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 + */ + void rollbackTransaction() throws TopiaException; + + /** + * Closes the context. All the children contexts will be closed in the same + * time. + * + * @throws TopiaException if any exception + */ + void closeContext() throws TopiaException; + + /** + * Tells if the context is closed + * + * @return {@code true} if the context is closed, {@code false} otherwise + */ + boolean isClosed(); + + + /* TopiaEntityListener */ + + /** + * Register to the context a TopiaEntityListener about any TopiaEntity. + * <code>listener</code> instance will be notified AFTER any operation on + * the entity. + * + * @param listener the listener instance to register + */ void addTopiaEntityListener(TopiaEntityListener listener); + /** + * Register to the context a TopiaEntityListener about the given entity + * class. <code>listener</code> instance will be notified AFTER any + * operation on the entity. + * + * @param entityClass the TopiaEntity's class to listen + * @param listener the listener instance to register + */ void addTopiaEntityListener( Class<? extends TopiaEntity> entityClass, TopiaEntityListener listener); + /** + * Unregister the given TopiaEntityListener about any TopiaEntity from the + * context + * + * @param listener the listener instance to unregister + */ + void removeTopiaEntityListener(TopiaEntityListener listener); + + /** + * Unregister the given TopiaEntityListener about he given entity class from + * the context + * + * @param entityClass the listened TopiaEntity's class + * @param listener the listener instance to unregister + */ + void removeTopiaEntityListener( + Class<? extends TopiaEntity> entityClass, + TopiaEntityListener listener); + + + /* TopiaEntityVetoable */ + + /** + * Register to the context a TopiaEntityVetoable about any TopiaEntity. + * <code>vetoable</code> instance will be notified BEFORE any operation on + * the entity. + * + * @param vetoable the vetoable instance to register + */ void addTopiaEntityVetoable(TopiaEntityVetoable vetoable); + /** + * Register to the context a TopiaEntityVetoable about the given entity + * class. <code>vetoable</code> instance will be notified BEFORE any + * operation on the entity. + * + * @param entityClass the TopiaEntity's class to listen + * @param vetoable the vetoable instance to register + */ void addTopiaEntityVetoable( Class<? extends TopiaEntity> entityClass, TopiaEntityVetoable vetoable); + /** + * Unregister the given TopiaEntityVetoable about any TopiaEntity from the + * context + * + * @param vetoable the vetoable instance to unregister + */ + void removeTopiaEntityVetoable(TopiaEntityVetoable vetoable); + + /** + * Unregister the given TopiaEntityVetoable about he given entity class from + * the context + * + * @param entityClass the listened TopiaEntity's class + * @param vetoable the vetoable instance to unregister + */ + void removeTopiaEntityVetoable( + Class<? extends TopiaEntity> entityClass, + TopiaEntityVetoable vetoable); + + + /* TopiaTransactionListener */ + + /** + * Register to the context a TopiaTransactionListener about the transaction. + * <code>listener</code> instance will be notified AFTER any operation on + * the transaction. + * + * @param listener the listener instance to register + */ void addTopiaTransactionListener(TopiaTransactionListener listener); + /** + * Unregister the given TopiaTransactionListener about the transaction from + * the context + * + * @param listener the listener instance to unregister + */ + void removeTopiaTransactionListener(TopiaTransactionListener listener); + + /* TopiaTransactionVetoable */ + + /** + * Register to the context a TopiaTransactionVetoable about the transaction. + * <code>vetoable</code> instance will be notified BEFORE any operation on + * the transaction. + * + * @param vetoable the vetoable instance to register + */ void addTopiaTransactionVetoable(TopiaTransactionVetoable vetoable); + /** + * Unregister the given TopiaTransactionVetoable about the transaction from + * the context + * + * @param vetoable the vetoable instance to unregister + */ + void removeTopiaTransactionVetoable(TopiaTransactionVetoable vetoable); + + + /* PropertyChangeListener */ + + /** + * Register to the context a PropertyChangeListener about some entity's + * property change. <code>listener</code> instance will be notified AFTER + * any change on the entity's property + * + * @param listener the listener instance to register + */ void addPropertyChangeListener(PropertyChangeListener listener); + /** + * Unregister the given PropertyChangeListener about some entity's + * property change from the context + * + * @param listener the listener instance to unregister + */ + void removePropertyChangeListener(PropertyChangeListener listener); + + + /* TopiaSchemaListener */ + + /** + * Register to the context a TopiaSchemaListener about any schema + * modification. <code>listener</code> instance will be notified BEFORE and + * AFTER any change on the schema + * + * @param listener the listener instance to register + */ + void addTopiaSchemaListener(TopiaSchemaListener listener); + + /** + * Unregister the given TopiaSchemaListener about any schema modification + * from the context + * + * @param listener the listener instance to unregister + */ + void removeTopiaSchemaListener(TopiaSchemaListener listener); + + + /* TopiaContextListener */ + + /** + * Register to the context a TopiaContextListener about any schema + * modification. <code>listener</code> instance will be notified BEFORE and + * AFTER any change on the schema + * + * @param listener the listener instance to register + * @deprecated Use addTopiaSchemaListener + */ + @Deprecated void addTopiaContextListener(TopiaContextListener listener); - void addTopiaEntitiesVetoable(TopiaEntitiesVetoable vetoable); + /** + * Unregister the given TopiaContextListener about any schema modification + * from the context + * + * @param listener the listener instance to unregister + * @deprecated Use removeTopiaSchemaListener + */ + @Deprecated + void removeTopiaContextListener(TopiaContextListener listener); - /* Removers */ - void removeTopiaEntityListener(TopiaEntityListener listener); - void removeTopiaEntityListener( - Class<? extends TopiaEntity> entityClass, - TopiaEntityListener listener); + - void removeTopiaEntityVetoable(TopiaEntityVetoable vetoable); - void removeTopiaEntityVetoable( - Class<? extends TopiaEntity> entityClass, - TopiaEntityVetoable vetoable); - void removeTopiaTransactionListener(TopiaTransactionListener listener); - void removeTopiaTransactionVetoable(TopiaTransactionVetoable vetoable); - void removePropertyChangeListener(PropertyChangeListener listener); - void removeTopiaContextListener(TopiaContextListener listener); + + + + + + /* TopiaEntitiesVetoable */ + + void addTopiaEntitiesVetoable(TopiaEntitiesVetoable vetoable); + void removeTopiaEntitiesVetoable(TopiaEntitiesVetoable vetoable); /** @@ -154,28 +357,6 @@ void updateSchema() throws TopiaException; /** - * Return a new context containing his own transaction. - * - * @return new context with transaction - * @throws TopiaException if any exception - */ - TopiaContext beginTransaction() throws TopiaException; - - /** - * applique les modifications apporté a ce context sur la base de données. - * - * @throws TopiaException if any exception - */ - void commitTransaction() throws TopiaException; - - /** - * annule les modifications apporté a ce context. - * - * @throws TopiaException if any exception - */ - void rollbackTransaction() throws TopiaException; - - /** * Retrieve {@link TopiaEntity} using its unique {@code id}. * * @param topiaId unique identifier of the entity in all the application. @@ -342,21 +523,6 @@ throws TopiaException, IllegalArgumentException; /** - * Closes the context. All the child contexts will be closed in the same - * time. - * - * @throws TopiaException if any exception - */ - void closeContext() throws TopiaException; - - /** - * Indique si le contexte a ete fermé. - * - * @return {@code true} si le context est fermé, {@code false} autrement - */ - boolean isClosed(); - - /** * Execute a given sql code inside this transaction. * * @param sqlScript the sql script to execute Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/event/TopiaContextListener.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/event/TopiaContextListener.java 2012-05-23 15:42:02 UTC (rev 2518) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/event/TopiaContextListener.java 2012-05-23 16:25:48 UTC (rev 2519) @@ -25,62 +25,46 @@ package org.nuiton.topia.event; -import java.util.EventListener; - /** - * Listener for TopiaContext actions. - * <p/> - * Listener are notified for action such as : - * <ul> - * <li>createSchema</li> - * <li>updateSchema</li> - * <li>...</li> - * </ul> - * - * @author chatellier <chatellier@codelutin.com> - * @version $Id$ + * @deprecated Use {@link TopiaSchemaListener} */ -public interface TopiaContextListener extends EventListener { +@Deprecated +public interface TopiaContextListener extends TopiaSchemaListener { /** - * Called before createSchema call - * - * @param event evet + * @deprecated Use {@link TopiaSchemaListener#preCreateSchema(TopiaContextEvent)} */ + @Deprecated void preCreateSchema(TopiaContextEvent event); /** - * Called after createSchema call - * - * @param event event + * @deprecated Use {@link TopiaSchemaListener#postCreateSchema(TopiaContextEvent)} */ + @Deprecated void postCreateSchema(TopiaContextEvent event); /** - * Called before updateSchema call - * - * @param event event + * @deprecated Use {@link TopiaSchemaListener#preUpdateSchema(TopiaContextEvent)} */ + @Deprecated void preUpdateSchema(TopiaContextEvent event); /** - * Called after updateSchema call - * - * @param event event + * @deprecated Use {@link TopiaSchemaListener#postUpdateSchema(TopiaContextEvent)} */ + @Deprecated void postUpdateSchema(TopiaContextEvent event); /** - * Called after updateSchema call - * - * @param event event + * @deprecated Use {@link TopiaSchemaListener#preRestoreSchema(TopiaContextEvent)} */ + @Deprecated void preRestoreSchema(TopiaContextEvent event); /** - * Called after updateSchema call - * - * @param event event + * @deprecated Use {@link TopiaSchemaListener#postRestoreSchema(TopiaContextEvent)} */ + @Deprecated void postRestoreSchema(TopiaContextEvent event); + } Added: trunk/topia-persistence/src/main/java/org/nuiton/topia/event/TopiaSchemaListener.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/event/TopiaSchemaListener.java (rev 0) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/event/TopiaSchemaListener.java 2012-05-23 16:25:48 UTC (rev 2519) @@ -0,0 +1,62 @@ +package org.nuiton.topia.event; + +import java.util.EventListener; + +/** + * Listener for TopiaContext actions. + * <p/> + * Listener are notified for action such as : + * <ul> + * <li>createSchema</li> + * <li>updateSchema</li> + * <li>...</li> + * </ul> + * + * @author Arnaud Thimel <thimel@codelutin.com> + * @version $Id: TopiaContextListener.java 2142 2010-11-18 16:17:42Z tchemit $ + */ +public interface TopiaSchemaListener extends EventListener { + + /** + * Called before createSchema call + * + * @param event event + */ + void preCreateSchema(TopiaContextEvent event); + + /** + * Called after createSchema call + * + * @param event event + */ + void postCreateSchema(TopiaContextEvent event); + + /** + * Called before updateSchema call + * + * @param event event + */ + void preUpdateSchema(TopiaContextEvent event); + + /** + * Called after updateSchema call + * + * @param event event + */ + void postUpdateSchema(TopiaContextEvent event); + + /** + * Called after updateSchema call + * + * @param event event + */ + void preRestoreSchema(TopiaContextEvent event); + + /** + * Called after updateSchema call + * + * @param event event + */ + void postRestoreSchema(TopiaContextEvent event); + +} Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaContextImpl.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaContextImpl.java 2012-05-23 15:42:02 UTC (rev 2518) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaContextImpl.java 2012-05-23 16:25:48 UTC (rev 2519) @@ -25,7 +25,6 @@ package org.nuiton.topia.framework; -import com.google.common.base.Predicate; import com.google.common.base.Splitter; import com.google.common.collect.ImmutableMap; import com.google.common.collect.ImmutableSet; @@ -49,6 +48,7 @@ import org.nuiton.topia.event.TopiaEntitiesVetoable; import org.nuiton.topia.event.TopiaEntityListener; import org.nuiton.topia.event.TopiaEntityVetoable; +import org.nuiton.topia.event.TopiaSchemaListener; import org.nuiton.topia.event.TopiaTransactionListener; import org.nuiton.topia.event.TopiaTransactionVetoable; import org.nuiton.topia.persistence.TopiaDAO; @@ -117,17 +117,6 @@ private static final Log log = LogFactory.getLog(TopiaContextImpl.class); /** - * Predicate to know if the given context is the root context - */ - protected final static Predicate<TopiaContextImplementor> IS_ROOT_CONTEXT = - new Predicate<TopiaContextImplementor>() { - @Override - public boolean apply(TopiaContextImplementor context) { - return context.getParentContext() == null; - } - }; - - /** * This context's parent. Root contexts does not have a parent context */ protected TopiaContextImplementor parentContext; @@ -489,7 +478,7 @@ "getDAO", "entityClass"); throw new IllegalArgumentException(message); } - if (IS_ROOT_CONTEXT.apply(this)) { + if (TopiaPredicates.IS_ROOT_CONTEXT.apply(this)) { throw new TopiaException( "You are on root context, you MUST open a transaction to perform any database access."); } @@ -600,7 +589,7 @@ @Override public void commitTransaction() throws TopiaException { - if (IS_ROOT_CONTEXT.apply(this)) { + if (TopiaPredicates.IS_ROOT_CONTEXT.apply(this)) { String message = String.format("Operation '%s' is not permitted on root context", "commitTransaction"); throw new TopiaException(message); } @@ -628,7 +617,7 @@ @Override public void rollbackTransaction() throws TopiaException { - if (IS_ROOT_CONTEXT.apply(this)) { + if (TopiaPredicates.IS_ROOT_CONTEXT.apply(this)) { String message = String.format("Operation '%s' is not permitted on root context", "rollbackTransaction"); throw new TopiaException(message); } @@ -670,7 +659,7 @@ } } - if (IS_ROOT_CONTEXT.apply(this)) { + if (TopiaPredicates.IS_ROOT_CONTEXT.apply(this)) { if (entityManagerFactory != null) { entityManagerFactory.close(); closed = true; @@ -761,10 +750,15 @@ } @Override - public void addTopiaContextListener(TopiaContextListener listener) { + public void addTopiaSchemaListener(TopiaSchemaListener listener) { getFiresSupport().addTopiaContextListener(listener); } + @Override + public void addTopiaContextListener(TopiaContextListener listener) { + addTopiaSchemaListener(listener); + } + /* Listeners removers */ @Override @@ -812,6 +806,11 @@ @Override public void removeTopiaContextListener(TopiaContextListener listener) { + removeTopiaSchemaListener(listener); + } + + @Override + public void removeTopiaSchemaListener(TopiaSchemaListener listener) { getFiresSupport().removeTopiaContextListener(listener); } Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaFiresSupport.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaFiresSupport.java 2012-05-23 15:42:02 UTC (rev 2518) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaFiresSupport.java 2012-05-23 16:25:48 UTC (rev 2519) @@ -28,32 +28,16 @@ import org.apache.commons.collections.map.IdentityMap; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; -//import org.hibernate.event.PostDeleteEvent; -//import org.hibernate.event.PostDeleteEventListener; -//import org.hibernate.event.PostInsertEvent; -//import org.hibernate.event.PostInsertEventListener; -//import org.hibernate.event.PostLoadEvent; -//import org.hibernate.event.PostLoadEventListener; -//import org.hibernate.event.PostUpdateEvent; -//import org.hibernate.event.PostUpdateEventListener; -//import org.hibernate.event.PreDeleteEvent; -//import org.hibernate.event.PreDeleteEventListener; -//import org.hibernate.event.PreInsertEvent; -//import org.hibernate.event.PreInsertEventListener; -//import org.hibernate.event.PreLoadEvent; -//import org.hibernate.event.PreLoadEventListener; -//import org.hibernate.event.PreUpdateEvent; -//import org.hibernate.event.PreUpdateEventListener; import org.nuiton.topia.TopiaContext; import org.nuiton.topia.TopiaException; import org.nuiton.topia.TopiaVetoException; import org.nuiton.topia.event.TopiaContextEvent; -import org.nuiton.topia.event.TopiaContextListener; import org.nuiton.topia.event.TopiaEntitiesEvent; import org.nuiton.topia.event.TopiaEntitiesVetoable; import org.nuiton.topia.event.TopiaEntityEvent; import org.nuiton.topia.event.TopiaEntityListener; import org.nuiton.topia.event.TopiaEntityVetoable; +import org.nuiton.topia.event.TopiaSchemaListener; import org.nuiton.topia.event.TopiaTransactionEvent; import org.nuiton.topia.event.TopiaTransactionListener; import org.nuiton.topia.event.TopiaTransactionVetoable; @@ -126,8 +110,8 @@ /* Pour les actions du topia context */ - protected ListenerSet<TopiaContextListener> topiaContextListeners = - new ListenerSet<TopiaContextListener>(); + protected ListenerSet<TopiaSchemaListener> topiaSchemaListeners = + new ListenerSet<TopiaSchemaListener>(); /** * used to register objects loaded during transaction. @@ -769,7 +753,7 @@ log.debug("firePreCreateSchema"); } TopiaContextEvent event = new TopiaContextEvent(context); - for (TopiaContextListener topiaContextListener : topiaContextListeners) { + for (TopiaSchemaListener topiaContextListener : topiaSchemaListeners) { try { topiaContextListener.preCreateSchema(event); } catch (Exception eee) { @@ -788,9 +772,9 @@ log.debug("firePostCreateSchema"); } TopiaContextEvent event = new TopiaContextEvent(context); - for (TopiaContextListener topiaContextListener : topiaContextListeners) { + for (TopiaSchemaListener topiaSchemaListener : topiaSchemaListeners) { try { - topiaContextListener.postCreateSchema(event); + topiaSchemaListener.postCreateSchema(event); } catch (Exception eee) { throw new TopiaVetoException(eee); } @@ -807,9 +791,9 @@ log.debug("firePostCreateSchema"); } TopiaContextEvent event = new TopiaContextEvent(context); - for (TopiaContextListener topiaContextListener : topiaContextListeners) { + for (TopiaSchemaListener topiaSchemaListener : topiaSchemaListeners) { try { - topiaContextListener.preUpdateSchema(event); + topiaSchemaListener.preUpdateSchema(event); } catch (Exception eee) { throw new TopiaVetoException(eee); } @@ -826,9 +810,9 @@ log.debug("firePostCreateSchema"); } TopiaContextEvent event = new TopiaContextEvent(context); - for (TopiaContextListener topiaContextListener : topiaContextListeners) { + for (TopiaSchemaListener topiaSchemaListener : topiaSchemaListeners) { try { - topiaContextListener.postUpdateSchema(event); + topiaSchemaListener.postUpdateSchema(event); } catch (Exception eee) { throw new TopiaVetoException(eee); } @@ -845,9 +829,9 @@ log.debug("firePreRestoreSchema"); } TopiaContextEvent event = new TopiaContextEvent(context); - for (TopiaContextListener topiaContextListener : topiaContextListeners) { + for (TopiaSchemaListener topiaSchemaListener : topiaSchemaListeners) { try { - topiaContextListener.preRestoreSchema(event); + topiaSchemaListener.preRestoreSchema(event); } catch (Exception eee) { throw new TopiaVetoException(eee); } @@ -864,9 +848,9 @@ log.debug("firePostRestoreSchema"); } TopiaContextEvent event = new TopiaContextEvent(context); - for (TopiaContextListener topiaContextListener : topiaContextListeners) { + for (TopiaSchemaListener topiaSchemaListener : topiaSchemaListeners) { try { - topiaContextListener.postRestoreSchema(event); + topiaSchemaListener.postRestoreSchema(event); } catch (Exception eee) { throw new TopiaVetoException(eee); } @@ -918,8 +902,8 @@ return transactionVetoables; } - public ListenerSet<TopiaContextListener> getTopiaContextListeners() { - return topiaContextListeners; + public ListenerSet<TopiaSchemaListener> getTopiaSchemaListeners() { + return topiaSchemaListeners; } public ListenerSet<TopiaEntitiesVetoable> getTopiaEntitiesVetoable() { @@ -975,11 +959,11 @@ propertyChangeListeners.add(listener); } - public void addTopiaContextListener(TopiaContextListener listener) { + public void addTopiaContextListener(TopiaSchemaListener listener) { if (listener == null) { throw new NullPointerException("Listener can not be null."); } - topiaContextListeners.add(listener); + topiaSchemaListeners.add(listener); } public void addTopiaEntitiesVetoable(TopiaEntitiesVetoable vetoable) { @@ -1038,11 +1022,11 @@ propertyChangeListeners.remove(listener); } - public void removeTopiaContextListener(TopiaContextListener listener) { + public void removeTopiaContextListener(TopiaSchemaListener listener) { if (listener == null) { throw new NullPointerException("Listener can not be null."); } - topiaContextListeners.remove(listener); + topiaSchemaListeners.remove(listener); } public void removeTopiaEntitiesVetoable(TopiaEntitiesVetoable vetoable) { Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaPredicates.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaPredicates.java 2012-05-23 15:42:02 UTC (rev 2518) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaPredicates.java 2012-05-23 16:25:48 UTC (rev 2519) @@ -19,4 +19,17 @@ } }; } + + + /** + * Predicate to know if the given context is the root context + */ + public final static Predicate<TopiaContextImplementor> IS_ROOT_CONTEXT = + new Predicate<TopiaContextImplementor>() { + @Override + public boolean apply(TopiaContextImplementor context) { + return context.getParentContext() == null; + } + }; + }