| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <!-- |
| |
| DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
| |
| Copyright (c) 2009-2010 Oracle and/or its affiliates. All rights reserved. |
| |
| The contents of this file are subject to the terms of either the GNU |
| General Public License Version 2 only ("GPL") or the Common Development |
| and Distribution License("CDDL") (collectively, the "License"). You |
| may not use this file except in compliance with the License. You can |
| obtain a copy of the License at |
| https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html |
| or packager/legal/LICENSE.txt. See the License for the specific |
| language governing permissions and limitations under the License. |
| |
| When distributing the software, include this License Header Notice in each |
| file and include the License file at packager/legal/LICENSE.txt. |
| |
| GPL Classpath Exception: |
| Oracle designates this particular file as subject to the "Classpath" |
| exception as provided by Oracle in the GPL Version 2 section of the License |
| file that accompanied this code. |
| |
| Modifications: |
| If applicable, add the following below the License Header, with the fields |
| enclosed by brackets [] replaced by your own identifying information: |
| "Portions Copyright [year] [name of copyright owner]" |
| |
| Contributor(s): |
| If you wish your version of this file to be governed by only the CDDL or |
| only the GPL Version 2, indicate your decision by adding "[Contributor] |
| elects to include this software in this distribution under the [CDDL or GPL |
| Version 2] license." If you don't indicate a single choice of license, a |
| recipient has the option to distribute your version of this file under |
| either the CDDL, the GPL Version 2 or to extend the choice of license to |
| its licensees as provided above. However, if you add GPL Version 2 code |
| and therefore, elected the GPL Version 2 license, then the option applies |
| only if the new code is made subject to such option by the copyright |
| holder. |
| |
| --> |
| |
| </HEAD> |
| <BODY BGCOLOR="white"> |
| |
| <p>Contains annotations and interfaces for defining interceptor methods, interceptor |
| classes and for binding interceptor classes to target classes.</p> |
| |
| <h3>Interceptor methods</h3> |
| |
| <p>An interceptor method may be defined on a target class itself or on an interceptor |
| class associated with the target class.</p> |
| |
| <p>There are three kinds of interceptor method:</p> |
| |
| <ul> |
| <li>{@linkplain javax.interceptor.AroundInvoke method interceptor methods} for |
| methods of a target class (e.g. managed bean / EJB component)</li> |
| <li>{@linkplain javax.interceptor.AroundTimeout timeout method interceptor methods} |
| for timeout methods of a target class (e.g. EJB component)</li> |
| <li>lifecycle callback interceptor methods for |
| {@link javax.annotation.PostConstruct @PostConstruct} |
| and {@link javax.annotation.PreDestroy @PreDestroy} callbacks of managed beans |
| and EJB components and for {@link javax.annotation.PrePassivate @PrePassivate} and |
| {@link javax.annotation.PostActivate @PostActivate} |
| methods of EJB {@linkplain javax.ejb.Stateful stateful} session beans.</li> |
| </ul> |
| |
| <p>An interceptor method may be defined by annotating the method, or using the EJB |
| deployment descriptor. Interceptor methods may not be declared <tt>static</tt> or |
| <tt>final</tt>.</p> |
| |
| <p>An interceptor class or target class may have multiple interceptor methods. However, |
| an interceptor class or target class may have no more than one interceptor method for |
| a certain type of interception: {@link javax.interceptor.AroundInvoke}, |
| {@link javax.interceptor.AroundTimeout}, {@code PostConstruct}, {@code PreDestroy}, |
| {@code PrePassivate} or {@code PostActivate}.</p> |
| |
| <h3>Interceptor classes</h3> |
| |
| <p>An interceptor class is a class (distinct from the target class) whose methods are |
| invoked in response to invocations and/or lifecycle events on the target class. Any |
| number of interceptor classes may be associated with a target class.</p> |
| |
| <p>An interceptor class must have a public constructor with no parameters.</p> |
| |
| <p>Interceptor classes may be annotated |
| {@link javax.interceptor.Interceptor @Interceptor}, but this is not required |
| when {@link javax.interceptor.Interceptors @Interceptors} or the EJB deployment |
| descriptor are used to bind the interceptor to its target classes.</p> |
| |
| <h3>Defining the interceptor classes of a target class</h3> |
| |
| <p>Interceptor classes of a target class or method of a target class may be defined in |
| several ways:</p> |
| |
| <ul> |
| <li>By annotating the target class or method of the target class with |
| {@link javax.interceptor.Interceptors @Interceptors} and specifying the |
| interceptor class.</li> |
| <li>If the target class is an EJB component, by using the EJB deployment descriptor.</li> |
| <li>If the target class is a {@linkplain javax.enterprise.inject CDI bean}, by |
| annotating both the interceptor class and the target class with an |
| {@linkplain javax.interceptor.InterceptorBinding interceptor binding}.</li> |
| </ul> |
| |
| <p>Any interceptor class may be defined to apply to a target class at the class level. |
| In the case of method interceptors, the interceptor applies to all methods of the target |
| class. In the case of timeout method interceptors, the interceptor applies to all |
| timeout methods of the target class.</p> |
| |
| <p>{@link javax.interceptor.ExcludeClassInterceptors @ExcludeClassInterceptors} |
| or the EJB deployment descriptor may be used to exclude the invocation of class level |
| interceptors for a method of a target class.</p> |
| |
| <p>A method interceptor may be defined to apply only to a specific method of the |
| target class. Likewise, a timeout method interceptor may be defined to apply only to |
| a specific timeout method of the target class. However, if an interceptor class that |
| defines lifecycle callback interceptor methods is defined to apply to a target class |
| at the method level, the lifecycle callback interceptor methods are not invoked.</p> |
| |
| <h3>Default Interceptors</h3> |
| |
| <p>Default interceptors may be defined to apply to a set of target classes using |
| the EJB deployment descriptor. The default interceptors are invoked before any other |
| interceptors for a target class. The EJB deployment descriptor may be used to specify |
| alternative orderings.</p> |
| |
| <p>{@link javax.interceptor.ExcludeDefaultInterceptors @ExcludeDefaultInterceptors} |
| or the EJB deployment descriptor may be used to exclude the invocation of default |
| interceptors for a target class or method of a target class.</p> |
| |
| <h3>Interceptor lifecycle</h3> |
| |
| <p>The lifecycle of an interceptor instance is the same as that of the target class |
| instance with which it is associated. When the target instance is created, a |
| corresponding interceptor instance is created for each associated interceptor class. |
| These interceptor instances are destroyed when the target instance is destroyed.</p> |
| |
| <p>Both the interceptor instance and the target instance are created before any |
| {@link javax.annotation.PostConstruct @PostConstruct} callbacks are invoked. Any |
| {@link javax.annotation.PreDestroy @PreDestroy} callbacks are invoked before the |
| destruction of either the target instance or interceptor instance. |
| |
| <p>An interceptor instance may hold state. An interceptor instance may be the target |
| of dependency injection. Dependency injection is performed when the interceptor instance |
| is created, using the naming context of the associated target class. The |
| {@link javax.annotation.PostConstruct @PostConstruct} interceptor callback method |
| is invoked after this dependency injection has taken place on both the interceptor |
| instances and the target instance.</p> |
| |
| <p>An interceptor class shares the enterprise naming context of its associated target |
| class. Annotations and/or XML deployment descriptor elements for dependency injection or |
| for direct JNDI lookup refer to this shared naming context.</p> |
| |
| <h3>Interceptors for lifecycle callbacks</h3> |
| |
| <p>A lifecycle callback interceptor method is a non-final, non-static method with return |
| type <tt>void</tt> of the target class (or superclass) or of any interceptor class. A |
| lifecycle callback interceptor method declared by the target class (or superclass) must |
| have no parameters. A lifecycle callback interceptor method declared by an interceptor |
| class must have a single parameter of type {@link javax.interceptor.InvocationContext}.</p> |
| |
| <pre> |
| @PostConstruct |
| public void interceptPostConstruct(InvocationContext ctx) { ... } |
| </pre> |
| |
| <p>A single lifecycle callback interceptor method may be used to interpose on multiple |
| callback events.</p> |
| |
| <pre> |
| @PostConstruct @PreDestroy |
| public void interceptLifecycle(InvocationContext ctx) { ... } |
| </pre> |
| |
| <p>A class may not declare more than one lifecycle callback interceptor method for |
| a particular lifecycle event.</p> |
| |
| <p>Lifecycle callback interceptor method invocations occur within unspecified |
| transaction and security contexts.</p> |
| |
| <p>Lifecycle callback interceptor methods may throw runtime exceptions but not checked |
| exceptions.</p> |
| |
| @see javax.interceptor.AroundInvoke |
| @see javax.interceptor.AroundTimeout |
| @see javax.interceptor.Interceptors |
| @see javax.interceptor.InvocationContext |
| |
| </BODY> |
| </HTML> |
