corba/src/share/classes/org/omg/PortableServer/package.html - edge/openjdk - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <html>
 <head>
 <!--

  Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

  This code is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License version 2 only, as
  published by the Free Software Foundation.  Oracle designates this
  particular file as subject to the "Classpath" exception as provided
  by Oracle in the LICENSE file that accompanied this code.

  This code is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  version 2 for more details (a copy is included in the LICENSE file that
  accompanied this code).

  You should have received a copy of the GNU General Public License version
  2 along with this work; if not, write to the Free Software Foundation,
  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  or visit www.oracle.com if you need additional information or have any
  questions.


 -->

 </head>
 <body bgcolor="white">
 Provides classes and interfaces for making the server side of your applications
 portable across multivendor ORBs.

 <P>In Java, Portable Object Adaptor (POA)-based Dynamic Skeleton Interface (DSI)
 servants inherit from the  standard <TT>DynamicImplementation</TT> class, which
 inherits from the <TT>Servant</TT> class. The native <TT>Servant</TT> type is
 defined by the <TT>PortableServer</TT> module for the POA. In Java, the
   <TT>Servant</TT> type is mapped to the Java
   <TT>org.omg.PortableServer.Servant</TT> class.
   It serves as the base class for all POA servant
   implementations and provides a number of methods that may
   be invoked by the application programmer, as well as methods
   which are invoked by the POA itself and may be overridden by
   the user to control aspects of servant behavior.

 <H2>Package Specification</H2>

 <P>For a precise list of supported sections of official OMG specifications with which
 the Java[tm] Platform, Standard Edition 6 complies, see <A
 HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA
 support in Java[tm] SE 6</A>.
 <p>

 <H2>POA-related Interfaces</H2>

 <P>The <TT>PortableServer</TT> module defines the following POA-related interfaces:
 <P>
 <UL>
 	<LI><TT>POA</TT>
 	<LI><TT>POAManager</TT>
 	<LI><TT>ServantManager</TT>
 	<LI><TT>ServantActivator</TT>
 	<LI><TT>ServantLocator</TT>
 	<LI><TT>AdapterActivator</TT>
 	<LI><TT>ThreadPolicy</TT>
 	<LI><TT>LifespanPolicy</TT>
 	<LI><TT>IdUniquenessPolicy</TT>
 	<LI><TT>IdAssignmentPolicy</TT>
 	<LI><TT>ImplicitActivationPolicy</TT>
 	<LI><TT>ServantRetentionPolicy</TT>
 	<LI><TT>RequestProcessingPolicy</TT>
 	<LI><TT>Current</TT>
 </UL>

 <P>In addition, the POA defines the <TT>Servant</TT> native type.

 <H3>Operations classes</H3>

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

 <H3>Value Classes</H3>

 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:
 <P>
 <UL>
 <LI><code>IdAssignmentPolicyValue</code>
 <LI><code>IdUniquenessPolicyValue</code>
 <LI><code>ImplicitActivationPolicyValue</code>
 <LI><code>LifespanPolicyValue</code>
 <LI><code>RequestProcessingPolicyValue</code>
 <LI><code>ServantRetentionPolicyValue</code>
 <LI><code>ThreadPolicyValue</code>
 </UL>

 <H3>Helper Classes</H3>

 <P>Helper classes, which are generated for all user-defined types in an OMG IDL
 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:
 <P>
 <UL>
 <LI><code>ForwardRequestHelper</code>
 <LI><code>ServantActivatorHelper</code>
 <LI><code>ServantLocatorHelper</code>
 </UL>

 <H3>POA Classes</H3>

 <P>POA classes are used to implement the <code>ServantActivator</code> or <code>ServantLocator</code>.

 <H3>Exceptions</H3>

 <P>The <code>ForwardRequest</code> exception indicates to the ORB
 that it is responsible for delivering the current request and subsequent <code>ForwardRequest</code> requests to the object denoted in the
  <code>forward_reference</code> member of the exception.

 <H3>Interfaces Implemented by the Application Programmer</H3>

 <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:
 <P>
 <ul>
 	<LI><code>AdapterActivator</code>
 	<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.
 	<P>
 	<LI><code>ServantLocator</code>
 	<P>When the POA has the <code>NON_RETAIN</code> policy, it uses servant managers that are <code>ServantLocator</code>s.
 	<P>
 	<LI><code>ServantActivator</code>
 	<P>When the POA has the <code>RETAIN</code> policy, it uses servant managers that are <code>ServantActivator</code>s.
 </ul>


 <H2>Package <TT>org.omg.PortableServer.ServantLocatorPackage</TT></H2>

 <P>This package supplies a <TT>CookieHolder</TT> class for passing
 the <TT>Cookie</TT> type as an <code>out</code> parameter. The <code>CookieHolder</code> class
 follows exactly the same pattern as the other holder classes for basic types.

 <H2>Related Documentation</H2>

 <P>For an overview of Java IDL, please see:
 <P>
 <LI><A HREF="../../../../technotes/guides/idl/index.html">Java IDL home page</A>.

 <H2>Example Code</H2>
 <a name="sampleserver"></a>
 <H3>Example Server Code</H3>
 <P>
 <PRE>
 import javax.naming.InitialContext;
 import javax.naming.Context;
 import javax.rmi.PortableRemoteObject ;
 import com.sun.corba.se.impl.poa.POAORB;
 import org.omg.PortableServer.*;
 import java.util.*;
 import org.omg.CORBA.*;
 import javax.rmi.CORBA.Stub;
 import javax.rmi.CORBA.Util;


 public class HelloServer {
     public HelloServer(String[] args) {
         try {
             Properties p = System.getProperties();
          //   p.put("org.omg.CORBA.ORBClass", "com.sun.corba.ee.internal.POA.POAORB");
             ORB orb = ORB.init( args, p );

             POA rootPOA = (POA)orb.resolve_initial_references("RootPOA");
 <strong>
             Policy[] tpolicy = new Policy[3];
             tpolicy[0] = rootPOA.create_lifespan_policy(
                 LifespanPolicyValue.TRANSIENT );
             tpolicy[1] = rootPOA.create_request_processing_policy(
                 RequestProcessingPolicyValue.USE_ACTIVE_OBJECT_MAP_ONLY );
             tpolicy[2] = rootPOA.create_servant_retention_policy(
                 ServantRetentionPolicyValue.RETAIN);
             POA tpoa = rootPOA.create_POA("MyTransientPOA", null, tpolicy);
 </strong>

             String  ObjectId = "MyObjectId";
             byte[] oid = ObjectId.getBytes();

             org.omg.CORBA.Object obj = tpoa.create_reference_with_id(oid,
                 new _HelloImpl_Tie()._all_interfaces(tpoa, oid)[0]);
             HelloInterface helloRef = (HelloInterface)PortableRemoteObject.narrow(
                 obj, HelloInterface.class );

             Context initialNamingContext = new InitialContext();
             initialNamingContext.rebind("HelloService", helloRef);
             System.out.println("Hello Server: Ready...");
             orb.run();
          } catch (Exception e) {
             System.out.println("Trouble: " + e);
             e.printStackTrace();
          }
      }


      public static void main(String args[]) {
          new HelloServer( args );
      }
 }


 </PRE>


 <P>


 @since 1.4
 <br>
 @serial exclude
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<html>
	<head>
	<!--

	Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

	This code is free software; you can redistribute it and/or modify it
	under the terms of the GNU General Public License version 2 only, as
	published by the Free Software Foundation. Oracle designates this
	particular file as subject to the "Classpath" exception as provided
	by Oracle in the LICENSE file that accompanied this code.

	This code is distributed in the hope that it will be useful, but WITHOUT
	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	version 2 for more details (a copy is included in the LICENSE file that
	accompanied this code).

	You should have received a copy of the GNU General Public License version
	2 along with this work; if not, write to the Free Software Foundation,
	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	or visit www.oracle.com if you need additional information or have any
	questions.


	-->

	</head>
	<body bgcolor="white">
	Provides classes and interfaces for making the server side of your applications
	portable across multivendor ORBs.

	<P>In Java, Portable Object Adaptor (POA)-based Dynamic Skeleton Interface (DSI)
	servants inherit from the standard <TT>DynamicImplementation</TT> class, which
	inherits from the <TT>Servant</TT> class. The native <TT>Servant</TT> type is
	defined by the <TT>PortableServer</TT> module for the POA. In Java, the
	<TT>Servant</TT> type is mapped to the Java
	<TT>org.omg.PortableServer.Servant</TT> class.
	It serves as the base class for all POA servant
	implementations and provides a number of methods that may
	be invoked by the application programmer, as well as methods
	which are invoked by the POA itself and may be overridden by
	the user to control aspects of servant behavior.

	<H2>Package Specification</H2>

	<P>For a precise list of supported sections of official OMG specifications with which
	the Java[tm] Platform, Standard Edition 6 complies, see <A
	HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA
	support in Java[tm] SE 6</A>.
	<p>

	<H2>POA-related Interfaces</H2>

	<P>The <TT>PortableServer</TT> module defines the following POA-related interfaces:
	<P>
	<UL>
	<LI><TT>POA</TT>
	<LI><TT>POAManager</TT>
	<LI><TT>ServantManager</TT>
	<LI><TT>ServantActivator</TT>
	<LI><TT>ServantLocator</TT>
	<LI><TT>AdapterActivator</TT>
	<LI><TT>ThreadPolicy</TT>
	<LI><TT>LifespanPolicy</TT>
	<LI><TT>IdUniquenessPolicy</TT>
	<LI><TT>IdAssignmentPolicy</TT>
	<LI><TT>ImplicitActivationPolicy</TT>
	<LI><TT>ServantRetentionPolicy</TT>
	<LI><TT>RequestProcessingPolicy</TT>
	<LI><TT>Current</TT>
	</UL>

	<P>In addition, the POA defines the <TT>Servant</TT> native type.

	<H3>Operations classes</H3>

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

	<H3>Value Classes</H3>

	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:
	<P>
	<UL>
	<LI><code>IdAssignmentPolicyValue</code>
	<LI><code>IdUniquenessPolicyValue</code>
	<LI><code>ImplicitActivationPolicyValue</code>
	<LI><code>LifespanPolicyValue</code>
	<LI><code>RequestProcessingPolicyValue</code>
	<LI><code>ServantRetentionPolicyValue</code>
	<LI><code>ThreadPolicyValue</code>
	</UL>

	<H3>Helper Classes</H3>

	<P>Helper classes, which are generated for all user-defined types in an OMG IDL
	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:
	<P>
	<UL>
	<LI><code>ForwardRequestHelper</code>
	<LI><code>ServantActivatorHelper</code>
	<LI><code>ServantLocatorHelper</code>
	</UL>

	<H3>POA Classes</H3>

	<P>POA classes are used to implement the <code>ServantActivator</code> or <code>ServantLocator</code>.

	<H3>Exceptions</H3>

	<P>The <code>ForwardRequest</code> exception indicates to the ORB
	that it is responsible for delivering the current request and subsequent <code>ForwardRequest</code> requests to the object denoted in the
	<code>forward_reference</code> member of the exception.

	<H3>Interfaces Implemented by the Application Programmer</H3>

	<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:
	<P>
	<ul>
	<LI><code>AdapterActivator</code>
	<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.
	<P>
	<LI><code>ServantLocator</code>
	<P>When the POA has the <code>NON_RETAIN</code> policy, it uses servant managers that are <code>ServantLocator</code>s.
	<P>
	<LI><code>ServantActivator</code>
	<P>When the POA has the <code>RETAIN</code> policy, it uses servant managers that are <code>ServantActivator</code>s.
	</ul>


	<H2>Package <TT>org.omg.PortableServer.ServantLocatorPackage</TT></H2>

	<P>This package supplies a <TT>CookieHolder</TT> class for passing
	the <TT>Cookie</TT> type as an <code>out</code> parameter. The <code>CookieHolder</code> class
	follows exactly the same pattern as the other holder classes for basic types.

	<H2>Related Documentation</H2>

	<P>For an overview of Java IDL, please see:
	<P>
	<LI><A HREF="../../../../technotes/guides/idl/index.html">Java IDL home page</A>.

	<H2>Example Code</H2>
	<a name="sampleserver"></a>
	<H3>Example Server Code</H3>
	<P>
	<PRE>
	import javax.naming.InitialContext;
	import javax.naming.Context;
	import javax.rmi.PortableRemoteObject ;
	import com.sun.corba.se.impl.poa.POAORB;
	import org.omg.PortableServer.*;
	import java.util.*;
	import org.omg.CORBA.*;
	import javax.rmi.CORBA.Stub;
	import javax.rmi.CORBA.Util;



	public class HelloServer {
	public HelloServer(String[] args) {
	try {
	Properties p = System.getProperties();
	// p.put("org.omg.CORBA.ORBClass", "com.sun.corba.ee.internal.POA.POAORB");
	ORB orb = ORB.init( args, p );

	POA rootPOA = (POA)orb.resolve_initial_references("RootPOA");
	<strong>
	Policy[] tpolicy = new Policy[3];
	tpolicy[0] = rootPOA.create_lifespan_policy(
	LifespanPolicyValue.TRANSIENT );
	tpolicy[1] = rootPOA.create_request_processing_policy(
	RequestProcessingPolicyValue.USE_ACTIVE_OBJECT_MAP_ONLY );
	tpolicy[2] = rootPOA.create_servant_retention_policy(
	ServantRetentionPolicyValue.RETAIN);
	POA tpoa = rootPOA.create_POA("MyTransientPOA", null, tpolicy);
	</strong>

	String ObjectId = "MyObjectId";
	byte[] oid = ObjectId.getBytes();

	org.omg.CORBA.Object obj = tpoa.create_reference_with_id(oid,
	new _HelloImpl_Tie()._all_interfaces(tpoa, oid)[0]);
	HelloInterface helloRef = (HelloInterface)PortableRemoteObject.narrow(
	obj, HelloInterface.class );

	Context initialNamingContext = new InitialContext();
	initialNamingContext.rebind("HelloService", helloRef);
	System.out.println("Hello Server: Ready...");
	orb.run();
	} catch (Exception e) {
	System.out.println("Trouble: " + e);
	e.printStackTrace();
	}
	}


	public static void main(String args[]) {
	new HelloServer( args );
	}
	}


	</PRE>



	<P>


	@since 1.4
	<br>
	@serial exclude
	</body>
	</html>