[jbosscache-commits] JBoss Cache SVN: r6494 - in core/trunk/src/main/java/org/jboss/cache: notifications/annotation and 1 other directory.

[jbosscache-commits at lists.jboss.org]

Author: manik.surtani at jboss.com
Date: 2008-08-04 09:34:30 -0400 (Mon, 04 Aug 2008)
New Revision: 6494

Modified:
   core/trunk/src/main/java/org/jboss/cache/config/Configuration.java
   core/trunk/src/main/java/org/jboss/cache/notifications/annotation/CacheListener.java
Log:
JBCACHE-1108 Javadocs

Modified: core/trunk/src/main/java/org/jboss/cache/config/Configuration.java
===================================================================
--- core/trunk/src/main/java/org/jboss/cache/config/Configuration.java	2008-08-04 13:27:06 UTC (rev 6493)
+++ core/trunk/src/main/java/org/jboss/cache/config/Configuration.java	2008-08-04 13:34:30 UTC (rev 6494)
@@ -412,6 +412,14 @@
       this.syncRollbackPhase = syncRollbackPhase;
    }
 
+   /**
+    * Sets the size of the asynchronous listener notification thread pool size.  Defaults to 1, and if set to below 1,
+    * all async listeners (specified with {@link org.jboss.cache.notifications.annotation.CacheListener#sync()} are notified
+    * synchronously.
+    *
+    * @param listenerAsyncPoolSize number of threads in pool
+    * @since 3.0
+    */
    public void setListenerAsyncPoolSize(int listenerAsyncPoolSize)
    {
       testImmutability("asyncListenerPoolSize");
@@ -721,7 +729,12 @@
    }
 
    /**
-    * @return the size of the async listener thread pool.  If this is < 1, all async listeners should be treated as sync listeners.
+    * Gets the size of the asynchronous listener notification thread pool size.  Defaults to 1, and if set to below 1,
+    * all async listeners (specified with {@link org.jboss.cache.notifications.annotation.CacheListener#sync()} are notified
+    * synchronously.
+    *
+    * @return thread pool size
+    * @since 3.0
     */
    public int getListenerAsyncPoolSize()
    {

Modified: core/trunk/src/main/java/org/jboss/cache/notifications/annotation/CacheListener.java
===================================================================
--- core/trunk/src/main/java/org/jboss/cache/notifications/annotation/CacheListener.java	2008-08-04 13:27:06 UTC (rev 6493)
+++ core/trunk/src/main/java/org/jboss/cache/notifications/annotation/CacheListener.java	2008-08-04 13:34:30 UTC (rev 6494)
@@ -58,8 +58,11 @@
  * as locks may be held longer than necessary or intended to and may cause deadlocking in certain situations.  See above paragraph
  * on long-running tasks that should be run in a separate thread.
  * </p>
+ * <b>Note</b>: Since 3.0, a new parameter, <tt>sync</tt>, has been introduced on this annotation.  This defaults to <tt>true</tt>
+ * which provides the above semantics.  Alternatively, if you set <tt>sync</tt> to <tt>false</tt>, then invocations are made in a
+ * <i>separate</i> thread, which will not cause any blocking on the caller or network thread.  The separate thread is taken
+ * from a pool, which can be configured using {@link org.jboss.cache.config.Configuration#setListenerAsyncPoolSize(int)}.
  * <p/>
- * <p/>
  * <b>Summary of Notification Annotations</b>
  * <table border="1" cellpadding="1" cellspacing="1" summary="Summary of notification annotations">
  * <tr>
@@ -298,5 +301,12 @@
 @Target(ElementType.TYPE)
 public @interface CacheListener
 {
+   /**
+    * Specifies whether callbacks on any class annotated with this annotation happens synchronously (in the caller's thread)
+    * or asynchronously (using a separate thread).  Defaults to <tt>true</tt>.
+    *
+    * @return true if the expectation is that callbacks are called using the caller's thread; false if they are to be made in a separate thread.
+    * @since 3.0
+    */
    boolean sync() default true;
 }