com.tibco.bw.poa.runtime
Class AsyncAdvice<I,U,N extends I,A extends I,S,T,X>

java.lang.Object
  extended by com.tibco.bw.poa.runtime.Advice<I,U,N,A,S,T,X>
      extended by com.tibco.bw.poa.runtime.AsyncAdvice<I,U,N,A,S,T,X>

public abstract class AsyncAdvice<I,U,N extends I,A extends I,S,T,X>
extends Advice<I,U,N,A,S,T,X>

The base class of all asynchronous advice implementations.

The asynchronous model is designed for advice implementations that take some time to execute. These are usually advice implementations that communicate with external systems, perform I/O operations or perform tasks that can potentially bring down the performance of a BW application.

An asynchronous advice implementation does not execute its business logic on the engine job thread. In other words, the BusinessWorks engine does not hold the job thread until an asynchronous advice completes its execution. This allows the engine to execute advices and/or activities that might exist in the process on parallel tracks, while the asynchronous advice is executing. The engine does not, however, continue executing the next advice in the join point, or the next activity on the same track before the asynchronous advice completes its execution.

A typical asynchronous advice implementation gets a thread from a thread pool in its execute() method and starts executing its business logic on it. Right after that it calls AdviceController.setPending(long) with the appropriate timeout and returns from its execute(). After its business logic completes and before the advice thread finishes executing, the advice implementation calls AdviceController.setReady(com.tibco.bw.poa.runtime.ReturnWrapper) with the result object. Once the job thread is available to finish executing the asynchronous advice, the engine calls its postExecute() method by passing the result object received in the setReady() call. The advice implementation gets the opportunity to do any final job related cleanup operations before returning the final result object back to the engine.

If the advice implementation does not complete its execution in the allotted time, which is specified in the setPending() call, the engine times out the advice implementation by calling its cancelled() method.

An advice implementation that does not communicates with external systems, does not perform I/O operations and does not perform tasks that may take some time to execute can be implemented as synchronous advice implementation. For more information, see SyncAdvice.

Note:

Since:
1.0
See Also:
AdviceController, AspectProcessContext, SyncAdvice, Advice

Constructor Summary
AsyncAdvice()
           
 
Method Summary
abstract  void cancelled(AspectProcessContext<I,U,N,A,S,T,X> apc)
          This method is called when the advice has not completed within the allotted time as specified in the AdviceController.setPending() call.
abstract  void execute(N input, AspectProcessContext<I,U,N,A,S,T,X> context, AdviceController<N> controller)
          Starts the execution of the advice implementation.
 boolean isSynchronous()
          Always returns false since this is an asynchronous advice implementation.
abstract  N postExecute(AspectProcessContext<I,U,N,A,S,T,X> apc, ReturnWrapper<N> result)
          Finishes the execution of the advice implementation.
 
Methods inherited from class com.tibco.bw.poa.runtime.Advice
destroy, getAdviceContext, init, resumeFromHibernate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AsyncAdvice

public AsyncAdvice()
Method Detail

isSynchronous

public final boolean isSynchronous()
Always returns false since this is an asynchronous advice implementation.

Specified by:
isSynchronous in class Advice<I,U,N extends I,A extends I,S,T,X>
Returns:
true if the advice implementation is synchronous; false otherwise.

execute

public abstract void execute(N input,
                             AspectProcessContext<I,U,N,A,S,T,X> context,
                             AdviceController<N> controller)
                      throws AspectException
Starts the execution of the advice implementation.

An advice implementation must pay very close attention to concurrency issues since it executes in a multi-threaded environment. The BusinessWorks engine can call this method multiple times simultaneously, on the same advice instance, usually once for each job that gets executed (for the process this advice belong to). If the advice instance is not in the execution path of a job, this method is not called for that particular job. If the advice instance executes in a loop, this method may be called multiple times for the same job.

The XML document that is passed as an input parameter is the document that is available in the join point where the advice instance is executing.

Parameters:
input - the input XML document
context - the context associated with the job (i.e. process instance)
Throws:
AspectException

postExecute

public abstract N postExecute(AspectProcessContext<I,U,N,A,S,T,X> apc,
                              ReturnWrapper<N> result)
                                 throws AspectException
Finishes the execution of the advice implementation.

This method is called after the advice implementation, from a non engine thread, calls AdviceController.setReady(ReturnWrapper)

An advice implementation must pay very close attention to concurrency issues since it executes in a multi-threaded environment. The BusinessWorks engine can call this method multiple times simultaneously, on the same advice instance, usually once for each job that gets executed (for the process this advice belong to). If the advice instance is not in the execution path of a job, this method is not called for that particular job. If the advice instance executes in a loop, this method may be called multiple times for the same job.

An advice implementation that mutates the input XML document (i.e. the document passed in the execute() call), must ensure that the new XML document is still valid against the XML schema that describes the incoming XML document.

An advice implementation that does not mutate the incoming XML document must return back the input XML document.

Parameters:
apc - the context associated with the job (i.e. process instance)
result - the result object passed in the AdviceController.setReady(ReturnWrapper) call
Returns:
the output XML document, the one used to invoke the next advice in the pipeline or the next activity on the track
Throws:
AspectException

cancelled

public abstract void cancelled(AspectProcessContext<I,U,N,A,S,T,X> apc)
                        throws AspectException
This method is called when the advice has not completed within the allotted time as specified in the AdviceController.setPending() call.

If this method is called, then postExecute() will not be called for the same exchange.

An advice implementation must pay very close attention to concurrency issues since it executes in a multi-threaded environment. The BusinessWorks engine can call this method multiple times simultaneously, on the same advice instance, usually once for each job that gets executed (for the process this advice belong to). If the advice instance is not in the execution path of a job, this method is not called for that particular job. If the advice instance executes in a loop, this method may be called multiple times for the same job.

Parameters:
apc - the context associated with the job (i.e. process instance)
Throws:
AspectException


Copyright @ 2010, TIBCO Softwares (Inc). All right reserved