se/PortableActivationIDL/activation.idl

/*
 * 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) ;
    };
};