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