Java example source code file (activation.idl)

This example Java source code file (activation.idl) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

endpointinfolist, namealreadybound, portableinterceptor::orbid, portableinterceptor::serverid, portableinterceptor\:\:objectreferencetemplate, serveralreadyinstalled, serveralreadyuninstalled, serverdef, serverhelddown, serverids, serverlocationperorb, servernotregistered, serverproxy, tcpport

The activation.idl Java example source code

/*
 * Copyright (c) 2000, 2001, 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.
 */

#include "Interceptors.idl"

module PortableActivationIDL {
    /** Possible values for endpointType argument on Server.getEndpoint()
    * If you change the value of this constant then update
    * core.EndPoint accordingly.  It has a duplicate definition
    * to avoid a compilation dependency.
    */
    const string IIOP_CLEAR_TEXT = "IIOP_CLEAR_TEXT";

    /** Raised if getEndpoint is called on a server callback object for
    * an invalid endpoint type
    */
    exception NoSuchEndPoint {} ;

    /** Raised if an attempt is made to retrieve ports corresponding to
    * non-registered ORB
    */
    exception InvalidORBid {} ;

    /** Raised if an operation is attempted against an invalid server ID.
    */
    exception ServerNotRegistered {
	PortableInterceptor::ServerId serverId ;
    };

    /** Raised if an operation is attempted for a server that is not running,
    * and the server is required to be running for the operation.
    */
    exception ServerNotActive {
	PortableInterceptor::ServerId serverId ;
    };

    /** Raised if an operation is attempted against a server that is in a 
    * hold down state.  A server becomes held down if it fails to activate
    * within 10 seconds.
    */
    exception ServerHeldDown {
	PortableInterceptor::ServerId serverId ;
    };

    /** Raised if an attempt is made to activate a server that is already 
    * running.
    */
    exception ServerAlreadyActive{
	PortableInterceptor::ServerId serverId ;
    };

    /** Raised if an attempt is made to register a serverdef with the
    * same applicationName as an existing serverdef.
    */
    exception ServerAlreadyRegistered {
	PortableInterceptor::ServerId serverId;
    };

    /** Raised if an attempt is made to install a server that is currently 
    * installed.  Note that a newly created server starts out in an uninstalled
    * state.
    */
    exception ServerAlreadyInstalled {
	PortableInterceptor::ServerId serverId;
    } ;

    /** Raised if an attempt is made to uninstall a server that is currently 
    * uninstalled.  Note that a newly created server starts out in an 
    * uninstalled
    * state.
    */
    exception ServerAlreadyUninstalled {
	PortableInterceptor::ServerId serverId;
    } ;

    /** Raised if an attempt is made to register an invalid serverdef.
    */
    exception BadServerDefinition {
	string reason;
    };

    /** Raised if an attempt is made to register endpoints for the
     * same ORB again
     */
    exception ORBAlreadyRegistered {
	PortableInterceptor::ORBId orbId;
    };

    /** Type of TCP port number, used in structures that describe 
    * transport endpoints.  The valid range is actually 0-65535, but
    * we use a long here to avoid signed/unsigned conversion headaches
    * in Java.
    */
    typedef long TCPPort ;

    /** Sequence of server Ids, used for queries about servers.
    */
    typedef sequence<PortableInterceptor::ServerId> ServerIds;

    /** End point information for one particular kind of port associated with an 
    * an ORB.  This is only used in the
    * Activator interface, which must always run on the same host as the daemon,
    * therefore we do not need the host name here.
    */
    struct EndPointInfo {
	string endpointType;
	TCPPort port;
    };

    /** A list of endpoint information for a particular ORB.  
    */
    typedef sequence<EndPointInfo> EndpointInfoList;

    /** struct contain ORB and port info for a particular type of endpoint.
    * This is only used in the
    * Activator interface, which must always run on the same host as the daemon,
    * therefore we do not need the host name here.
    */
    struct ORBPortInfo {
	PortableInterceptor::ORBId orbId;
	TCPPort port;
    };

    /** A list of ORB and port information for a particular endpoint type.
    */
    typedef sequence<ORBPortInfo> ORBPortInfoList;

    /** A list of ORB IDs.
    */
    typedef sequence<PortableInterceptor::ORBId> ORBidList;

    /** Server callback interface, passed to Activator in registerServer method.
    */
    interface ServerProxy {
	/** Shutdown this server.  Returns after orb.shutdown() completes.
	*/
	void shutdown();

	/** Install the server.  Returns after the install hook completes
	* execution in the server.
	*/
	void install();

	/** Uninstall the server.  Returns after the uninstall hook
	* completes execution.
	*/
	void uninstall();
    };

    /** ORB callback interface, passed to Activator in registerORB method.
    */
    interface ORBProxy {
	/** Method used to cause ORB to activate the named adapter, if possible.
	* This will cause the named POA to register itself with the activator as
	* a side effect.  This should always happen before this call can complete.
	* This method returns true if adapter activation succeeded, otherwise it
	* returns false.
	*/
	boolean activate_adapter( in PortableInterceptor::AdapterName name ) ;
    } ;
    
    interface Activator {
	/*******************************************************
	*		    Server State Change Methods
	********************************************************/

    	/** A new ORB started server registers itself with the Activator
	*/
    	void registerServer(in PortableInterceptor::ServerId serverId, in ServerProxy serverObj) 
	    raises (ServerNotRegistered);

	/** A server is shutting down that was started by this activator.
	* Complete termination of the server is detected by the death of the
	* process implementing the server.
	*/
	void serverGoingDown( in PortableInterceptor::ServerId serverId ) ;

	/** Called whenever an ORB instance is created.  This registers
	* the transport endpoints and the ORB proxy callback object.
	* Note that we cannot detect when an ORB shuts down, although
	* all of the POA shutdowns should still be reported.
	*/
	void registerORB( in PortableInterceptor::ServerId serverId, in PortableInterceptor::ORBId orbId, 
	    in ORBProxy orb, in EndpointInfoList endPointInfo) 
	    raises (ServerNotRegistered,NoSuchEndPoint, ORBAlreadyRegistered) ;

	/** Construct or find an ORBD object template corresponding to the 
	* server's object template and return it.  Called whenever a 
	* persistent POA is created.
	*/
	PortableInterceptor::ObjectReferenceTemplate registerPOA( 
	    in PortableInterceptor::ServerId serverId, in PortableInterceptor::ORBId orbId, 
	    in PortableInterceptor::ObjectReferenceTemplate poaTemplate ) ;
 
	/** Called whenever a POA is destroyed.
	*/
	void poaDestroyed( 
	    in PortableInterceptor::ServerId serverId, in PortableInterceptor::ORBId orbId, 
	    in PortableInterceptor::ObjectReferenceTemplate poaTemplate ) ;       

	/*******************************************************
	*		    Server Control Methods
	********************************************************/

	/** If the server is not running, start it up.  This is allowed
	* whether or not the server has been installed.
	*/
	void activate(in PortableInterceptor::ServerId serverId) 
	    raises (ServerAlreadyActive, ServerNotRegistered, ServerHeldDown);

	/** If the server is running, shut it down
	*/
	void shutdown(in PortableInterceptor::ServerId serverId) 
	    raises (ServerNotActive, ServerNotRegistered);

	/** Invoke the server install hook.  If the server is not 
	* currently running, this method will activate it.
	*/
	void install(in PortableInterceptor::ServerId serverId) 
	    raises (ServerNotRegistered, ServerHeldDown, 
		ServerAlreadyInstalled);

	/** Invoke the server uninstall hook.  If the server is not
	* currently running, this method will activate it.
	* After this hook completes, the server may still be running.
	*/
	void uninstall(in PortableInterceptor::ServerId serverId) 
	    raises (ServerNotRegistered, ServerHeldDown, 
		ServerAlreadyUninstalled);

	/*******************************************************
	*		    Accessors
	********************************************************/

	/** list active servers
	*/
	ServerIds getActiveServers();

	/** list all registered ORBs for a server
	*/
	ORBidList getORBNames(in PortableInterceptor::ServerId serverId)
	    raises (ServerNotRegistered);

	/** Find the server template that corresponds to the ORBD's
	* adapter id.
	*/
	PortableInterceptor::ObjectReferenceTemplate lookupPOATemplate( 
	    in PortableInterceptor::ServerId serverId, in PortableInterceptor::ORBId orbId, 
	    in PortableInterceptor::AdapterName orbAdapterName ) ;
    };

    interface Locator {
	/** struct to return the list of endpoints for a server for a specific
	* endpoint type.  
	*/
	struct ServerLocationPerType {
	    string hostname;
	    ORBPortInfoList ports;
        };

	/** struct to return the list of endpoints for a server for a specific
	* ORB
	*/
	struct ServerLocationPerORB {
	    string hostname;
	    EndpointInfoList ports;
        };

	/** locate server - returns the port with a specific type for all registered
	* ORBs of an active server.
	* Starts the server if it is not already running.
	*/
	ServerLocationPerType locateServer(
	    in PortableInterceptor::ServerId serverId,
	    in string endPoint) 
	    raises(NoSuchEndPoint, ServerNotRegistered, ServerHeldDown);

	/** locate server - returns all ports registered with a specified ORB for
	* an active server
	* Starts the server if it is not already running.
	*/
	ServerLocationPerORB locateServerForORB(
	    in PortableInterceptor::ServerId serverId,
	    in PortableInterceptor::ORBId orbId) 
	    raises(InvalidORBid, ServerNotRegistered, ServerHeldDown);

	/** get the port for the endpoint of the locator
	*/
	TCPPort getEndpoint(in string endPointType)
	    raises(NoSuchEndPoint);

	/** Useful from external BadServerIdHandlers which need
	* to pick a particular port type.
	*/
	TCPPort getServerPortForType(
            in ServerLocationPerORB location,
	    in string endPointType)
	    raises(NoSuchEndPoint);
    };

    /** Interface used to combine the Activator and Locator when both are
    * implemented together in the same process, as is currently the case
    * for our implementation.
    */
    interface ServerManager : Activator, Locator { };

    /** Interface used to support binding references in the bootstrap name
    * service.
    */
    interface InitialNameService {
	exception NameAlreadyBound {};

	/** bind initial name
	*/
	void bind (
	    in string name,
	    in Object obj,
	    in boolean isPersistant) raises (NameAlreadyBound);
    };

    interface Repository {
	/** server program definition.  
	*/
	struct ServerDef {
	    string  applicationName;	// alias used for servers with identical
					// serverName values.
	    string  serverName;		// Class name of server's main class.
	    string  serverClassPath;	// class path used to run the server.
	    string  serverArgs;		// arguments passed to the server
	    string  serverVmArgs;	// arguments passed to the server's Java VM1
	    boolean isInstalled;	// Whether or not the server has been installed
	};
	
	/** register server definition.
	* This returns the serverId of the server.  A newly created server is
	* always uninstalled.
	*/
	PortableInterceptor::ServerId registerServer (in ServerDef serverDef) 
	    raises (ServerAlreadyRegistered, BadServerDefinition);
	
	/** unregister server definition
	*/
	void unregisterServer (in PortableInterceptor::ServerId serverId) 
	    raises (ServerNotRegistered);

	/** get server definition
	*/
	ServerDef getServer(in PortableInterceptor::ServerId serverId) 
	    raises (ServerNotRegistered);

	/** Return whether the server has been installed
	*/
	boolean isInstalled( in PortableInterceptor::ServerId serverId ) 
	    raises (ServerNotRegistered);

	/** Mark the server as being installed.  Raises ServerAlreadyInstalled
	* if the server is currently marked as installed.
	*/
	void install( in PortableInterceptor::ServerId serverId ) 
	    raises (ServerNotRegistered, ServerAlreadyInstalled) ;

	/** Mark the server as being uninstalled.  Raises ServerAlreadyUninstalled
	* if the server is currently marked as uninstalled.
	*/
	void uninstall( in PortableInterceptor::ServerId serverId ) 
	    raises (ServerNotRegistered, ServerAlreadyUninstalled) ;

	/** list registered servers
	*/
	ServerIds listRegisteredServers ();

	/** Type used for a list of application names
	*/
	typedef sequence<string>    AppNames ;

	/** Returns list of ALL applicationNames defined in ServerDefs of registered 
	* servers.
	*/
	AppNames   getApplicationNames();

	/** Find the ServerID associated with the given application name.
	*/
	PortableInterceptor::ServerId getServerID( in string applicationName ) 
		raises (ServerNotRegistered) ;
    };
};