Wed, 26 Feb 2014 14:43:56 -0800
Added tag jdk8u20-b03 for changeset 9059a1c85704
duke@1 | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
duke@1 | 2 | <html> |
duke@1 | 3 | <head> |
duke@1 | 4 | <!-- |
duke@1 | 5 | |
ohair@158 | 6 | Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. |
duke@1 | 7 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
duke@1 | 8 | |
duke@1 | 9 | This code is free software; you can redistribute it and/or modify it |
duke@1 | 10 | under the terms of the GNU General Public License version 2 only, as |
ohair@158 | 11 | published by the Free Software Foundation. Oracle designates this |
duke@1 | 12 | particular file as subject to the "Classpath" exception as provided |
ohair@158 | 13 | by Oracle in the LICENSE file that accompanied this code. |
duke@1 | 14 | |
duke@1 | 15 | This code is distributed in the hope that it will be useful, but WITHOUT |
duke@1 | 16 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
duke@1 | 17 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
duke@1 | 18 | version 2 for more details (a copy is included in the LICENSE file that |
duke@1 | 19 | accompanied this code). |
duke@1 | 20 | |
duke@1 | 21 | You should have received a copy of the GNU General Public License version |
duke@1 | 22 | 2 along with this work; if not, write to the Free Software Foundation, |
duke@1 | 23 | Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
duke@1 | 24 | |
ohair@158 | 25 | Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
ohair@158 | 26 | or visit www.oracle.com if you need additional information or have any |
ohair@158 | 27 | questions. |
duke@1 | 28 | |
duke@1 | 29 | |
duke@1 | 30 | --> |
duke@1 | 31 | |
duke@1 | 32 | </head> |
duke@1 | 33 | <body bgcolor="white"> |
duke@1 | 34 | Provides classes and interfaces for making the server side of your applications |
duke@1 | 35 | portable across multivendor ORBs. |
duke@1 | 36 | |
duke@1 | 37 | <P>In Java, Portable Object Adaptor (POA)-based Dynamic Skeleton Interface (DSI) |
duke@1 | 38 | servants inherit from the standard <TT>DynamicImplementation</TT> class, which |
duke@1 | 39 | inherits from the <TT>Servant</TT> class. The native <TT>Servant</TT> type is |
duke@1 | 40 | defined by the <TT>PortableServer</TT> module for the POA. In Java, the |
duke@1 | 41 | <TT>Servant</TT> type is mapped to the Java |
duke@1 | 42 | <TT>org.omg.PortableServer.Servant</TT> class. |
duke@1 | 43 | It serves as the base class for all POA servant |
duke@1 | 44 | implementations and provides a number of methods that may |
duke@1 | 45 | be invoked by the application programmer, as well as methods |
duke@1 | 46 | which are invoked by the POA itself and may be overridden by |
duke@1 | 47 | the user to control aspects of servant behavior. |
duke@1 | 48 | |
duke@1 | 49 | <H2>Package Specification</H2> |
duke@1 | 50 | |
duke@1 | 51 | <P>For a precise list of supported sections of official OMG specifications with which |
duke@1 | 52 | the Java[tm] Platform, Standard Edition 6 complies, see <A |
duke@1 | 53 | HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA |
duke@1 | 54 | support in Java[tm] SE 6</A>. |
duke@1 | 55 | <p> |
duke@1 | 56 | |
duke@1 | 57 | <H2>POA-related Interfaces</H2> |
duke@1 | 58 | |
duke@1 | 59 | <P>The <TT>PortableServer</TT> module defines the following POA-related interfaces: |
duke@1 | 60 | <P> |
duke@1 | 61 | <UL> |
duke@1 | 62 | <LI><TT>POA</TT> |
duke@1 | 63 | <LI><TT>POAManager</TT> |
duke@1 | 64 | <LI><TT>ServantManager</TT> |
duke@1 | 65 | <LI><TT>ServantActivator</TT> |
duke@1 | 66 | <LI><TT>ServantLocator</TT> |
duke@1 | 67 | <LI><TT>AdapterActivator</TT> |
duke@1 | 68 | <LI><TT>ThreadPolicy</TT> |
duke@1 | 69 | <LI><TT>LifespanPolicy</TT> |
duke@1 | 70 | <LI><TT>IdUniquenessPolicy</TT> |
duke@1 | 71 | <LI><TT>IdAssignmentPolicy</TT> |
duke@1 | 72 | <LI><TT>ImplicitActivationPolicy</TT> |
duke@1 | 73 | <LI><TT>ServantRetentionPolicy</TT> |
duke@1 | 74 | <LI><TT>RequestProcessingPolicy</TT> |
duke@1 | 75 | <LI><TT>Current</TT> |
duke@1 | 76 | </UL> |
duke@1 | 77 | |
duke@1 | 78 | <P>In addition, the POA defines the <TT>Servant</TT> native type. |
duke@1 | 79 | |
duke@1 | 80 | <H3>Operations classes</H3> |
duke@1 | 81 | |
duke@1 | 82 | <P>Each of the interfaces listed above has an associated <code>Operations</code> interface. The <code>Operations</code> interface is generated by the <code>idlj</code> compiler and contains the method signatures for methods defined in its associated interface. The <code>Operations</code> interface can be accessed by both the client and the server, while its associated interface can only be called by the client. |
duke@1 | 83 | |
duke@1 | 84 | <H3>Value Classes</H3> |
duke@1 | 85 | |
duke@1 | 86 | Classes ending in the suffix <code>PolicyValue</code> provide the values used for the <code>create_POA</code> call, which sets the policy for the POA. See the <a href="#sampleserver">sample code</a> below for a demonstration. <code>PolicyValue</code> files include the following: |
duke@1 | 87 | <P> |
duke@1 | 88 | <UL> |
duke@1 | 89 | <LI><code>IdAssignmentPolicyValue</code> |
duke@1 | 90 | <LI><code>IdUniquenessPolicyValue</code> |
duke@1 | 91 | <LI><code>ImplicitActivationPolicyValue</code> |
duke@1 | 92 | <LI><code>LifespanPolicyValue</code> |
duke@1 | 93 | <LI><code>RequestProcessingPolicyValue</code> |
duke@1 | 94 | <LI><code>ServantRetentionPolicyValue</code> |
duke@1 | 95 | <LI><code>ThreadPolicyValue</code> |
duke@1 | 96 | </UL> |
duke@1 | 97 | |
duke@1 | 98 | <H3>Helper Classes</H3> |
duke@1 | 99 | |
duke@1 | 100 | <P>Helper classes, which are generated for all user-defined types in an OMG IDL |
duke@1 | 101 | interface, supply static methods needed to manipulate those types. There is only one method in a helper class that an application programmer uses: the <code>narrow</code> method. Only Java interfaces mapped from IDL interfaces will have a helper class that includes a <code>narrow</code> method, so in the <code>PortableServer</code> package, only the following classes have a <code>narrow</code> method: |
duke@1 | 102 | <P> |
duke@1 | 103 | <UL> |
duke@1 | 104 | <LI><code>ForwardRequestHelper</code> |
duke@1 | 105 | <LI><code>ServantActivatorHelper</code> |
duke@1 | 106 | <LI><code>ServantLocatorHelper</code> |
duke@1 | 107 | </UL> |
duke@1 | 108 | |
duke@1 | 109 | <H3>POA Classes</H3> |
duke@1 | 110 | |
duke@1 | 111 | <P>POA classes are used to implement the <code>ServantActivator</code> or <code>ServantLocator</code>. |
duke@1 | 112 | |
duke@1 | 113 | <H3>Exceptions</H3> |
duke@1 | 114 | |
duke@1 | 115 | <P>The <code>ForwardRequest</code> exception indicates to the ORB |
duke@1 | 116 | that it is responsible for delivering the current request and subsequent <code>ForwardRequest</code> requests to the object denoted in the |
duke@1 | 117 | <code>forward_reference</code> member of the exception. |
duke@1 | 118 | |
duke@1 | 119 | <H3>Interfaces Implemented by the Application Programmer</H3> |
duke@1 | 120 | |
duke@1 | 121 | <P>Most of what <code>PortableServer</code> does is transparent to the user. The result is that programmers will use only a few of the interfaces mentioned above. The remaining interfaces will be provided by the ORB implementation. The interfaces of interest to application programmers are the following: |
duke@1 | 122 | <P> |
duke@1 | 123 | <ul> |
duke@1 | 124 | <LI><code>AdapterActivator</code> |
duke@1 | 125 | <P>Adapter activators are associated with POAs. An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when <code>find_POA</code> is called with an activate parameter value of <code>TRUE</code>. An application server that creates all its needed POAs at the beginning of execution does not need to use or provide an adapter activator; it is necessary only for the case in which POAs need to be created during request processing. |
duke@1 | 126 | <P> |
duke@1 | 127 | <LI><code>ServantLocator</code> |
duke@1 | 128 | <P>When the POA has the <code>NON_RETAIN</code> policy, it uses servant managers that are <code>ServantLocator</code>s. |
duke@1 | 129 | <P> |
duke@1 | 130 | <LI><code>ServantActivator</code> |
duke@1 | 131 | <P>When the POA has the <code>RETAIN</code> policy, it uses servant managers that are <code>ServantActivator</code>s. |
duke@1 | 132 | </ul> |
duke@1 | 133 | |
duke@1 | 134 | |
duke@1 | 135 | <H2>Package <TT>org.omg.PortableServer.ServantLocatorPackage</TT></H2> |
duke@1 | 136 | |
duke@1 | 137 | <P>This package supplies a <TT>CookieHolder</TT> class for passing |
duke@1 | 138 | the <TT>Cookie</TT> type as an <code>out</code> parameter. The <code>CookieHolder</code> class |
duke@1 | 139 | follows exactly the same pattern as the other holder classes for basic types. |
duke@1 | 140 | |
duke@1 | 141 | <H2>Related Documentation</H2> |
duke@1 | 142 | |
duke@1 | 143 | <P>For an overview of Java IDL, please see: |
duke@1 | 144 | <P> |
duke@1 | 145 | <LI><A HREF="../../../../technotes/guides/idl/index.html">Java IDL home page</A>. |
duke@1 | 146 | |
duke@1 | 147 | <H2>Example Code</H2> |
duke@1 | 148 | <a name="sampleserver"></a> |
duke@1 | 149 | <H3>Example Server Code</H3> |
duke@1 | 150 | <P> |
duke@1 | 151 | <PRE> |
duke@1 | 152 | import javax.naming.InitialContext; |
duke@1 | 153 | import javax.naming.Context; |
duke@1 | 154 | import javax.rmi.PortableRemoteObject ; |
duke@1 | 155 | import com.sun.corba.se.impl.poa.POAORB; |
duke@1 | 156 | import org.omg.PortableServer.*; |
duke@1 | 157 | import java.util.*; |
duke@1 | 158 | import org.omg.CORBA.*; |
duke@1 | 159 | import javax.rmi.CORBA.Stub; |
duke@1 | 160 | import javax.rmi.CORBA.Util; |
duke@1 | 161 | |
duke@1 | 162 | |
duke@1 | 163 | |
duke@1 | 164 | public class HelloServer { |
duke@1 | 165 | public HelloServer(String[] args) { |
duke@1 | 166 | try { |
duke@1 | 167 | Properties p = System.getProperties(); |
duke@1 | 168 | // p.put("org.omg.CORBA.ORBClass", "com.sun.corba.ee.internal.POA.POAORB"); |
duke@1 | 169 | ORB orb = ORB.init( args, p ); |
duke@1 | 170 | |
duke@1 | 171 | POA rootPOA = (POA)orb.resolve_initial_references("RootPOA"); |
duke@1 | 172 | <strong> |
duke@1 | 173 | Policy[] tpolicy = new Policy[3]; |
duke@1 | 174 | tpolicy[0] = rootPOA.create_lifespan_policy( |
duke@1 | 175 | LifespanPolicyValue.TRANSIENT ); |
duke@1 | 176 | tpolicy[1] = rootPOA.create_request_processing_policy( |
duke@1 | 177 | RequestProcessingPolicyValue.USE_ACTIVE_OBJECT_MAP_ONLY ); |
duke@1 | 178 | tpolicy[2] = rootPOA.create_servant_retention_policy( |
duke@1 | 179 | ServantRetentionPolicyValue.RETAIN); |
duke@1 | 180 | POA tpoa = rootPOA.create_POA("MyTransientPOA", null, tpolicy); |
duke@1 | 181 | </strong> |
duke@1 | 182 | |
duke@1 | 183 | String ObjectId = "MyObjectId"; |
duke@1 | 184 | byte[] oid = ObjectId.getBytes(); |
duke@1 | 185 | |
duke@1 | 186 | org.omg.CORBA.Object obj = tpoa.create_reference_with_id(oid, |
duke@1 | 187 | new _HelloImpl_Tie()._all_interfaces(tpoa, oid)[0]); |
duke@1 | 188 | HelloInterface helloRef = (HelloInterface)PortableRemoteObject.narrow( |
duke@1 | 189 | obj, HelloInterface.class ); |
duke@1 | 190 | |
duke@1 | 191 | Context initialNamingContext = new InitialContext(); |
duke@1 | 192 | initialNamingContext.rebind("HelloService", helloRef); |
duke@1 | 193 | System.out.println("Hello Server: Ready..."); |
duke@1 | 194 | orb.run(); |
duke@1 | 195 | } catch (Exception e) { |
duke@1 | 196 | System.out.println("Trouble: " + e); |
duke@1 | 197 | e.printStackTrace(); |
duke@1 | 198 | } |
duke@1 | 199 | } |
duke@1 | 200 | |
duke@1 | 201 | |
duke@1 | 202 | public static void main(String args[]) { |
duke@1 | 203 | new HelloServer( args ); |
duke@1 | 204 | } |
duke@1 | 205 | } |
duke@1 | 206 | |
duke@1 | 207 | |
duke@1 | 208 | </PRE> |
duke@1 | 209 | |
duke@1 | 210 | |
duke@1 | 211 | |
duke@1 | 212 | <P> |
duke@1 | 213 | |
duke@1 | 214 | |
duke@1 | 215 | @since 1.4 |
duke@1 | 216 | <br> |
duke@1 | 217 | @serial exclude |
duke@1 | 218 | </body> |
duke@1 | 219 | </html> |