tomee-8.0/javadoc/javax/enterprise/concurrent/ContextService.html - tomee-site-pub - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <!-- NewPage -->
 <html lang="en">
 <head>
 <title>ContextService</title>
 <link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
 </head>
 <body>
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
             parent.document.title="ContextService";
         }
     }
     catch(err) {
     }
 //-->
 var methods = {"i0":6,"i1":6,"i2":6,"i3":6,"i4":6};
 var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"]};
 var altColor = "altColor";
 var rowColor = "rowColor";
 var tableTab = "tableTab";
 var activeTableTab = "activeTableTab";
 </script>
 <noscript>
 <div>JavaScript is disabled on your browser.</div>
 </noscript>
 <!-- ========= START OF TOP NAVBAR ======= -->
 <div class="topNav"><a name="navbar.top">
 <!--   -->
 </a>
 <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
 <a name="navbar.top.firstrow">
 <!--   -->
 </a>
 <ul class="navList" title="Navigation">
 <li><a href="../../../overview-summary.html">Overview</a></li>
 <li><a href="package-summary.html">Package</a></li>
 <li class="navBarCell1Rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
 <li><a href="../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../index-all.html">Index</a></li>
 <li><a href="../../../help-doc.html">Help</a></li>
 </ul>
 </div>
 <div class="subNav">
 <ul class="navList">
 <li><a href="../../../javax/enterprise/concurrent/AbortedException.html" title="class in javax.enterprise.concurrent"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
 <li><a href="../../../javax/enterprise/concurrent/LastExecution.html" title="interface in javax.enterprise.concurrent"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
 </ul>
 <ul class="navList">
 <li><a href="../../../index.html?javax/enterprise/concurrent/ContextService.html" target="_top">Frames</a></li>
 <li><a href="ContextService.html" target="_top">No&nbsp;Frames</a></li>
 </ul>
 <ul class="navList" id="allclasses_navbar_top">
 <li><a href="../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
 </ul>
 <div>
 <script type="text/javascript"><!--
   allClassesLink = document.getElementById("allclasses_navbar_top");
   if(window==top) {
     allClassesLink.style.display = "block";
   }
   else {
     allClassesLink.style.display = "none";
   }
   //-->
 </script>
 </div>
 <div>
 <ul class="subNavList">
 <li>Summary:&nbsp;</li>
 <li>Nested&nbsp;|&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.summary">Method</a></li>
 </ul>
 <ul class="subNavList">
 <li>Detail:&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.detail">Method</a></li>
 </ul>
 </div>
 <a name="skip.navbar.top">
 <!--   -->
 </a></div>
 <!-- ========= END OF TOP NAVBAR ========= -->
 <!-- ======== START OF CLASS DATA ======== -->
 <div class="header">
 <div class="subTitle">javax.enterprise.concurrent</div>
 <h2 title="Interface ContextService" class="title">Interface ContextService</h2>
 </div>
 <div class="contentContainer">
 <div class="description">
 <ul class="blockList">
 <li class="blockList">
 <dl>
 <dt>All Known Implementing Classes:</dt>
 <dd><a href="../../../org/apache/openejb/threads/impl/ContextServiceImpl.html" title="class in org.apache.openejb.threads.impl">ContextServiceImpl</a></dd>
 </dl>
 <hr>
 <br>
 <pre>public interface <span class="typeNameLabel">ContextService</span></pre>
 <div class="block">The ContextService provides methods for creating dynamic proxy objects
  (as defined by <code>java.lang.reflect.Proxy</code>) with
  the addition of context typically associated with applications executing in a
  Java&trade; EE environment.
  Examples of such context are classloading, namespace, security, etc.
  <p>

  The proxy objects follow the same rules as defined for the
  <code>java.lang.reflect.Proxy</code> class with the following additions:
  <ul>
  <li>The proxy instance will retain the context of the creator's
      thread.
  <li>The proxy instance will implement all of the interfaces specified on the
      <code>createContextualProxy</code> methods.
  <li>The object to have a proxy instance created for should not be a
      component managed by the Java&trade; EE Product Provider, such as a web
      component or an EJB.
  <li>All interface method invocations on a proxy instance run in the
      creator's context with the exception of <code>hashCode</code>,
      <code>equals</code>, <code>toString</code> and all other methods declared in
      <code>Object</code>.
  <li>The proxy instance must implement <code>Serializable</code>.
  <li>The proxied object instance must implement
      <code>Serializable</code> if the proxy instance is serialized.
  <li>Execution properties can be stored with the proxy instance. Custom
      property keys must not begin with "javax.enterprise.concurrent.".
  <li>Execution properties are to be used for controlling how various contextual
      information is retrieved and applied to the thread. Although application
      components can store arbitrary property keys and values, it is not
      recommended. Java&trade; EE product providers may impose limits to the
      size of the keys and values.
  </ul>
  <P></div>
 <dl>
 <dt><span class="simpleTagLabel">Since:</span></dt>
 <dd>1.0</dd>
 </dl>
 </li>
 </ul>
 </div>
 <div class="summary">
 <ul class="blockList">
 <li class="blockList">
 <!-- ========== METHOD SUMMARY =========== -->
 <ul class="blockList">
 <li class="blockList"><a name="method.summary">
 <!--   -->
 </a>
 <h3>Method Summary</h3>
 <table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
 <caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
 <tr>
 <th class="colFirst" scope="col">Modifier and Type</th>
 <th class="colLast" scope="col">Method and Description</th>
 </tr>
 <tr id="i0" class="altColor">
 <td class="colFirst"><code>java.lang.Object</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../javax/enterprise/concurrent/ContextService.html#createContextualProxy-java.lang.Object-java.lang.Class...-">createContextualProxy</a></span>(java.lang.Object&nbsp;instance,
                      java.lang.Class&lt;?&gt;...&nbsp;interfaces)</code>
 <div class="block">Creates a new contextual object proxy for the input object instance.</div>
 </td>
 </tr>
 <tr id="i1" class="rowColor">
 <td class="colFirst"><code>java.lang.Object</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../javax/enterprise/concurrent/ContextService.html#createContextualProxy-java.lang.Object-java.util.Map-java.lang.Class...-">createContextualProxy</a></span>(java.lang.Object&nbsp;instance,
                      java.util.Map&lt;java.lang.String,java.lang.String&gt;&nbsp;executionProperties,
                      java.lang.Class&lt;?&gt;...&nbsp;interfaces)</code>
 <div class="block">Creates a new contextual object proxy for the input object instance.</div>
 </td>
 </tr>
 <tr id="i2" class="altColor">
 <td class="colFirst"><code>&lt;T&gt;&nbsp;T</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../javax/enterprise/concurrent/ContextService.html#createContextualProxy-T-java.lang.Class-">createContextualProxy</a></span>(T&nbsp;instance,
                      java.lang.Class&lt;T&gt;&nbsp;intf)</code>
 <div class="block">Creates a new contextual object proxy for the input object instance.</div>
 </td>
 </tr>
 <tr id="i3" class="rowColor">
 <td class="colFirst"><code>&lt;T&gt;&nbsp;T</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../javax/enterprise/concurrent/ContextService.html#createContextualProxy-T-java.util.Map-java.lang.Class-">createContextualProxy</a></span>(T&nbsp;instance,
                      java.util.Map&lt;java.lang.String,java.lang.String&gt;&nbsp;executionProperties,
                      java.lang.Class&lt;T&gt;&nbsp;intf)</code>
 <div class="block">Creates a new contextual object proxy for the input object instance.</div>
 </td>
 </tr>
 <tr id="i4" class="altColor">
 <td class="colFirst"><code>java.util.Map&lt;java.lang.String,java.lang.String&gt;</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../javax/enterprise/concurrent/ContextService.html#getExecutionProperties-java.lang.Object-">getExecutionProperties</a></span>(java.lang.Object&nbsp;contextualProxy)</code>
 <div class="block">Gets the current execution properties on the context proxy instance.</div>
 </td>
 </tr>
 </table>
 </li>
 </ul>
 </li>
 </ul>
 </div>
 <div class="details">
 <ul class="blockList">
 <li class="blockList">
 <!-- ============ METHOD DETAIL ========== -->
 <ul class="blockList">
 <li class="blockList"><a name="method.detail">
 <!--   -->
 </a>
 <h3>Method Detail</h3>
 <a name="createContextualProxy-java.lang.Object-java.lang.Class-">
 <!--   -->
 </a><a name="createContextualProxy-T-java.lang.Class-">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>createContextualProxy</h4>
 <pre>&lt;T&gt;&nbsp;T&nbsp;createContextualProxy(T&nbsp;instance,
                             java.lang.Class&lt;T&gt;&nbsp;intf)</pre>
 <div class="block">Creates a new contextual object proxy for the input object instance.
  <p>
  Each method invocation will have the context of the application component
  instance that created the contextual object proxy.
  <p>
  The contextual object is useful when developing or using Java&trade; SE
  threading mechanisms propagating events to other component instances.
  <p>
  If the application component that created the proxy is not started or
  deployed, all methods on reflected interfaces may throw an
  <code>IllegalStateException</code>.
   <p>
  For example, to execute a Runnable which is contextualized with the
  creator's context using a Java&trade; SE ExecutorService:
  <P>
  <pre>
   public class MyRunnable implements Runnable {
       public void run() {
           System.out.println(&quot;MyRunnable.run with Java EE Context available.&quot;);
       }
   }

   InitialContext ctx = new InitialContext();
   ThreadFactory threadFactory = (ThreadFactory) ctx
            .lookup(&quot;java:comp/env/concurrent/ThreadFactory&quot;);

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

   MyRunnable myRunnableInstance = ...;

   Runnable rProxy = ctxService.createContextualProxy(myRunnableInstance, Runnable.class);

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

   Future f = exSvc.submit(rProxy);
  </pre>
  <P></div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>instance</code> - the instance of the object to proxy.</dd>
 <dd><code>intf</code> - the interface that the proxy should implement.</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>a proxy for the input object that implements the specified interface.</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code>java.lang.IllegalArgumentException</code> - - if the <code>intf</code> argument
  is null or the instance does not implement the specified
  interface.</dd>
 </dl>
 </li>
 </ul>
 <a name="createContextualProxy-java.lang.Object-java.lang.Class...-">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>createContextualProxy</h4>
 <pre>java.lang.Object&nbsp;createContextualProxy(java.lang.Object&nbsp;instance,
                                        java.lang.Class&lt;?&gt;...&nbsp;interfaces)</pre>
 <div class="block">Creates a new contextual object proxy for the input object instance.
  <p>
  This method is similar to <code>&lt;T&gt; T createContextualProxy(T instance, Class&lt;T&gt; intf)</code>
  except that this method can be used if the proxy has to support multiple
  interfaces.
   <p>
  Example:
  <P>
  <pre>
   public class MyRunnableWork implements Runnable, SomeWorkInterface {
       public void run() {
           System.out.println(&quot;MyRunnableWork.run with Java EE Context available.&quot;);
       }
       public void someWorkInterfaceMethod() {
           ...
       }
   }

   ThreadFactory threadFactory = ...;

   ContextService ctxService = ...;

   MyRunnableWork myRunnableWorkInstance = ...;

   Object proxy = ctxService.createContextualProxy(myRunnableWorkInstance,
                                    Runnable.class, SomeWorkInterface.class);

   // call SomeWorkInterface method on the proxy
   ((SomeWorkInterface) proxy).someWorkInterfaceMethod();

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

   // submit the proxy as a Runnable to the ExecutorService
   Future f = exSvc.submit( (Runnable)proxy);
  </pre>
  <P></div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>instance</code> - the instance of the object to proxy.</dd>
 <dd><code>interfaces</code> - the interfaces that the proxy should implement.</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>a proxy for the input object that implements all of the specified
          interfaces.</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code>java.lang.IllegalArgumentException</code> - - if the <code>interfaces</code>
  argument is null or the instance does not implement
  all the specified interfaces.</dd>
 </dl>
 </li>
 </ul>
 <a name="createContextualProxy-java.lang.Object-java.util.Map-java.lang.Class-">
 <!--   -->
 </a><a name="createContextualProxy-T-java.util.Map-java.lang.Class-">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>createContextualProxy</h4>
 <pre>&lt;T&gt;&nbsp;T&nbsp;createContextualProxy(T&nbsp;instance,
                             java.util.Map&lt;java.lang.String,java.lang.String&gt;&nbsp;executionProperties,
                             java.lang.Class&lt;T&gt;&nbsp;intf)</pre>
 <div class="block">Creates a new contextual object proxy for the input object instance.
  <p>
  The contextual object is useful when developing or using Java&trade; SE
  threading mechanisms propagating events to other component instances.
  <p>
  If the application component that created the proxy is not started or
  deployed, all methods on reflected interfaces may throw an
  <code>IllegalStateException</code>.
  <p>
  This method accepts a <code>Map</code> 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.
  <p>

  For example, to call a Message Driven Bean (MDB) with the sender's
  context, but within the MDB's transaction:
  <P>
  <pre>
  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(&quot;java:comp/env/SecurityContext&quot;);

         // Set any custom context data through execution properties
         Map&lt;String, String&gt; execProps = new HashMap&lt;&gt;();
         execProps.put(&quot;vendor_a.security.tokenexpiration&quot;, &quot;15000&quot;);
         // Specify that contextual object should run inside the current
         // transaction.  If we have a failure, we don't want to consume
         // the message.
         execProps.put(ManagedTask.TRANSACTION, &quot;USE_TRANSACTION_OF_EXECUTION_THREAD&quot;);

         ProcessMessage msgProcessor =
             ctxSvc.createContextualProxy(new MessageProcessor(), execProps,
             ProcessMessage.class);

         ConnectionFactory cf = (ConnectionFactory)
              ctx.lookup(&quot;java:comp/env/MyTopicConnectionFactory&quot;);
         Destination dest = (Destination) ctx.lookup(&quot;java:comp/env/MyTopic&quot;);
         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 contextual object from the message.
         ObjectMessage omsg = (ObjectMessage)msg;
         ProcessMessage msgProcessor = (ProcessMessage)omsg.getObject();

         // 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.

       }
   }
 </pre>
 <P></div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>instance</code> - the instance of the object to proxy.</dd>
 <dd><code>executionProperties</code> - the properties to use when creating and running the context
                           object.</dd>
 <dd><code>intf</code> - the interface that the proxy should implement.</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>a proxy for the input object that implements the specified interface.</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code>java.lang.IllegalArgumentException</code> - - if the <code>intf</code> argument
  null or the instance does not implement the specified interface.</dd>
 </dl>
 </li>
 </ul>
 <a name="createContextualProxy-java.lang.Object-java.util.Map-java.lang.Class...-">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>createContextualProxy</h4>
 <pre>java.lang.Object&nbsp;createContextualProxy(java.lang.Object&nbsp;instance,
                                        java.util.Map&lt;java.lang.String,java.lang.String&gt;&nbsp;executionProperties,
                                        java.lang.Class&lt;?&gt;...&nbsp;interfaces)</pre>
 <div class="block">Creates a new contextual object proxy for the input object instance.
  <p>
  This method is similar to <code>&lt;T&gt; T createContextualProxy(T instance, Map&lt;String, String&gt; executionProperties, Class&lt;T&gt; intf)</code>
  except that this method can be used if the proxy has to support multiple
  interfaces.</div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>instance</code> - the instance of the object to proxy.</dd>
 <dd><code>executionProperties</code> - the properties to use when creating and running the context
                           object.</dd>
 <dd><code>interfaces</code> - the interfaces that the proxy should implement.</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>a proxy for the input object that implements all of the specified
          interfaces.</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code>java.lang.IllegalArgumentException</code> - - if the <code>interfaces</code>
  argument is null or the instance does not implement all the specified
  interfaces.</dd>
 </dl>
 </li>
 </ul>
 <a name="getExecutionProperties-java.lang.Object-">
 <!--   -->
 </a>
 <ul class="blockListLast">
 <li class="blockList">
 <h4>getExecutionProperties</h4>
 <pre>java.util.Map&lt;java.lang.String,java.lang.String&gt;&nbsp;getExecutionProperties(java.lang.Object&nbsp;contextualProxy)</pre>
 <div class="block">Gets the current execution properties on the context proxy instance.</div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>contextualProxy</code> - the contextual proxy instance to retrieve the execution properties.</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>A copy of the current contextual object execution properties, or null if
          the contextualProxy is created without specifying any execution properties.</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code>java.lang.IllegalArgumentException</code> - thrown if the input contextualProxy is not a valid
                                             contextual object proxy created with the
                                             <code>createContextualProxy</code> method.</dd>
 </dl>
 </li>
 </ul>
 </li>
 </ul>
 </li>
 </ul>
 </div>
 </div>
 <!-- ========= END OF CLASS DATA ========= -->
 <!-- ======= START OF BOTTOM NAVBAR ====== -->
 <div class="bottomNav"><a name="navbar.bottom">
 <!--   -->
 </a>
 <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
 <a name="navbar.bottom.firstrow">
 <!--   -->
 </a>
 <ul class="navList" title="Navigation">
 <li><a href="../../../overview-summary.html">Overview</a></li>
 <li><a href="package-summary.html">Package</a></li>
 <li class="navBarCell1Rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
 <li><a href="../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../index-all.html">Index</a></li>
 <li><a href="../../../help-doc.html">Help</a></li>
 </ul>
 </div>
 <div class="subNav">
 <ul class="navList">
 <li><a href="../../../javax/enterprise/concurrent/AbortedException.html" title="class in javax.enterprise.concurrent"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
 <li><a href="../../../javax/enterprise/concurrent/LastExecution.html" title="interface in javax.enterprise.concurrent"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
 </ul>
 <ul class="navList">
 <li><a href="../../../index.html?javax/enterprise/concurrent/ContextService.html" target="_top">Frames</a></li>
 <li><a href="ContextService.html" target="_top">No&nbsp;Frames</a></li>
 </ul>
 <ul class="navList" id="allclasses_navbar_bottom">
 <li><a href="../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
 </ul>
 <div>
 <script type="text/javascript"><!--
   allClassesLink = document.getElementById("allclasses_navbar_bottom");
   if(window==top) {
     allClassesLink.style.display = "block";
   }
   else {
     allClassesLink.style.display = "none";
   }
   //-->
 </script>
 </div>
 <div>
 <ul class="subNavList">
 <li>Summary:&nbsp;</li>
 <li>Nested&nbsp;|&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.summary">Method</a></li>
 </ul>
 <ul class="subNavList">
 <li>Detail:&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.detail">Method</a></li>
 </ul>
 </div>
 <a name="skip.navbar.bottom">
 <!--   -->
 </a></div>
 <!-- ======== END OF BOTTOM NAVBAR ======= -->
 </body>
 </html>