TIBCO ActiveMatrix BusinessWorks ActiveAspects Plug-in provides support for executing advices developed in Java. TIBCO ActiveMatrix BusinessWorks defines both a Java API as well as a set of annotations that have to be used for creating Advice Implementations.
Relationship between an advice and its implementation is very important. An advice is a configured instance of an advice implementation. Multiple advices can be implemented with the same implementation. Therefore, there is an N-to-one relationship between advices and their associated java implementation.
TIBCO ActiveMatrix BusinessWorks ActiveAspects Plug-in defines a couple of java annotations that are used for advertising aspect specific metadata. These annotations are defined in the package
com.tibco.bw.poa.runtime.annotation. This section describes these annotations.
The @AdviceImpl Java Annotation
public class MyAdviceImplementation … {
Table 4 describes the 5 optional parameters.
Advice implementations get instantiated in different scopes, which can be controlled using the
scope parameter. The valid values of this parameter are the following:
If the scope parameter is set to a different value than the one mentioned above, the BW engine throws an
AspectException at run-time, when the engine gets initialized.
public class MyAdviceImplementation … }
If the dataAccess parameter is set to a different value than the ones mentioned above, the BW engine throws an
AspectException at run-time, when the engine gets initialized.
dataAccess = "READ-WRITE"
public class MyAdviceImplementation … {
public void execute(N input, AspectProcessContext context) {
// the advice implementation mutates the data here…
The default value of this parameter, which is used when the parameter is not explicitly set by the user, is "READ-ONLY". Hence, an advice implementation that mutates the data must explicitly set the dataAccess parameter to "READ-WRITE". If an advice implementation that mutates the data does not set this parameter appropriately, a
ClassCastException is thrown at run-time, when the advice implementation tries to use a mutable XML processing contex.
Advice implementations can hibernate and resume Jobs. If an advice implementation takes advantage of this feature, it must explicitly declare that it does it through the
hibernatesJobs parameter. The valid values of this parameter are:
public class MyAdviceImplementation … {
public void execute(N input, AspectProcessContext context) {
if (need_to_hibernate_job) {
context.setHibernateJobEnabled(0);
The default value of this parameter, which is used when the user doesn't explicitly set it, is
false.
By default, advice implementations do not hibernate jobs. If an advice implementation attempts to call the API to hibernate a job without explicitly setting the
hibernatesJobs parameter to
true, an
AspectException is thrown at run-time. This exception may result in the job to be terminated abnormally, depending on how exceptions are handled at the process level.
When accessing the incoming XML document, advice Implementations may or may not be dependent on a particular schema. For example, an advice implementation that changes the value of a JMS property in a JMS message sent by the
JMSQueueSendReceive activity is dependent on the format (like XML schema) of the
JMSQueueSendReceive activity's input message.
A way is provided to the advice implementation developer to declare a dependency of a particular instantiation context through the use of two parameters defined as part of the
@AdviceImpl annotation: targetKind and targetFilter.
If the targetKind parameter is set to a different value than the ones mentioned above, the BW engine throws an
AspectException at run-time, when the engine gets initialized.
The default value of this parameter, which is used when the user doesn't explicitly set it, is
"". By default, advice implementations do not depend on a particular context (can be executed anywhere).
When the targetKind parameter is set, the developer of the advice implementation can also specify a target filter, using the
targetFilter parameter, which is used to further narrow down the scope of the instantiation context. Using this parameter, the developer can specify the type of the activity around which the implementation can be instantiated. For example, the developer can specify the advice implementation that can only be instantiated in the context of a
FileReadActivity. The value of the parameter (the filter) is the same as the value of the
activity() primitive's "
type" parameter that is defined as part of the
Point Cut Query Language.
The default value of this parameter, which is used when the advice implementation developer does not explicitly set it, is
"". By default, advice implementations can be executed in any context.
targetKind = "ACTIVITY-BEFORE",
targetFilter = "bw.JMSQueueSendActivity"
When the Aspect engine gets initialized, the engine checks these two parameters and uses them to validate the aspect configurations. If an advice is about to be instantiated in a context that is not valid, the engine throws an exception.
A more complicated example shows how all these parameters can be used together. The following is a singleton advice implementation that requires read-write access to the data, that hibernates jobs and must be instantiated and executed before
JMSQueueSend activities:
dataAccess = "READ-WRITE",
targetKind = "ACTIVITY-BEFORE",
targetFilter = "bw.JMSQueueSendActivity"
To enable tracing for Aspect Engine, set the AspectEngine.Trace property to
true in a
cfg file and this file should be passed as an argument to the BusinessWorks engine.
public class AdviceImplExample<I, U, N extends I, A extends I, S, T, X>
extends SyncAdvice<I, U, N, A, S, T, X> {
public String currency = "$";
Advice implementations can define configuration properties that are used for configuring the behavior and execution of the java class. For example, an advice implementation that changes the value of a JMS Property may choose to define the name of the JMS property using an advice implementation property. TIBCO ActiveMatrix BusinessWorks ActiveAspects Plug-in makes these advice implementation properties visible and configurable from advices. This means that two advices that have the same implementation (that are implemented with the same java class) can specify different values for the same property. In the example in
The @Property Java Annotation, there could be two or more advices that want to mutate JMS Properties. These advices can share the same implementation and each one can configure it with a different JMS Property name.
A required advice property must be set in every advice that uses the implementation class that defines it. The ActiveMatrix BusinessWorks engine throws an exception at the time the engine gets initialized, if it finds a required advice implementation property that is not set in an advice.
The default value, which is used when the "required" parameter is not set, is true. Therefore, by default, advice properties are required to be set in aspect files.
Advice implementations advertise configuration properties through the use of the @Property annotation. The following example shows an advice implementation with two properties:
targetKind="ACTIVITY-BEFORE",
targetFilter="bw.JMSQueueSendActivity"
public class JMSPropertyChangerWithConfig<I, U, N extends I, A extends I, S, T, X> extends SyncAdvice<I, U, N, A, S, T, X> {
public String propertyToModify ="foo";
@Property (required = false)
public String propertyToModifyValue = "defaultFooValue";
•
|
Only properties of String type are supported. If the Aspect Engine detects a property of a type different than String, it throws an exception at initialization time.
|
•
|
Member variables that are exposed as advice configuration properties must be declared public. If the BW Engine detects a property that is not declared public, it throws an exception at initialization time.
|
At run-time, when an advice is instantiated, the BW engine injects in the advice instance the property values that are specified in the aspect XML file.
Setter and Getter methods do not have to be available in the java class to provide access to the member variables. The BW engine can inject these property values by accessing the member variables directly.
All advices that share the same implementation instance (for example when using an implementation configured with an
APPLICATION scope) must have the same property values. The BW Engine configures the implementation instance at the time the first advice that is using it gets instantiated. If a subsequent advice that uses the same implementation instance is instantiated, the BW engine validates that all its properties have the same values as the properties set on the advice implementation instance. If a mismatch is found, the BW Engine throws an exception.
Refer Advice Configuration Properties about how property values are set in aspect files.
At run-time, during its initialization process, the BW Engine weaves aspects into BW processes. As part of this process, the BW engine instantiates advices and injects them in different join points inside processes. Since each advice has an implementation associated with it, which is represented as a Java class, the BW engine either creates an instance of this class or takes one from a pool of already created object instances. ActiveMatrix BusinessWorks 5.9 supports binding multiple advice instances to the same advice implementation java class instance through the concept of scoping.
Since scope is an attribute of the advice implementation, it is configured at the java class level in an annotation. This means that all advices using the same advice implementation java class have the same scoping configuration.
The Advice scope is used when a new advice implementation object instance must be created for every advice instance. This mode is usually used when multiple advices that share the same implementation do not need to share any state.
Figure 12 shows this Advice Scope mode.
Since an advice instance runs in a multi threaded environment potentially serving multiple process instances (like jobs) at the same time, each job is executed in a different thread.
The Application scope is used when the developer of the advice implementation java class wants to ensure that only one advice implementation object instance is created for the entire application. In TIBCO ActiveMatrix BusinessWorks ActiveAspects Plug-in, this means one object instance per engine. Hence, all advice instances that are implemented with the same implementation share the same advice implementation object instance.
Figure 13 shows the Application Scope mode.
When it executes, an advice implementation has access to the XML document that is available in a particular context (like, join point). This XML Document is build based on a schema, which is again dependent on the context. For example, when it runs before an activity, the XML Document must be valid against the XML Schema that defines the input type of the activity.
In order to provide a deterministic behavior that allows the engine to fail fast when configuration issues are detected, TIBCO ActiveMatrix BusinessWorks ActiveAspects Plug-in provides a declarative way of specifying metadata about advice implementations. This metadata is primarily driven by two main questions a developer of an advice implementation needs to answer.
Not all advice implementations mutate the incoming XML Document. If the engine knows that an advice does not mutate the XML document, it can perform some optimizations, such as not requiring a revalidation of the document after the execution of the advices. In TIBCO ActiveMatrix BusinessWorks ActiveAspects Plug-in, an advice cannot mutate the incoming XML Document unless it explicitly states that it does it, in the advice implementation metadata. For details about how to configure an advice to allow the mutation of the XML Document, refer
The @AdviceImpl Java Annotation.
Figure 14 shows two advices, one that mutates the XML Document and another that does not mutate the XML Document.
The XML Document is passed as an input parameter to the execute() method that is defined as part of the Advice Implementation Java class. The following is the signature of the method:
public N execute(N inputDoc, AspectProcessContext context)
The XML Document is the first input parameter (like, "inputDoc"). TIBCO ActiveMatrix BusinessWorks ActiveAspects Plug-in uses gXML (Generic XML) as the data model, which allows it to support multiple underlying XML tree models such as DOM, Axiom, etc. For more information about gXML and general information on how to manipulate an XML Document with gXML, refer
References.
In order to manipulate an XML Document, the advice implementation must get access to the gXML processing context object, which is instance of
org.gxml.sa.GxProcessingContext. This object can be retrieved by an advice implementation from the advice's context, in the following way:
GxProcessingContext<I,U,N,A,S,T,X> pContext = getAdviceContext().getGxProcessingContext();
This object is then used for traversing and pulling information from the XML Document. This object cannot be used for mutating an XML Document, though. In order to mutate an XML Document, the advice implementation needs to get a mutable gXML processing context, which is instance of
org.gxml.sa.GxProcessingContextMutable. Since this class extends
GxProcessingContext, the way to retrieve a mutable processing context is very similar to the way to retrieve the immutable processing context (like, note the extra type casting):
GxProcessingContextMutable<I,U,N,A,S,T,X> pContext = GxProcessingContextMutable)getAdviceContext().getGxProcessingContext();
If an advice implementation type casts the returned value of getGxProcessingContext() to a mutable processing context without explicitly setting the
@AdviceImplementation or
dataAccess parameter to "
READ-WRITE", the previous call throws a
ClassCastException at run-time. That is since the engine injects a mutable processing context in an advice instance only if its implementation is mutable.
Advice implementations are packaged in JAR files and need to be available in the CLASSPATH at run-time in order for the engine to properly instantiate advices. It does not really matter how these advice implementations are packaged in JAR files. What is important is that all the advice implementations (like, java classes) are referenced by advices to be available in the
CLASSPATH at run-time, at the time the BW engine gets initialized.
TIBCO ActiveMatrix BusinessWorks ActiveAspects Plug-in does not support loading a JAR file in the
CLASSPATH at run-time, after the engine has been initialized. Therefore, unless it gets restarted, the BW engine cannot execute an advice implemented with a java class that was not available in the
CLASSPATH at initialization time.
The TIBCO ActiveMatrix BusinessWorks ActiveAspects Plug-in installer creates a "
lib" folder under
BWAA_HOME and adds it to the
CLASSPATH. This folder can be used for storing all advice implementation libraries (that is, JAR files).