[jboss-cvs] JBossAS SVN: r110429 - projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor.

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Sat Jan 22 16:32:10 EST 2011


Author: david.lloyd at jboss.com
Date: 2011-01-22 16:32:09 -0500 (Sat, 22 Jan 2011)
New Revision: 110429

Modified:
   projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/AroundInvoke.java
   projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/AroundTimeout.java
   projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/ExcludeClassInterceptors.java
   projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/ExcludeDefaultInterceptors.java
   projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/Interceptor.java
   projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/InterceptorBinding.java
   projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/Interceptors.java
   projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/InvocationContext.java
Log:
Code cleanup, javadoc

Modified: projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/AroundInvoke.java
===================================================================
--- projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/AroundInvoke.java	2011-01-21 22:44:26 UTC (rev 110428)
+++ projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/AroundInvoke.java	2011-01-22 21:32:09 UTC (rev 110429)
@@ -18,20 +18,23 @@
 
 package javax.interceptor;
 
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import static java.lang.annotation.ElementType.*;
-import static java.lang.annotation.RetentionPolicy.*;
-
 /**
- * Defines an interceptor method. The method must have the signature:
- * public Object <METHOD>(InvocationContext) throws Exception
- * 
- * @author <a href="mailto:kabir.khan at jboss.org">Kabir Khan</a>
- * @version $Revision$
+ * Defines a method which intercepts invocation of another method.  The annotated method must not be final, must not be
+ * static, and must accept exactly one parameter of type {@link InvocationContext}, returning an {@link Object}.
+ * <p/>
+ * The annotation may be applied a method of the target class (or a superclass thereof), or to a method of any
+ * interceptor class; however only one method of the class may be so annotated.
+ * <p/>
+ * An {@code @AroundInvoke} interceptor method can invoke any component or resource that the method it is intercepting
+ * can invoke.  In particular, the same transaction and security contexts apply to the interceptor method as to the
+ * intercepted method.
  */
-
- at Target({METHOD}) @Retention(RUNTIME)
-public @interface AroundInvoke {
-}
+ at Target(METHOD)
+ at Retention(RUNTIME)
+public @interface AroundInvoke {}

Modified: projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/AroundTimeout.java
===================================================================
--- projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/AroundTimeout.java	2011-01-21 22:44:26 UTC (rev 110428)
+++ projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/AroundTimeout.java	2011-01-22 21:32:09 UTC (rev 110429)
@@ -25,16 +25,16 @@
 import java.lang.annotation.Target;
 
 /**
- * Defines an interceptor for a timeout method. The method must have the signature:
- * public Object <METHOD>(InvocationContext) throws Exception
- * 
- * @author <a href="mailto:cdewolf at redhat.com">Carlo de Wolf</a>
- * @version $Revision$
- * @since 3.1
+ * Defines a method which intercepts invocation of a timeout method.  The annotated method must not be final, must not
+ * be static, and must accept exactly one parameter of type {@link InvocationContext}, returning an {@link Object}.
+ * <p/>
+ * The annotation may be applied a method of the target class (or a superclass thereof), or to a method of any
+ * interceptor class; however only one method of the class may be so annotated.
+ * <p/>
+ * An {@code @AroundTimeout} interceptor method can invoke any component or resource that the timeout method it is
+ * intercepting can invoke.  In particular, the same transaction and security contexts apply to the interceptor method
+ * as to the timeout method.
  */
-
- at Target(value=METHOD)
- at Retention(value=RUNTIME)
-public @interface AroundTimeout {
-
-}
+ at Target(METHOD)
+ at Retention(RUNTIME)
+public @interface AroundTimeout {}

Modified: projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/ExcludeClassInterceptors.java
===================================================================
--- projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/ExcludeClassInterceptors.java	2011-01-21 22:44:26 UTC (rev 110428)
+++ projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/ExcludeClassInterceptors.java	2011-01-22 21:32:09 UTC (rev 110429)
@@ -25,12 +25,9 @@
 import java.lang.annotation.Target;
 
 /**
- * 
- * @author <a href="kabir.khan at jboss.com">Kabir Khan</a>
- * @version $Revision$
+ * Exclude the invocation of class-level interceptors for a method.  This annotation applies to a method
+ * that would otherwise be subject to interception.
  */
-
- at Target({METHOD}) @Retention(RUNTIME)
-public @interface ExcludeClassInterceptors {
-
-}
+ at Target(METHOD)
+ at Retention(RUNTIME)
+public @interface ExcludeClassInterceptors {}

Modified: projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/ExcludeDefaultInterceptors.java
===================================================================
--- projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/ExcludeDefaultInterceptors.java	2011-01-21 22:44:26 UTC (rev 110428)
+++ projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/ExcludeDefaultInterceptors.java	2011-01-22 21:32:09 UTC (rev 110429)
@@ -26,12 +26,9 @@
 import java.lang.annotation.Target;
 
 /**
- * 
- * @author <a href="kabir.khan at jboss.com">Kabir Khan</a>
- * @version $Revision$
+ * Exclude the invocation of default interceptors for a method.  This annotation applies to a method
+ * that would otherwise be subject to interception.
  */
-
- at Target({TYPE, METHOD}) @Retention(RUNTIME)
-public @interface ExcludeDefaultInterceptors {
-
-}
+ at Target({ TYPE, METHOD })
+ at Retention(RUNTIME)
+public @interface ExcludeDefaultInterceptors {}

Modified: projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/Interceptor.java
===================================================================
--- projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/Interceptor.java	2011-01-21 22:44:26 UTC (rev 110428)
+++ projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/Interceptor.java	2011-01-22 21:32:09 UTC (rev 110429)
@@ -26,13 +26,11 @@
 import java.lang.annotation.Target;
 
 /**
- * Specifies that a class is an interceptor.
- *
- * @author Gavin King
- *
+ * Explicitly specify that a class is an interceptor class.  Note that in many cases, it is possible for the container
+ * to implicitly determine that a class is an interceptor class without the presence of this annotation; in particular,
+ * a deployment descriptor or {@link Interceptors @Interceptors} annotation can also identify an interceptor class.
  */
-
- at Retention(RUNTIME)
 @Target(TYPE)
+ at Retention(RUNTIME)
 @Documented
 public @interface Interceptor {}

Modified: projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/InterceptorBinding.java
===================================================================
--- projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/InterceptorBinding.java	2011-01-21 22:44:26 UTC (rev 110428)
+++ projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/InterceptorBinding.java	2011-01-22 21:32:09 UTC (rev 110429)
@@ -18,6 +18,8 @@
 
 package javax.interceptor;
 
+import java.lang.annotation.ElementType;
+
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
@@ -26,12 +28,17 @@
 import java.lang.annotation.Target;
 
 /**
- * Specifies that an annotation type is an interceptor binding.
- *
- * @author Gavin King
- * @author Pete Muir
+ * Specifies that an annotation type is an interceptor binding type.  Interceptor bindings are used to specify
+ * the binding of an interceptor class to target classes and methods.
+ * <p>
+ * The annotation type that is marked as a binding must be applied to an interceptor class (marked with the
+ * {@link Interceptor @Interceptor} annotation to associate that annotation with an interceptor.  The annotation
+ * may then be applied instead of, or in addition to, the {@link Interceptors @Interceptors} annotation to specify
+ * what interceptors are attached to the class or method.
+ * <p>
+ * The associated annotation type must be associated only with {@link ElementType#TYPE TYPE}s and/or
+ * {@link ElementType#METHOD METHOD}s.
  */
-
 @Target(ANNOTATION_TYPE)
 @Retention(RUNTIME)
 @Documented

Modified: projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/Interceptors.java
===================================================================
--- projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/Interceptors.java	2011-01-21 22:44:26 UTC (rev 110428)
+++ projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/Interceptors.java	2011-01-22 21:32:09 UTC (rev 110429)
@@ -20,20 +20,22 @@
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
+
 import static java.lang.annotation.ElementType.*;
 import static java.lang.annotation.RetentionPolicy.*;
 
 /**
- * An interceptor class is denoted using the Interceptor annotation on the bean
- * class with which it is associated. In the case of multiple interceptor
- * classes, the Interceptors annotation is used.
- * 
- * @author <a href="mailto:kabir.khan at jboss.org">Kabir Khan</a>
- * @version $Revision$
+ * Declares the list of interceptors (by interceptor class) which apply to the annotated class or method.
  */
+ at Target({ TYPE, METHOD })
+ at Retention(RUNTIME)
+public @interface Interceptors {
 
- at Target({TYPE, METHOD}) @Retention(RUNTIME)
-   public @interface Interceptors
-{
-   Class[] value();
+    /**
+     * The actual interceptor classes to apply to the annotated element.
+     *
+     * @return the interceptor classes
+     */
+    @SuppressWarnings("unchecked") // By spec, this returns a raw type.  Don't mess with the spec.
+    Class[] value();
 }

Modified: projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/InvocationContext.java
===================================================================
--- projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/InvocationContext.java	2011-01-21 22:44:26 UTC (rev 110428)
+++ projects/specs/trunk/jboss-interceptors-api_1.1_spec/src/main/java/javax/interceptor/InvocationContext.java	2011-01-22 21:32:09 UTC (rev 110429)
@@ -19,35 +19,82 @@
 package javax.interceptor;
 
 import java.lang.reflect.Method;
+import java.util.Map;
 
 /**
- * The InvocationContext object provides the metadata that is required for
- * AroundInvoke interceptor methods.
- * 
- * @author <a href="mailto:kabir.khan at jboss.org">Kabir Khan</a>
- * @version $Revision$
+ * Contextual information about a method invocation, along with methods to alter the invocation process
+ * in various ways.
  */
-public interface InvocationContext
-{
-   public Object getTarget();
+public interface InvocationContext {
 
-   public Method getMethod();
+    /**
+     * Get the target instance for this invocation.
+     *
+     * @return the target instance
+     */
+    Object getTarget();
 
-   public Object[] getParameters();
+    /**
+     * Get the invoked method for this invocation.  If the invoked method is an {@link AroundInvoke @AroundInvoke} or
+     * {@link AroundTimeout @AroundTimeout} interceptor method, the method of the target class is returned.  For
+     * lifecycle callback interceptors (such as {@link javax.annotation.PostConstruct @PostConstruct} or {@link
+     * javax.annotation.PreDestroy @PreDestroy}), {@code null} is returned.
+     *
+     * @return the invoked method, or {@code null} if none applies to the current invocation context
+     */
+    Method getMethod();
 
-   public void setParameters(Object[] params);
+    /**
+     * Get the parameters of the method invocation (for method interceptors).
+     *
+     * @return the invoked method parameters
+     *
+     * @throws IllegalStateException if the current invocation context refers to a lifecycle callback invocation
+     */
+    Object[] getParameters() throws IllegalStateException;
 
-   /**
-    * Returns the context data associated with this invocation or lifecycle callback. If there is no context data, an empty Map object will be returned.
-    */
-   public java.util.Map<String, Object> getContextData();
+    /**
+     * Replace the parameters of the method invocation.
+     *
+     * @param params the new parameter values to use for the current invocation
+     *
+     * @throws IllegalStateException if the current invocation context refers to a lifecycle callback invocation
+     * @throws IllegalArgumentException if the types or quantity of the method parameters does not match the method
+     * declaration
+     */
+    void setParameters(Object[] params) throws IllegalStateException, IllegalArgumentException;
 
-   /**
-    * Returns the timer associated with an @AroundTimeout method.
-    * 
-    * @since 3.1
-    */
-   Object getTimer();
-   
-   public Object proceed() throws Exception;
+    /**
+     * Returns the context data associated with this invocation or lifecycle callback.
+     * <p/>
+     * If the current context is an invocation on a web service endpoint, the map returned will be the JAX-WS {@code
+     * MessageContext}.  If there is no context data, an empty {@code Map} object will be returned.  Normally,
+     * information stored in this map is available to subsequent interceptors in an interceptor chain, so this mechanism
+     * may be used to pass information from one interceptor to the next.
+     *
+     * @return the context map
+     */
+    Map<String, Object> getContextData();
+
+    /**
+     * Get the timer associated with an {@link AroundTimeout @AroundTimeout} interceptor method.  When intercepting
+     * an EJB component timeout, the returned type is {@link javax.ejb.Timer}.
+     *
+     * @return the timer object, or {@code null} if the invocation did not apply to a timeout method.
+     */
+    Object getTimer();
+
+    /**
+     * Proceed with the next stage of invocation processing.  Calling this method may cause another interceptor to be
+     * invoked, or it may cause the final target object to be invoked.  The return value of this method is the result
+     * of the subsequent invocation processing, or of the invocation itself.  Normally an interceptor will return this
+     * value to its caller; however, it is also possible to return a different value.
+     * <p>
+     * If the intercepted method's return type is {@code void}, or if this is a lifecycle method interceptor, then
+     * {@code null} is returned from this method, and should be returned by the interceptor as well.
+     *
+     * @return the result of subsequent interceptor method processing
+     * @throws Exception if an exception is thrown by subsequent processing
+     */
+    Object proceed() throws Exception;
 }



More information about the jboss-cvs-commits mailing list