4 Programming Tasks

To support the generic work context, the required-work-context element is added to the ra.xml file schema to represent a WorkContext class that is required by the resource adapter for WebLogic Server to support. For each WorkContext class that is required, an individual required-work-context element is specified.

Note that the @Connector metadata annotation can be used in a resource adapter source file to specify this deployment descriptor information. For more information, see Section 18.4, @Connector, in JSR 322: Java EE Connector Architecture 1.6.

As an alternative to using a WebLogic Server startup class, you can program a resource adapter with a minimal resource adapter class that implements javax.resource.ResourceAdapter, which defines a start() and stop() method.

When the resource adapter is deployed, the start() method is invoked. When it is undeployed, the stop() method is invoked. Any work that the resource adapter initiates can be performed in the start() method as with a WebLogic Server startup class.

Example 4-1 shows a resource adapter having a minimum resource adapter class. It is the absolute minimum resource adapter that you can develop (other than removing the println statements). In this example, the only work performed by the start() method is to print a message to stdout (standard out).

import javax.resource.spi.ResourceAdapter;
import javax.resource.spi.endpoint.MessageEndpointFactory;
import javax.resource.spi.ActivationSpec;
import javax.resource.ResourceException;
import javax.transaction.xa.XAResource;
import javax.resource.NotSupportedException;
import javax.resource.spi.BootstrapContext;
/**
* This resource adapter is the absolute minimal resource adapter that anyone can build (other than removing the println's.)
*/
public class ResourceAdapterImpl implements ResourceAdapter
{
   public void start( BootstrapContext bsCtx )
   {   
      System.out.println( "ResourceAdapterImpl started" );
   }
   public void stop()
   {
      System.out.println( "ResourceAdapterImpl stopped" );
   }
   public void endpointActivation(MessageEndpointFactory messageendpointfactory, ActivationSpec activationspec)
      throws ResourceException
   {
      throw new NotSupportedException();
   }
   public void endpointDeactivation(MessageEndpointFactory messageendpointfactory, ActivationSpec activationspec)
   {
   }
   public XAResource[] getXAResources(ActivationSpec aactivationspec[])
      throws ResourceException
   {
      throw new NotSupportedException();
   }
}

Because resource adapters have access to the Work Manager through the BootstrapContext in the start() method, they should submit Work instances instead of using direct thread management. This enables WebLogic Server to manage threads effectively through its self-tuning Work Manager.

Once a Work instance is submitted for execution, the start() method should return promptly so as not to interfere with the full deployment of the resource adapter. Thus, a scheduleWork() or startWork() method should be invoked on the Work Manager rather than the doWork() method.

Example 4-2 shows resource adapter that submits work instances to the Work Manager. The resource adapter starts some work in the start() method, thus serving as a Java EE-compliant startup class.

import javax.resource.NotSupportedException;
import javax.resource.ResourceException;
import javax.resource.spi.ActivationSpec;
import javax.resource.spi.BootstrapContext;
import javax.resource.spi.ResourceAdapter;
import javax.resource.spi.endpoint.MessageEndpointFactory;
import javax.resource.spi.work.Work;
import javax.resource.spi.work.WorkException;
import javax.resource.spi.work.WorkManager;
import javax.transaction.xa.XAResource;
/**
* This Resource Adapter starts some work in the start() method, 
* thus serving as a Java EE compliant "startup class" 
*/
public class ResourceAdapterWorker implements ResourceAdapter
{
   private WorkManager wm;
   private MyWork someWork;
   public void start( BootstrapContext bsCtx )
   {
      System.out.println( "ResourceAdapterWorker started" );
      wm = bsCtx.getWorkManager();
      try
      {
         someWork = new MyWork();
         wm.startWork( someWork );
      }
      catch (WorkException ex)
      {
         System.err.println( "Unable to start work: " + ex );
      }
   }
   public void stop()
   {
   // stop work that was started in the start() method
   someWork.release();
      System.out.println( "ResourceAdapterImpl stopped" );
   }
   public void endpointActivation(MessageEndpointFactory messageendpointfactory,
             ActivationSpec activationspec)
      throws ResourceException
   {
      throw new NotSupportedException();
   }
   public void endpointDeactivation(MessageEndpointFactory
             messageendpointfactory, ActivationSpec activationspec)
   {
   }
   public XAResource[] getXAResources(ActivationSpec activationspec[]) 
      throws ResourceException
   {
      throw new NotSupportedException();
   }
   // Work class
   private class MyWork implements Work
   {
      private boolean isRunning;
      public void run()
      {
         isRunning = true;
         while (isRunning)
         {
         // do a unit of work (e.g. listen on a socket, wait for an inbound msg, 
         // check the status of something)
         System.out.println( "Doing some work" );
         // perhaps wait some amount of time or for some event
         try
         {
            Thread.sleep( 60000 ); // wait a minute
         }
         catch (InterruptedException ex)
         {}
      }
   }
   public void release()
   {
         // signal the run() loop to stop
         isRunning = false;
      }
   }
}

There are instances in which the submission of a Work instance by a resource adapter can experience a transient failure. For example, JSR 322: Java EE Connector Architecture 1.6 describes how you can use the optional startTimeout parameter in a WorkManager interface implementation to specify a time interval within which the execution of the Work instance must start. If a Work submission times out, a work submission failure occurs and a WorkRejectedException is generated.

JSR 322: Java EE Connector Architecture 1.6 states that the application server throws out a RetryableWorkRejectedException when it determines that the failure of a Work submission may due to transient causes. When it receives a RetryableWorkRejectedException, the resource adapter may retry submitting the Work instance. WebLogic Server supports the RetryableWorkRejectedException in the following transient failure situations:

• The Work instance was submitted to a suspended Work Manager.

• The Work submission has timed out.

In the WebLogic Server Diagnostic Framework, a thread may have an associated diagnostic context. A request on the thread carries its diagnostic context throughout its lifetime, as it proceeds along its path of execution. The ExtendedBootstrapContext allows the resource adapter developer to set a diagnostic context payload consisting of a String that can be used, for example, to trace the execution of a request from an EIS all the way to a message endpoint.

This capability can serve a variety of diagnostic purposes. For example, you can set the String to the client ID or session ID on an inbound message from an EIS. During message dispatch, various diagnostics can be gathered to show the request flow through the system. As you develop your resource adapter classes, you can make use of the setDiagnosticContextID() and getDiagnosticContextID() methods for this purpose.

Note the following regarding the contents of the diagnostic context payload:

• The payload can be viewed by other code in the same execution context, and it can also flow out of the process along with the Work instance. Therefore, you should ensure that the application does not include any sensitive data in the payload that, for example, could be returned by the getDiagnosticContextID() method.

• The payload can be overwritten by other code in the same execution context. Therefore, the application must never have a dependency on a specific context ID being available in the payload. In addition, the application should also verify that the context ID in the payload matches what is expected before using it.

For more information about the diagnostic context, see Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

The WebLogic Server diagnostic framework also provides the ability to dye a request. The ExtendedBootstrapContext allows you to set and retrieve four dye bits on the current thread for whatever diagnostic purpose the resource adapter developer chooses. For example, you might set priority of a request using the dye bits. For more information about request dyeing, see Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

You can use the ExtendedBootstrapContext.complete() method as a callback to the connector container. For detailed information on this feature, see Redeploying Applications in a Production Environment in Deploying Applications to Oracle WebLogic Server.

In its support of JSR 303: Bean Validation, WebLogic Server extends Java EE 6 by providing a module-level bean validation configuration file, which WebLogic Server uses to validate the resource adapter module.

There are circumstances in which you might want a resource adapter to perform validation on other bean instances that are managed by that resource adapter. Because a resource adapter does not have its own JNDI namespace, it cannot look up its own Validator and ValidatorFactory instances using JNDI. Instead, the resource adapter can inject those beans using CDI, or use the following methods on the ExtendedBootstrapContext interface to obtain instances of those beans:

• getValidator()

• getValidatorFactory()

To support JSR 299: Contexts and Dependency Injection for the Java EE Platform (CDI), WebLogic Server implements the getBeanManager method on the ExtendedBootstrapContext interface. A resource adapter can invoke this method to obtain its own BeanManager instance and perform CDI-style injection of managed beans inside the resource adapter.

For more information about using the getBeanManager method on the ExtendedBootstrapContext interface to use CDI, see Using Contexts and Dependency Injection in Resource Adapters.