Process ContextsPage edited by Tammo van Lessenprocess context documentation updated.Process Contexts
AbstractTo allow the circulation of transport metadata from messages to processes and then from processes to messages, we want to add support for different levels of contextual data to our process engine. The main use cases are:
ArchitectureThe aim of this proposal is to make transport metadata accessible within BPEL processes and allow modelers and deployers to define which metadata should be propagated between process and partners. Therefore, we model such metadata in terms of contexts. Contexts are modeled as a bag of metadata information represented as key-value pairs and are attached to partner links. A partner link may maintain multiple contexts; each of them is identifiable by a name attribute to distinguish context used for different purposes (e.g. security context vs. tracing context). ContextsContexts are modeled as a bag of metadata information represented as key-value pairs (string, string) and are attached to partner links. Contexts have a name attribute. Contexts are persisted in ODE's runtime database. Long values are stored as a CLOB whereas shorter values (<250 characters) are automatically stored in an indexed VARCHAR field. Since contexts should also be accessible in BPEL, there is also an XML-based representation. It is defined as follows, the according XMLSchema can be found here "Example: Context data in its XML representation" <?xml version="1.0" encoding="UTF-8"?> <ctx:contexts xmlns:ctx="http://www.apache.org/ode/schemas/context/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.apache.org/ode/schemas/context/2009 contexts.xsd "> <ctx:context name="foo"> <ctx:value key="bar">baz</ctx:value> </ctx:context> <ctx:context name="tracing"> <ctx:value key="id">0815</ctx:value> </ctx:context> </ctx:contexts> {null}
h3. Context Interceptors
At the transport level, message headers can be translated to context data and contexts can be translated to message headers. Context interceptors define how the headers are set to/from contexts and which contexts are affected. Interceptors are Java classes that implement the following interface. They can be registered either globally in ode's property configuration file or per process in the {{deploy.xml}}.
/**
public abstract void configure(Element configuration); /**
abstract void onPartnerInvoke(ContextData ctx, Message msg); } h3. Working with Contexts in BPEL h4. Declaring Context Interceptors In order to use context interceptors, their implementation must be registered with ODE. There are two options to do this: * Engine-wide registration - the context interceptor will be available for all processes that are deployed to this ODE instance. * Per-process registration - the context interceptor will only be available for a particular process model. Engine-wide context interceptors are registered in ODE's properties file (either {{ode-axis2.properties}} or {{ode-jbi.properties}}) using the properties key {{context.interceptors}}. {code:title=ode-axis2.properties} ... ode-axis2.context.interceptors = my.full.qualified.context.interceptor.class.name ... ode-jbi.properties ... ode-jbi.context.interceptors = my.full.qualified.context.interceptor.class.name ... Per-process context interceptors are declared in ODE's deployment descriptor deploy.xml: deploy.xml <deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03" xmlns:pns="http://ode/bpel/unit-test" xmlns:wns="http://ode/bpel/unit-test.wsdl"> <process name="pns:HelloWorld2"> <active>true</active> <provide partnerLink="helloPartnerLink"> <service name="wns:HelloService" port="HelloPort"/> </provide> <context> <propagate from="helloPartnerLink" to="helloPartnerLink2" context="*"/> <interceptor> <class-name>org.apache.ode.bpel.context.TestInterceptor</class-name> <config> <myparam1>x</myparam1> <myparam2>y</myparam2> </config> </interceptor> </context> </process> </deploy> The context-specific configuration takes place in the <context> element. The <interceptor> element is used to declare and register context interceptor implementations. The <class-name> element takes the full qualified class name of the context interceptor implementation (which must implement the ContextInterceptor interface). The content of the <config> element will be passed to configure method of the interceptor, immediately after instantiation. Static propagation rules can be configured directly in the deploy.xml. Using the <propagate> element, ODE can be configured to propagate all contexts named in the context attribute (space-separated list) from a certain partner link to another partner link. To propagate all contexts the context attribute should be set to *. These rules are automatically evaluated when an invoke activity is being executed. Before a BPEL process instance invokes an operation of a certain partner link, the propagation logic performs a look-up for propagation rules that have that partner link referenced by their to attribute. Subsequently the specified contexts are retrieved from the partner link specified by the from attribute of the rule, passed to the context interceptor that translates the context data into transport meta data, which is then added to the outgoing message. Customize Context Propagation in the Process ModelIn addition to static propagation rules, context propagation can be explicitly configured for outbound interaction activities (i.e. <invoke> and <reply>. Therefore, we introduce a new BPEL extension element <ctx:propagate> in the http://ode.apache.org/contextPropagation namespace (to which the ctx-prefix is bound to), following the syntax as described below:
<bpel:invoke ...>
<ctx:propagate ctx:fromPartnerLink="testPartnerLink" ctx:context="*"/>
</bpel:invoke>
<bpel:reply ...>
<ctx:propagate ctx:fromPartnerLink="testPartnerLink" ctx:context="*"/>
</bpel:reply>
The context data identified by this propagation rule will be passed to all registered context interceptors which enhance the outgoing message accordingly.
Accessing and Assigning Context DataContext data should be accessible within BPEL processes and from the outside, e.g. for management purposes. For the former, the <assign> activity has been extended to support copying data from and to contexts of a partner link. The according from/to specs are defined as follows:
<assign>
<!-- copy 'tracing' and 'security' contexts to a variable. -->
<copy>
<from partnerLink="pl1" context="tracing security"/>
<to>$var</to>
</copy>
<!-- copy context data from $var to pl1. Only 'tracing' and 'security' contexts will be written, other contexts remain unchanged. -->
<copy>
<from>$var</from>
<to partnerLink="pl1" context="tracing security"/>
</copy>
<!-- copy 'tracing' and 'security' contexts from pl1 to pl2. Pre-existing contexts in pl2 will be purged (*). -->
<copy>
<from partnerLink="pl1" context="tracing security"/>
<to partnerLink="pl2" context="*"/>
</copy>
<!-- copy 'tracing' and 'security' contexts from pl1 to pl2. Pre-existing contexts in pl2 will be merged (+). -->
<copy>
<from partnerLink="pl1" context="tracing security"/>
<to partnerLink="pl2" context="+"/>
</copy>
<!-- copy all contexts from pl1 to pl2. Pre-existing contexts in pl2 will be merged (+). -->
<copy>
<from partnerLink="pl1" context="*"/>
<to partnerLink="pl2" context="+"/>
</copy>
</assign>
When assigning context data to variables, the variable should be declared to be an instance of the context XSD (see Contexts section). It is also possible to copy only fragments of a context data set by applying an XPath query to the from-spec: "Extracting a tracing ID from a context and assigning it to a xs:string variable."
<assign>
<!-- copy 'tracing' and 'security' contexts to a variable. -->
<copy>
<from partnerLink="pl1" context="*">
<query>/ctx:contexts/ctx:conte...@name='tracing']/ctx:val...@key='id']</query>
</from>
<to>$tracingId</to>
</copy>
</assign>
In order to make context data accessible for external management tools, the ProcessManagement-API has been extended. Unknown macro: {TODO}
Change Notification Preferences
View Online
|
View Change
|
