diff --git a/spec/src/main/asciidoc/chapters/interceptor_programming_contract/definition_of_interceptor_classes_and_interceptor_methods.adoc b/spec/src/main/asciidoc/chapters/interceptor_programming_contract/definition_of_interceptor_classes_and_interceptor_methods.adoc new file mode 100644 index 0000000..946695a --- /dev/null +++ b/spec/src/main/asciidoc/chapters/interceptor_programming_contract/definition_of_interceptor_classes_and_interceptor_methods.adoc @@ -0,0 +1,101 @@ +//// +******************************************************************* +* Copyright (c) 2019 Eclipse Foundation +* +* This specification document is made available under the terms +* of the Eclipse Foundation Specification License v1.0, which is +* available at https://www.eclipse.org/legal/efsl.php. +******************************************************************* +//// + +[[definition_of_interceptor_classes_and_interceptor_methods]] +== Definition of Interceptor Classes and Interceptor Methods + +An interceptor method for a target class may +be declared in the target class, in an interceptor class associated with +the target class, or in a superclass of the target class or interceptor +class. + +Any number of interceptor classes may be +associated with a target class. See Chapter +link:intercept.html#a446[See Interceptor Ordering] for rules on +interceptor ordering. + +An interceptor class must not be abstract and +must have a public no-arg constructor. + +This specification defines the interceptor +method types listed below. Extension specifications may define +additional interceptor method types. + +Around-invoke interceptor methods (annotated +with the _jakarta.interceptor.AroundInvoke_ annotation). Around-invoke +interceptor methods interpose on the invocation of business methods. + +Around-timeout interceptor methods (annotated +with the _jakarta.interceptor.AroundTimeout_ annotation). Around-timeout +interceptor methods interpose on the invocation of timeout methods, in +response to timer events. + +Post-construct interceptor methods (annotated +with the _jakarta.annotation.PostConstruct_ annotation). Post-construct +interceptor methods are invoked after dependency injection has been +completed on the target instance. + +Pre-destroy interceptor methods (annotated +with the _jakarta.annotation.PreDestroy_ annotation). Pre-destroy +interceptor methods are invoked before the target instance and all +interceptor instances associated with it are destroyed by the container. + +Around-construct interceptor methods +(annotated with the _jakarta.interceptor.AroundConstruct_ annotation). +Around-construct interceptor methods interpose on the invocation of the +constructor of the target instance. + +Post-construct, pre-destroy, and +around-construct interceptor methods are collectively referred to as +_lifecycle callback interceptor methods_ . Extension specifications may +define additional lifecycle callback events and lifecycle callback +interceptor method types. + +Up to one interceptor method of each +interceptor method type may be defined in the same class. More +specifically, up to one around-invoke interceptor method, one +around-timeout interceptor method, and one lifecycle callback +interceptor method for each of the different lifecycle events may be +defined in the same class. Only the interceptor methods of the +interceptor class that are relevant for the given invocation context are +invoked. For example, when a business method is invoked, around-invoke +interceptor methods are invoked, but any around-construct, +around-timeout, post-construct, or pre-destroy methods are ignored. + +A single interceptor method may be defined to +interpose on any combination of business methods, timeout methods, and +lifecycle callback events. + +Interceptor methods and interceptor classes +may be defined for a class by means of metadata annotations or, +optionally, by means of a deployment descriptor. + +Interceptor classes may be associated with +the target class using either interceptor binding annotations (see +link:intercept.html#a303[See Associating Interceptors with +Classes and Methods using Interceptor Bindings]) or the +_jakarta.interceptor.Interceptors_ annotation (see +link:intercept.html#a423[See Associating Interceptors with +Classes and Methods using the Interceptors Annotation]). Typically only +one interceptor association type is used for any target class. + +An extension specification may use a +deployment descriptor to specify the invocation order of interceptors or +to override the order specified in metadata annotations. A deployment +descriptor can optionally be used to define interceptors, to define +default interceptors, or to associate interceptors with a target class. +For example, the EJB specification link:intercept.html#a542[See +Jakarta Enterprise Beans, version 4.0. +https://jakarta.ee/specifications/enterprise-beans/4.0/.] requires support for the +ejb-jar.xml deployment descriptor and the CDI specification +link:intercept.html#a543[See +Jakarta Contexts and Dependency Injection (CDI specification), version 3.0. +https://jakarta.ee/specifications/cdi/3.0/.] requires support for the beans.xml +deployment descriptor. diff --git a/spec/src/main/asciidoc/chapters/interceptor_programming_contract/interceptor_programming_contract.adoc b/spec/src/main/asciidoc/chapters/interceptor_programming_contract/interceptor_programming_contract.adoc index 0564304..80ec080 100644 --- a/spec/src/main/asciidoc/chapters/interceptor_programming_contract/interceptor_programming_contract.adoc +++ b/spec/src/main/asciidoc/chapters/interceptor_programming_contract/interceptor_programming_contract.adoc @@ -12,3 +12,5 @@ == Interceptor Programming Contract include::terminology.adoc[] + +include::definition_of_interceptor_classes_and_interceptor_methods.adoc[]