Added Invocation Context

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

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

@@ -18,3 +18,5 @@ include::definition_of_interceptor_classes_and_interceptor_methods.adoc[]
 include::interceptor_life_cycle.adoc[]
 
 include::interceptor_environment.adoc[]
+
+include::invocation_context.adoc[]

spec/src/main/asciidoc/chapters/interceptor_programming_contract/invocation_context.adoc

@@ -0,0 +1,116 @@
+////
+*******************************************************************
+* 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.
+*******************************************************************
+////
+[[invocation_context]]
+== Invocation Context
+
+The _InvocationContext_ object provides
+information that enables interceptor methods to control the behavior of
+the invocation chain.
+
+public interface InvocationContext \{
+
+ public Object getTarget();
+
+ public Object getTimer();
+
+ public Method getMethod();
+
+ public Constructor<?> getConstructor();
+
+ public Object[] getParameters();
+
+ public void setParameters(Object[] params);
+
+ public java.util.Map<String, Object>
+getContextData();
+
+ public Object proceed() throws Exception;
+
+}
+
+
+
+The same _InvocationContext_ instance is
+passed to each interceptor method for a given target class method or
+lifecycle event interception.
+
+The _InvocationContext_ instance allows an
+interceptor method to save information in the _Map_ obtained via the
+_getContextData_ method. This information can subsequently be retrieved
+and/or updated by other interceptor methods in the invocation chain, and
+thus serves as a means to pass contextual data between interceptors. The
+contextual data is not sharable across separate target class method or
+or lifecycle callback event invocations. The lifecycle of the
+_InvocationContext_ instance is otherwise unspecified.
+
+If interceptor methods are invoked as a
+result of the invocation on a web service endpoint, the map returned by
+_getContextData_ will be the JAX-WS _MessageContext_
+link:intercept.html#a544[See
+Jakarta XML Web Services (JAX-WS 3.0) version 3.0.
+https://jakarta.ee/specifications/xml-web-services/3.0/.].
+
+The _getTarget_ method returns the associated
+target instance. For around-construct lifecycle callback interceptor
+methods, getTarget returns null if called before the proceed method
+returns.
+
+The _getTimer_ method returns the timer
+object associated with a timeout method invocation. The _getTimer_
+method returns null for interceptor method types other than
+around-timeout interceptor methods.
+
+The _getMethod_ method returns the method of
+the target class for which the current interceptor method was invoked.
+The _getMethod_ returns null in a lifecycle callback interceptor method
+for which there is no corresponding lifecycle callback method declared
+in the target class (or inherited from a superclass) or in an
+around-construct lifecycle callback interceptor method.
+
+The getConstructor method returns the
+constructor of the target class for which the current around-construct
+interceptor method was invoked. The _getConstructor_ method returns null
+for interceptor method types other than around-construct interceptor
+methods.
+
+The _getParameters_ method returns the
+parameters of the method or constructor invocation. If the
+_setParameters_ method has been called, _getParameters_ returns the
+values to which the parameters have been set.
+
+The _setParameters_ method modifies the
+parameters used for the invocation of the target class method or
+constructor. Modifying the parameter values does not affect the
+determination of the method or the constructor that is invoked on the
+target class. The parameter types must match the types for the target
+class method or constructor, and the number of parameters supplied must
+equal the number of parameters on the target class method or
+constructorlink:#a569[3], or the _IllegalArgumentException_ is
+thrown to the _setParameters_ call.
+
+The _proceed_ method causes the invocation of
+the next interceptor method in the chain or, when called from the last
+around-invoke or around-timeout interceptor method, the target class
+method. For around-construct lifecycle callback interceptor methods, the
+invocation of the _proceed_ method in the last interceptor method in the
+chain causes the target instance to be created. Interceptor methods must
+always call the _InvocationContext.proceed_ method or no subsequent
+interceptor methods, target class method, or lifecycle callback methods
+will be invoked, or—in the case of around-construct interceptor
+methods—the target instance will not be created. The _proceed_ method
+returns the result of the next method invoked. If a method is of type
+_void_ , the invocation of the _proceed_ method returns _null_ . For
+around-construct lifecycle callback interceptor methods, the invocation
+of proceed in the last interceptor method in the chain causes the target
+instance to be created. For all other lifecycle callback interceptor
+methods, if there is no lifecycle callback interceptor method defined on
+the target class, the invocation of _proceed_ in the last interceptor
+method in the chain is a no-oplink:#a570[4], and _null_ is
+returned.