javax.util.concurrent
Interface ContextService


public interface ContextService

The ContextService provides methods for creating contextual dynamic proxy objects.

The proxy objects follow the same rules as defined for the java.lang.reflect.Proxy class with the following additions:

Author:
Chris D. Johnson

Field Summary
static java.lang.String USE_PARENT_TRANSACTION
          A contextual object property that disables the normal transaction suspension and UserTransaction access from the proxied methods.
 
Method Summary
 java.lang.Object createContextObject(java.lang.Object instance, java.lang.Class[] interfaces)
          Creates a new contextual object proxy for the input object instance.
 java.lang.Object createContextObject(java.lang.Object instance, java.lang.Class[] interfaces, java.util.Properties contextProperties)
          Creates a new contextual object proxy for the input object instance.
 java.util.Properties getProperties(java.lang.Object contextObject)
          Gets the current properties on the context proxy instance.
 void setProperties(java.lang.Object contextObject, java.util.Properties contextProperties)
          Sets the properties on the context proxy instance.
 

Field Detail

USE_PARENT_TRANSACTION

static final java.lang.String USE_PARENT_TRANSACTION
A contextual object property that disables the normal transaction suspension and UserTransaction access from the proxied methods.

If "false" (the default if unspecified), any transaction that is currently active on the thread will be suspended and a UserTransaction (accessible in the local JNDI namespace as "java:comp/UserTransaction") will be available. When the proxied method returns the original transaction is restored.

If "true", the proxied method will run within the transaction (if any) of the current thread. A UserTransaction will only be available if the the container thread (for example, a Servlet or Bean Managed Transaction EJB).

See Also:
Constant Field Values
Method Detail

createContextObject

java.lang.Object createContextObject(java.lang.Object instance,
                                     java.lang.Class[] interfaces)
Creates a new contextual object proxy for the input object instance.

Each method invocation will have the context of the application component instance that created the context object.

The contextual object is useful when developing or using Java SE threading mechanisms spraying events to other component instances or communicating with component instances on different Java processes.

If the application component that created the proxy is started or deployed, all methods on reflected interfaces will throw a java.lang.IllegalState exception.

For example, to call a normal Runnable with the correct context using a Java™ ExecutorService:

 public class MyRunnable implements Runnable {
     public void run() {
         System.out.println("MyRunnable.run with J2EE Context available.");
     }
 }

 InitialContext ctx = new InitialContext();

 ThreadFactory threadFactory = (ThreadFactory) ctx
         .lookup("java:comp/env/concurrent/ThreadFactory");

 ContextService ctxService = (ContextService) ctx
         .lookup("java:comp/env/concurrent/ContextService");

 Object rProxy = ctxService.createContextObject(myRunnableInstance,
         new Class[] { Runnable.class });

 ExecutorService exSvc = Executors.newThreadPool(10, threadFactory);

 Future f = exSvc.submit((Runnable) rProxy);
 

Parameters:
instance - the instance of the object to proxy.
interfaces - the interfaces that the proxy should implement.
Returns:
a proxy for the input object that implements all of the specified interfaces.
Throws:
java.lang.IllegalArgumentException - if the Class does not have an interface or there is not an accessible default constructor.

createContextObject

java.lang.Object createContextObject(java.lang.Object instance,
                                     java.lang.Class[] interfaces,
                                     java.util.Properties contextProperties)
Creates a new contextual object proxy for the input object instance.

The contextual object is useful when developing or using Java SE threading mechanisms spraying events to other component instances or communicating with component instances on different Java processes.

If the application component that created the proxy is started or deployed, all methods on reflected interfaces will throw a java.lang.IllegalState exception.

This method accepts a Properties object which allows the contextual object creator to define what contexts or behaviors to capture when creating the contextual object. The specified properties will remain with the contextual object until the properties are updated or removed using the setProperties(Object, Properties) method.

For example, to call a Message Driven Bean (MDB) with the sender's context, but within the MDB's transaction:

      public class MyServlet ... {
        public void doPost() throws NamingException, JMSException {
            InitialContext ctx = new InitialContext();

            // Get the ContextService that only propagates
            // security context.
            ContextService ctxSvc = (ContextService)
                ctx.lookup("java:comp/env/SecurityContext");

            // Set any custom context data.
            Properties ctxProps = new Properties();
            ctxProps.setProperty("vendor_a.security.tokenexpiration", "15000");

            ProcessMessage msgProcessor =
                (ProcessMessage) ctxSvc.createContextObject(new MessageProcessor(),
                new Class[]{ProcessMessage.class},
                ctxProps);

            ConnectionFactory cf = (ConnectionFactory)
                 ctx.lookup("java:comp/env/MyTopicConnectionFactory");
            Destination dest = (Destination) ctx.lookup("java:comp/env/MyTopic");
            Connection con = cf.createConnection();

            Session session = con.createSession(true, Session.AUTO_ACKNOWLEDGE);
            MessageProducer producer = session.createProducer(dest);

            Message msg = session.createObjectMessage((Serializable)msgProcessor);
            producer.send(dest, msg);
            ...

        }

      public class MyMDB ... {
        public void onMessage(Message msg) {
            // Get the ProcessMessage context object from the message.
            ObjectMessage omsg = (ObjectMessage)msg;
            ProcessMessage msgProcessor = (ProcessMessage)omsg.getObject();

            // Update the context object and verify that the processMessage()
            // method runs inside the current transaction.  If we have a failure,
            // we don't want to consume the message.
            InitialContext ctx = new InitialContext();
            ContextService ctxSvc = (ContextService)
                ctx.lookup("java:comp/env/SecurityContext");
            Properties ctxProps = ctxSvc.getProperties(msgProcessor);
            ctxProps.setProperty(ContextService.USE_PARENT_TRANSACTION, "true");
            ctxSvc.setProperties(msgProcessor, ctxProps);

            // Process the message in the specified context.
            msgProcessor.processMessage(msg);
        }
      }

      public interface  ProcessMessage {
          public void processMessage(Message msg);
      }

      public class MessageProcessor implements ProcessMessage, Serializable {
          public void processMessage(Message msg) {
              // Process the message with the application container
              // context that sent the message.

          }
      }
 

Parameters:
instance - the instance of the object to proxy.
interfaces - the interfaces that the proxy should implement.
contextProperties - the properties to use when creating and running the context object.
Returns:
a proxy for the input object that implements all of the specified interfaces.
Throws:
java.lang.IllegalArgumentException - if the Class does not have an interface or there is not an accessible default constructor.
java.lang.ClassCastException - thrown if one of the keys or values in the specified Properties object are not of type String.

setProperties

void setProperties(java.lang.Object contextObject,
                   java.util.Properties contextProperties)
Sets the properties on the context proxy instance.

All property keys and values must be strings. Storing other class types may result in a java.lang.ClassCastException.

Parameters:
contextObject - the contextual proxy instance to set the properties.
contextProperties - the properties to use when running the context object. Specify an empty Properties object to erase all current properties.
Throws:
java.lang.IllegalArgumentException - thrown if the input contextObject is not a valid contextual object proxy created with the createContextObject method.
java.lang.ClassCastException - thrown if one of the keys or values in the specified Properties object are not of type String.

getProperties

java.util.Properties getProperties(java.lang.Object contextObject)
Gets the current properties on the context proxy instance.

Parameters:
contextObject - the contextual proxy instance to set the properties.
Returns:
the current context object properties
Throws:
java.lang.IllegalArgumentException - thrown if the input contextObject is not a valid contextual object proxy created with the createContextObject method.