| <!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="../../../jakarta/enterprise/concurrent/AbortedException.html" title="class in jakarta.enterprise.concurrent"><span class="typeNameLink">Prev Class</span></a></li> |
| <li><a href="../../../jakarta/enterprise/concurrent/LastExecution.html" title="interface in jakarta.enterprise.concurrent"><span class="typeNameLink">Next Class</span></a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../index.html?jakarta/enterprise/concurrent/ContextService.html" target="_top">Frames</a></li> |
| <li><a href="ContextService.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../../allclasses-noframe.html">All 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: </li> |
| <li>Nested | </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method.summary">Method</a></li> |
| </ul> |
| <ul class="subNavList"> |
| <li>Detail: </li> |
| <li>Field | </li> |
| <li>Constr | </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">jakarta.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"> |
| <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 |
| Jakarta™ 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 Jakarta EE Product Provider, such as a web |
| component or a Jakarta Enterprise Bean. |
| <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 "jakarta.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. Jakarta 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"> </span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd"> </span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd"> </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="../../../jakarta/enterprise/concurrent/ContextService.html#createContextualProxy-java.lang.Object-java.lang.Class...-">createContextualProxy</a></span>(java.lang.Object instance, |
| java.lang.Class<?>... 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="../../../jakarta/enterprise/concurrent/ContextService.html#createContextualProxy-java.lang.Object-java.util.Map-java.lang.Class...-">createContextualProxy</a></span>(java.lang.Object instance, |
| java.util.Map<java.lang.String,java.lang.String> executionProperties, |
| java.lang.Class<?>... 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><T> T</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../../jakarta/enterprise/concurrent/ContextService.html#createContextualProxy-T-java.lang.Class-">createContextualProxy</a></span>(T instance, |
| java.lang.Class<T> 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><T> T</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../../jakarta/enterprise/concurrent/ContextService.html#createContextualProxy-T-java.util.Map-java.lang.Class-">createContextualProxy</a></span>(T instance, |
| java.util.Map<java.lang.String,java.lang.String> executionProperties, |
| java.lang.Class<T> 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<java.lang.String,java.lang.String></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../../jakarta/enterprise/concurrent/ContextService.html#getExecutionProperties-java.lang.Object-">getExecutionProperties</a></span>(java.lang.Object 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><T> T createContextualProxy(T instance, |
| java.lang.Class<T> 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™ 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™ SE ExecutorService: |
| <P> |
| <pre> |
| public class MyRunnable implements Runnable { |
| public void run() { |
| System.out.println("MyRunnable.run with Jakarta EE 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"); |
| |
| 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 createContextualProxy(java.lang.Object instance, |
| java.lang.Class<?>... interfaces)</pre> |
| <div class="block">Creates a new contextual object proxy for the input object instance. |
| <p> |
| This method is similar to <code><T> T createContextualProxy(T instance, Class<T> 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("MyRunnableWork.run with Jakarta EE Context available."); |
| } |
| 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><T> T createContextualProxy(T instance, |
| java.util.Map<java.lang.String,java.lang.String> executionProperties, |
| java.lang.Class<T> 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™ 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("java:comp/env/SecurityContext"); |
| |
| // Set any custom context data through execution properties |
| Map<String, String> execProps = new HashMap<>(); |
| execProps.put("vendor_a.security.tokenexpiration", "15000"); |
| // 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, "USE_TRANSACTION_OF_EXECUTION_THREAD"); |
| |
| ProcessMessage msgProcessor = |
| ctxSvc.createContextualProxy(new MessageProcessor(), execProps, |
| ProcessMessage.class); |
| |
| 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 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 createContextualProxy(java.lang.Object instance, |
| java.util.Map<java.lang.String,java.lang.String> executionProperties, |
| java.lang.Class<?>... interfaces)</pre> |
| <div class="block">Creates a new contextual object proxy for the input object instance. |
| <p> |
| This method is similar to <code><T> T createContextualProxy(T instance, Map<String, String> executionProperties, Class<T> 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<java.lang.String,java.lang.String> getExecutionProperties(java.lang.Object 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="../../../jakarta/enterprise/concurrent/AbortedException.html" title="class in jakarta.enterprise.concurrent"><span class="typeNameLink">Prev Class</span></a></li> |
| <li><a href="../../../jakarta/enterprise/concurrent/LastExecution.html" title="interface in jakarta.enterprise.concurrent"><span class="typeNameLink">Next Class</span></a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../index.html?jakarta/enterprise/concurrent/ContextService.html" target="_top">Frames</a></li> |
| <li><a href="ContextService.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../../allclasses-noframe.html">All 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: </li> |
| <li>Nested | </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method.summary">Method</a></li> |
| </ul> |
| <ul class="subNavList"> |
| <li>Detail: </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method.detail">Method</a></li> |
| </ul> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| </body> |
| </html> |