Added Interceptor Ordering Rules and Use of the Priority Annotation i…

…n Ordering Interceptors

Signed-off-by: thadumi <th.theodor.th@gmail.com>

spec/src/main/asciidoc/chapters/interceptor_ordering/interceptor_ordering.adoc

@@ -12,3 +12,7 @@
 == Interceptor Ordering
 
 include::enabling_interceptors.adoc[]
+
+include::interceptor_ordering_rules.adoc[]
+
+include::use_of_the_priority_annotation_in_ordering_interceptors.adoc[]

spec/src/main/asciidoc/chapters/interceptor_ordering/interceptor_ordering_rules.adoc

@@ -0,0 +1,96 @@
+////
+*******************************************************************
+* 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.
+*******************************************************************
+////
+
+[[interceptor_ordering_rules]]
+== Interceptor Ordering Rules
+
+For each interceptor method type (i.e.,
+around-invoke, around-timeout, post-construct, etc.), the following
+interceptor invocation ordering rules apply, except as specified
+otherwise by an extension specification.
+
+Default interceptors are invoked first.
+
+Default interceptors are invoked in the order
+defined by the extension specification (e.g., by their order in the
+deployment descriptor).
+
+If a default interceptor class has
+superclasses, interceptor methods declared in the interceptor class’s
+superclasses are invoked before the interceptor method declared in the
+interceptor class itself, most general superclass first.
+
+Interceptors declared by applying the
+Interceptors annotation _at class-level_ to the target class are invoked
+next.
+
+Interceptor methods declared in the
+interceptor classes listed in the _Interceptors_ annotation are invoked
+in the same order as the specification of the interceptor classes in
+that annotation.
+
+If an interceptor class declared by applying
+the Interceptors annotation _at class-level_ has superclasses,
+interceptor methods declared in the interceptor class’s superclasses are
+invoked before the interceptor method declared in the interceptor class
+itself, most general superclass first.
+
+ _NOTE:_ _This specification does not define
+the semantics of applying the Interceptors annotation to a superclass of
+the target class, and thus the corresponding interceptor methods may or
+may not be invoked. Applications that specify the Interceptors
+annotation on a superclass of the target class will not be portable._
+
+Interceptors declared by applying the
+Interceptors annotation _at method- or constructor-level_ are invoked
+next.
+
+Interceptor methods declared in the
+interceptor classes listed in the _Interceptors_ annotation are invoked
+in the same order as the specification of the interceptor classes in
+that annotation.
+
+If an interceptor class declared by applying
+the Interceptors annotation _at method- or constructor-level_ has
+superclasses, interceptor methods declared in the interceptor class’s
+superclasses are invoked before the interceptor method declared in the
+interceptor class itself, most general superclass first.
+
+Interceptors declared using interceptor
+bindings are invoked next.
+
+All interceptors specified using interceptor
+binding annotations visible on the target class (e.g., specified on the
+class or visible on the class because they were declared with the
+_Inherited_ annotation) are combined with all binding annotations on the
+target method and sorted by the priorities specified by the _Priority_
+annotation; and then the interceptor methods are invoked in order of
+priority. The _Priority_ annotation is described in Section
+link:intercept.html#a472[See Use of the Priority Annotation in
+Ordering Interceptors].
+
+If an interceptor class declared using
+interceptor bindings has superclasses, interceptor methods declared in
+the interceptor class’s superclasses are invoked before the interceptor
+method declared in the interceptor class itself, most general superclass
+first.
+
+Interceptor methods declared in the target
+class or in any superclass of the target class are invoked last.
+
+If the target class has superclasses,
+interceptor methods declared in the target class’s superclasses are
+invoked before an interceptor method declared in the target class
+itself, most general superclass first.
+
+If an interceptor method is overridden by
+another method (regardless whether that method is itself an interceptor
+method), it will not be invoked.
+

spec/src/main/asciidoc/chapters/interceptor_ordering/use_of_the_priority_annotation_in_ordering_interceptors.adoc

@@ -0,0 +1,96 @@
+////
+*******************************************************************
+* 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.
+*******************************************************************
+////
+
+[[use_of_the_priority_annotation_in_ordering_interceptors]]
+== Use of the Priority Annotation in Ordering Interceptors
+
+The _Priority_ annotation can be used to
+enable and order interceptors associated with components that use
+interceptor bindings. The required _value_ element of the _Priority_
+annotation determines the ordering. Interceptors with smaller priority
+values are called first. If more than one interceptor has the same
+priority, the relative order of those interceptors is undefined.
+
+@Monitored @Interceptor @Priority(100)
+
+public class MonitoringInterceptor \{
+
+
+
+ @AroundInvoke
+
+ public Object
+monitorInvocation(InvocationContext ctx)
+
+ throws Exception \{ ... }
+
+
+
+}
+
+The Priority annotation is ignored when
+computing the invocation order of interceptors bound to a component
+using the Interceptors annotation.
+
+The following priority values are defined for
+interceptor ordering when used with the Priority annotation.
+Interceptors with lower priority values are invoked earlier in the
+interceptor chain.
+
+Interceptor.Priority.PLATFORM_BEFORE = 0
+
+Interceptor.Priority.LIBRARY_BEFORE = 1000
+
+Interceptor.Priority.APPLICATION = 2000
+
+Interceptor.Priority.LIBRARY_AFTER = 3000
+
+Interceptor.Priority.PLATFORM_AFTER = 4000
+
+These values define the following interceptor
+ranges to order interceptors for a specific interposed method or event
+in the interceptor chain:
+
+Interceptors defined by the Jakarta EE Platform
+specifications that are to be executed at the beginning of the
+interceptor chain should have priority values in the range
+PLATFORM_BEFORE up until LIBRARY_BEFORE.
+
+Interceptors defined by extension libraries
+that are intended to be executed earlier in the interceptor chain, but
+after interceptors in the range up until _LIBRARY_BEFORE_ should have
+priority values in the range LIBRARY_BEFORE up until APPLICATION.
+
+Interceptors defined by applications should
+be in the range APPLICATION up until LIBRARY_AFTER.
+
+Interceptors defined by extension libraries
+that are intended to be executed later in the interceptor chain should
+have priority values in the range LIBRARY_AFTER up until PLATFORM_AFTER.
+
+Interceptors defined by the Jakarta EE Platform
+specifications that are to be executed at the end of the interceptor
+chain should have priority values at PLATFORM_AFTER or higher.
+
+An interceptor that must be invoked before or
+after another defined interceptor can choose any appropriate value.
+
+Negative priority values are reserved for
+future use by this specification and should not be used.
+
+The following example defines an extension
+library interceptor that is to be executed before any application
+interceptor, but after any early platform interceptor:
+
+@Priority(Interceptor.Priority.LIBRARY_BEFORE+10)
+
+@Validated @Interceptor
+
+public class ValidationInterceptor \{ ... }