[jboss-cvs] JBossCache/src/org/jboss/cache/pojo/notification/annotation ...
Jason Thomas Greene
jgreene at jboss.com
Mon Jul 2 21:44:37 EDT 2007
User: jgreene
Date: 07/07/02 21:44:37
Modified: src/org/jboss/cache/pojo/notification/annotation
ArrayModified.java Detached.java
PojoCacheListener.java
Log:
Update documentation
Revision Changes Path
1.2 +3 -3 JBossCache/src/org/jboss/cache/pojo/notification/annotation/ArrayModified.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: ArrayModified.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/pojo/notification/annotation/ArrayModified.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- ArrayModified.java 29 Jun 2007 04:34:01 -0000 1.1
+++ ArrayModified.java 3 Jul 2007 01:44:37 -0000 1.2
@@ -30,7 +30,7 @@
import org.jboss.cache.pojo.PojoCache;
import org.jboss.cache.pojo.notification.event.ArrayModifiedEvent;
-// $Id: ArrayModified.java,v 1.1 2007/06/29 04:34:01 jgreene Exp $
+// $Id: ArrayModified.java,v 1.2 2007/07/03 01:44:37 jgreene Exp $
/**
* <p>
@@ -47,10 +47,10 @@
* Example:
*
* <pre>
- * @PojoCacheListener
+ * @PojoCacheListener
* public class MyListener()
* {
- * @ArrayModified
+ * @ArrayModified
* public void handleArray(ArrayModifiedEvent event)
* {
* System.out.println("Object = " + even.getSource());
1.2 +4 -4 JBossCache/src/org/jboss/cache/pojo/notification/annotation/Detached.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: Detached.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/pojo/notification/annotation/Detached.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- Detached.java 29 Jun 2007 04:34:01 -0000 1.1
+++ Detached.java 3 Jul 2007 01:44:37 -0000 1.2
@@ -27,9 +27,9 @@
import java.lang.annotation.Target;
import org.jboss.cache.pojo.PojoCache;
-import org.jboss.cache.pojo.notification.event.AttachedEvent;
+import org.jboss.cache.pojo.notification.event.DetachedEvent;
-// $Id: Detached.java,v 1.1 2007/06/29 04:34:01 jgreene Exp $
+// $Id: Detached.java,v 1.2 2007/07/03 01:44:37 jgreene Exp $
/**
* <p>
@@ -46,10 +46,10 @@
* Example:
*
* <pre>
- * @PojoCacheListener
+ * @PojoCacheListener
* public class MyListener()
* {
- * @Detached
+ * @Detached
* public void handleDetached(DetachedEvent event)
* {
* System.out.println("Object = " + even.getSource());
1.2 +185 -22 JBossCache/src/org/jboss/cache/pojo/notification/annotation/PojoCacheListener.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: PojoCacheListener.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/pojo/notification/annotation/PojoCacheListener.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- PojoCacheListener.java 29 Jun 2007 04:34:01 -0000 1.1
+++ PojoCacheListener.java 3 Jul 2007 01:44:37 -0000 1.2
@@ -26,6 +26,7 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import org.jboss.cache.pojo.notification.NotificationContext;
import org.jboss.cache.pojo.notification.event.AttachedEvent;
import org.jboss.cache.pojo.notification.event.DetachedEvent;
import org.jboss.cache.pojo.notification.event.FieldModifiedEvent;
@@ -37,40 +38,202 @@
/**
* Indicates that a class should receive POJO notification events. The class may
- * have zero or more annotated notification methods. Each method may have any name,
- * but must have a method signature that contains the required event type (or super type).
+ * have zero or more annotated notification methods. Each method may have any
+ * name, but must have a method signature that contains the required event type
+ * (or super type).
*
* <p>
- * There can be multiple methods that are annotated to receive the same event, and a
- * method may receive multiple events by using a super type.
+ * There can be multiple methods that are annotated to receive the same event,
+ * and a method may receive multiple events by using a super type.
*
- * <b>Summary of notification annotations</b>
+ * <h4>Delivery Semantics</h4>
+ * <p>
+ * An event is delivered immediately after the
+ * respective operation, but before the underlying cache call returns. For this
+ * reason it is important to keep listener processing logic short-lived. If a
+ * long running task needs to be performed, it's recommended to use another
+ * thread.
+ *
+ * <h4>Transactional Semantics</h4>
+ * <p>
+ * Since the event is delivered during the actual cache call, the transactional
+ * outcome is not yet known. For this reason, <i>events are always delivered, even
+ * if the changes they represent are discarded by their containing transaction</i>.
+ * For applications that must only process events that represent changes in a
+ * completed transaction, {@link NotificationContext#getTransaction()} can be used,
+ * along with {@link TransactionCompletedEvent#isSuccessful()} to record events and
+ * later process them once the transaction has been successfully committed.
+ * Example 4 demonstrates this.
+ *
+ * <h4>Threading Semantics</h4>
+ * <p>
+ * A listener implementation must be capable of handling concurrent invocations. Local
+ * notifications reuse the calling thread; remote notifications reuse the network thread.
+ *
+ * <p>
+ * <b>Summary of Notification Annotations</b>
* <table border="1" cellpadding="1" cellspacing="1" summary="Summary of notification annotations">
* <tr>
* <th bgcolor="#CCCCFF" align="left">Annotation</th>
* <th bgcolor="#CCCCFF" align="left">Event</th>
* <th bgcolor="#CCCCFF" align="left">Description</th>
* </tr>
- * <tr><td valign="top">{@link Attached}</td><td valign="top">{@link AttachedEvent}</td>
- * <td valign="top">An object was attached.</td></tr>
- * <tr><td valign="top">{@link Detached}</td><td valign="top">{@link DetachedEvent}</td>
- * <td valign="top">An object was detached.</td></tr>
- * <tr><td valign="top">{@link FieldModified}</td><td valign="top">{@link FieldModifiedEvent}</td>
- * <td valign="top">An attached object's field was modified.</td></tr>
- * <tr><td valign="top">{@link ListModified}</td><td valign="top">{@link ListModifiedEvent}</td>
- * <td valign="top">An attached list was modified.</td></tr>
- * <tr><td valign="top">{@link SetModified}</td><td valign="top">{@link SetModifiedEvent}</td>
- * <td valign="top">An attached set was modified.</td></tr>
- * <tr><td valign="top">{@link MapModified}</td><td valign="top">{@link MapModifiedEvent}</td>
- * <td valign="top">An attached map was modified.</td></tr>
- * <tr><td valign="top">{@link TransactionRegistered}</td><td valign="top">{@link TransactionRegisteredEvent}</td>
- * <td valign="top">A transaction was registered.</td></tr>
- * <tr><td valign="top">{@link TransactionCompleted}</td><td valign="top">{@link TransactionCompletedEvent}</td>
- * <td valign="top">A transaction was completed.</td></tr>
+ * <tr>
+ * <td valign="top">{@link Attached}</td>
+ * <td valign="top">{@link AttachedEvent}</td>
+ * <td valign="top">An object was attached.</td>
+ * </tr>
+ * <tr>
+ * <td valign="top">{@link Detached}</td>
+ * <td valign="top">{@link DetachedEvent}</td>
+ * <td valign="top">An object was detached.</td>
+ * </tr>
+ * <tr>
+ * <td valign="top">{@link FieldModified}</td>
+ * <td valign="top">{@link FieldModifiedEvent}</td>
+ * <td valign="top">An attached object's field was modified.</td>
+ * </tr>
+ * <tr>
+ * <td valign="top">{@link ListModified}</td>
+ * <td valign="top">{@link ListModifiedEvent}</td>
+ * <td valign="top">An attached list was modified.</td>
+ * </tr>
+ * <tr>
+ * <td valign="top">{@link SetModified}</td>
+ * <td valign="top">{@link SetModifiedEvent}</td>
+ * <td valign="top">An attached set was modified.</td>
+ * </tr>
+ * <tr>
+ * <td valign="top">{@link MapModified}</td>
+ * <td valign="top">{@link MapModifiedEvent}</td>
+ * <td valign="top">An attached map was modified.</td>
+ * </tr>
+ * <tr>
+ * <td valign="top">{@link TransactionRegistered}</td>
+ * <td valign="top">{@link TransactionRegisteredEvent}</td>
+ * <td valign="top">A transaction was registered.</td>
+ * </tr>
+ * <tr>
+ * <td valign="top">{@link TransactionCompleted}</td>
+ * <td valign="top">{@link TransactionCompletedEvent}</td>
+ * <td valign="top">A transaction was completed.</td>
+ * </tr>
* </table>
*
+ * <h4>Example 1 - Method receiving a single event</h4>
+ * <pre>
+ * @PojoCacheListener
+ * public class SingleEventListener
+ * {
+ * @Attached
+ * public void handleAttached(AttachedEvent event)
+ * {
+ * System.out.println("Attached = " event.getSource());
+ * }
+ * }
+ * </pre>
+ *
+ * <h4>Example 2 - Method receiving multiple events</h4>
+ * <pre>
+ * @PojoCacheListener
+ * public class MultipleEventListener
+ * {
+ * @Attached
+ * @Detached
+ * public void handleAttachDetach(Event event)
+ * {
+ * if (event instanceof AttachedEvent)
+ * System.out.println("Attached = " + event.getSource());
+ * else if (event instanceof DetachedEvent)
+ * System.out.println("Detached = " + event.getSource());
+ * }
+ * }
+ * </pre>
+ *
+ * <h4>Example 3 - Multiple methods receiving the same event</h4>
+ * <pre>
+ * @PojoCacheListener
+ * public class SingleEventListener
+ * {
+ * @Attached
+ * public void handleAttached(AttachedEvent event)
+ * {
+ * System.out.println("Attached = " event.getSource());
+ * }
+ * @Attached
+ * @Detached
+ * @FieldModified
+ * @ListModified
+ * @MapModified
+ * @SetModified
+ * @TransactionRegistered
+ * @TransactionCompleted
+ * public void handleAll(Event event)
+ * {
+ * System.out.println(event);
+ * }
+ * }
+ * </pre>
+ *
+ * <p>
+ * <b>Example 4 - Processing only events with a committed transaction.</b>
+ *
+ * <pre>
+ * @PojoCacheListener
+ * public class TxGauranteedListener
+ * {
+ * private class TxEventQueue
+ * {
+ * private ConcurrentMap<Transaction, Queue<Event>> map = new ConcurrentHashMap<Transaction, Queue<Event>>();
+ *
+ * public void offer(Event event)
+ * {
+ * Queue<Event> queue = getQueue(event.getContext().getTransaction());
+ * queue.offer(event);
+ * }
+ *
+ * private Queue<Event> getQueue(Transaction transaction)
+ * {
+ * Queue<Event> queue = map.get(transaction);
+ * if (queue == null)
+ * {
+ * queue = new ConcurrentLinkedQueue<Event>();
+ * map.putIfAbsent(transaction, queue);
+ * }
+ *
+ * return queue;
+ * }
+ *
+ * public Queue<Event> takeAll(Transaction transaction)
+ * {
+ * return map.remove(transaction);
+ * }
+ * }
+ *
+ * private TxEventQueue events = new TxEventQueue();
+ *
+ * @Attached
+ * @Detached
+ * @FieldModified
+ * @ListModified
+ * @SetModified
+ * @MapModified
+ * public void handle(Event event)
+ * {
+ * events.offer(event);
+ * }
+ *
+ * @TransactionCompleted
+ * public void handleTx(TransactionCompletedEvent event)
+ * {
+ * Queue<Event> completed = events.takeAll(event.getContext().getTransaction());
+ * if (completed != null && event.isSuccessful())
+ * System.out.println("Comitted events = " + completed);
+ * }
+ * }
+ * </pre>
+ *
* @author Jason T. Greene
- * @version $Id: PojoCacheListener.java,v 1.1 2007/06/29 04:34:01 jgreene Exp $
* @since 2.0
*/
@Retention(RetentionPolicy.RUNTIME)
More information about the jboss-cvs-commits
mailing list