[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