Author: manik.surtani(a)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; }