1 /*
   2  * Copyright (c) 1997, 2002, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 //
  27 
  28 module activation {
  29     // Possible values for endpointType argument on Server.getEndpoint()
  30     // If you change the value of this constant then update
  31     // core.EndPoint accordingly.  It has a duplicate definition
  32     // to avoid a compilation dependency.
  33     const string IIOP_CLEAR_TEXT = "IIOP_CLEAR_TEXT";
  34 
  35     // REVISIT Use the CORBA 2.3 ORBid if we ever get the Java ORB ID
  36     // issue resolved.
  37     typedef string ORBid;
  38     typedef long ServerId ;
  39     typedef sequence<string> POAName ;
  40 
  41     /** Raised if getEndpoint is called on a server callback object for
  42     * an invalid endpoint type
  43     */
  44     exception NoSuchEndPoint {} ;
  45 
  46     /**
  47     * Raised if an attempt is made to retrieve ports corresponding to
  48     * non-registered ORB
  49     */
  50 
  51     exception InvalidORBid {} ;
  52 
  53     /** Raised if an operation is attempted against an invalid server ID.
  54     */
  55     exception ServerNotRegistered {
  56         ServerId serverId ;
  57     };
  58 
  59     /** Raised if an operation is attempted for a server that is not running,
  60     * and the server is required to be running for the operation.
  61     */
  62     exception ServerNotActive {
  63         ServerId serverId ;
  64     };
  65 
  66     /** Raised if an operation is attempted against a server that is in a 
  67     * hold down state.  A server becomes held down if it fails to activate
  68     * within 10 seconds.
  69     */
  70     exception ServerHeldDown {
  71         ServerId serverId ;
  72     };
  73 
  74     /** Raised if an attempt is made to activate a server that is already 
  75     * running.
  76     */
  77     exception ServerAlreadyActive{
  78         ServerId serverId ;
  79     };
  80 
  81     /** Raised if an attempt is made to register a serverdef with the
  82     * same applicationName as an existing serverdef.
  83     */
  84     exception ServerAlreadyRegistered {
  85         ServerId serverId;
  86     };
  87 
  88     /** Raised if an attempt is made to install a server that is currently 
  89     * installed.  Note that a newly created server starts out in an uninstalled
  90     * state.
  91     */
  92     exception ServerAlreadyInstalled {
  93         ServerId serverId;
  94     } ;
  95 
  96     /** Raised if an attempt is made to uninstall a server that is currently 
  97     * uninstalled.  Note that a newly created server starts out in an 
  98     * uninstalled
  99     * state.
 100     */
 101     exception ServerAlreadyUninstalled {
 102         ServerId serverId;
 103     } ;
 104 
 105     /** Raised if an attempt is made to register an invalid serverdef.
 106     */
 107     exception BadServerDefinition {
 108         string reason;
 109     };
 110 
 111     /** Raised if an attempt is made to register endpoints for the
 112      * same ORB again
 113      */
 114     exception ORBAlreadyRegistered {
 115         ORBid orbId;
 116     };
 117 
 118     typedef long TCPPort ;
 119     typedef sequence<ServerId> ServerIds;
 120 
 121     // passing a struct containing endpointType and port-#s
 122     struct EndPointInfo {
 123         string endpointType;
 124         TCPPort port;
 125     };
 126 
 127     typedef sequence<EndPointInfo> EndpointInfoList;
 128 
 129     // struct contain ORB and port info
 130     struct ORBPortInfo {
 131         ORBid orbId;
 132         TCPPort port;
 133     };
 134 
 135     typedef sequence<ORBPortInfo> ORBPortInfoList;
 136 
 137     typedef sequence<ORBid> ORBidList;
 138 
 139     /** Server callback API, passed to Activator in active method.
 140     */
 141     interface Server {
 142         /** Shutdown this server.  Returns after orb.shutdown() completes.
 143         */
 144         void shutdown();
 145 
 146         /** Install the server.  Returns after the install hook completes
 147         * execution in the server.
 148         */
 149         void install();
 150 
 151         /** Uninstall the server.  Returns after the uninstall hook
 152         * completes execution.
 153         */
 154         void uninstall();
 155     };
 156 
 157     interface Activator {
 158         // A new ORB started server registers itself with the Activator
 159         void active(in ServerId serverId, in Server serverObj) 
 160             raises (ServerNotRegistered);
 161 
 162         // Install a particular kind of endpoint
 163         void registerEndpoints( in ServerId serverId, in ORBid orbId, 
 164             in EndpointInfoList endPointInfo) 
 165             raises (ServerNotRegistered,NoSuchEndPoint, ORBAlreadyRegistered) ;
 166 
 167         // list active servers
 168         ServerIds getActiveServers();
 169 
 170         // If the server is not running, start it up.
 171         void activate(in ServerId serverId) 
 172             raises (ServerAlreadyActive, ServerNotRegistered, ServerHeldDown);
 173 
 174         // If the server is running, shut it down
 175         void shutdown(in ServerId serverId) 
 176             raises (ServerNotActive, ServerNotRegistered);
 177 
 178         // Invoke the server install hook.  If the server is not 
 179         // currently running, this method will activate it.
 180         void install(in ServerId serverId) 
 181             raises (ServerNotRegistered, ServerHeldDown, 
 182                 ServerAlreadyInstalled);
 183 
 184         // list all registered ORBs for a server
 185         ORBidList getORBNames(in ServerId serverId)
 186             raises (ServerNotRegistered);
 187 
 188         // Invoke the server uninstall hook.  If the server is not
 189         // currently running, this method will activate it.
 190         // After this hook completes, the server may still be running.
 191         void uninstall(in ServerId serverId) 
 192             raises (ServerNotRegistered, ServerHeldDown, 
 193                 ServerAlreadyUninstalled);
 194     };
 195 
 196     interface Locator {
 197 
 198         // struct to return the list of endpoints for a server for a specific
 199         // endpoint
 200         struct ServerLocation {
 201             string hostname;
 202             ORBPortInfoList ports;
 203         };
 204 
 205         // struct to return the list of endpoints for a server for a specific
 206         // ORB
 207         struct ServerLocationPerORB {
 208             string hostname;
 209             EndpointInfoList ports;
 210         };
 211 
 212         // locate server - returns the port with a specific type for all registered
 213         // ORBs of an active server.
 214         // Starts the server if it is not already running.
 215         ServerLocation locateServer(
 216             in ServerId serverId,
 217             in string endPoint) 
 218             raises(NoSuchEndPoint, ServerNotRegistered, ServerHeldDown);
 219 
 220         // locate server - returns all ports registered with a specified ORB for
 221         // an active server
 222         // Starts the server if it is not already running.
 223         ServerLocationPerORB locateServerForORB(
 224             in ServerId serverId,
 225             in ORBid orbId) 
 226             raises(InvalidORBid, ServerNotRegistered, ServerHeldDown);
 227 
 228         // get the port for the endpoint of the locator
 229         TCPPort getEndpoint(in string endPointType)
 230             raises(NoSuchEndPoint);
 231 
 232         // Useful from external BadServerIdHandlers which need
 233         // to pick a particular port type.
 234         TCPPort getServerPortForType(
 235             in ServerLocationPerORB location,
 236             in string endPointType)
 237             raises(NoSuchEndPoint);
 238     };
 239 
 240     interface ServerManager : Activator, Locator { };
 241 
 242     interface InitialNameService {
 243         exception NameAlreadyBound {};
 244 
 245         // bind initial name
 246         void bind (
 247             in string name,
 248             in Object obj,
 249             in boolean isPersistant) raises (NameAlreadyBound);
 250 
 251     };
 252 
 253     interface Repository {
 254         // server program definition.  We should make this a ValueType.
 255         struct ServerDef {
 256             string  applicationName;    // alias used for servers with identical
 257                                         // serverName values.
 258             string  serverName;         // Class name of server's main class.
 259             string  serverClassPath;    // class path used to run the server.
 260             string  serverArgs;         
 261             string  serverVmArgs;
 262         };
 263         
 264         // register server definition
 265         // This returns the serverId of the server.  A newly created server is
 266         // always uninstalled.
 267         ServerId registerServer (in ServerDef serverDef) 
 268             raises (ServerAlreadyRegistered, BadServerDefinition);
 269         
 270         // unregister server definition
 271         void unregisterServer (in ServerId serverId) 
 272             raises (ServerNotRegistered);
 273 
 274         // get server definition
 275         ServerDef getServer(in ServerId serverId) 
 276             raises (ServerNotRegistered);
 277 
 278         // Return whether the server has been installed
 279         boolean isInstalled( in ServerId serverId ) 
 280             raises (ServerNotRegistered);
 281 
 282         // Mark the server as being installed.  Raises ServerAlreadyInstalled
 283         // if the server is currently marked as installed.
 284         void install( in ServerId serverId ) 
 285             raises (ServerNotRegistered, ServerAlreadyInstalled) ;
 286 
 287         // Mark the server as being uninstalled.  Raises ServerAlreadyUninstalled
 288         // if the server is currently marked as uninstalled.
 289         void uninstall( in ServerId serverId ) 
 290             raises (ServerNotRegistered, ServerAlreadyUninstalled) ;
 291 
 292         // list registered servers
 293         ServerIds listRegisteredServers ();
 294 
 295         typedef sequence<string>    StringSeq ;
 296 
 297         // Returns list of ALL applicationNames defined in ServerDefs of registered 
 298         // servers.
 299         StringSeq   getApplicationNames();
 300 
 301         // Find the ServerID associated with the given application name.
 302         ServerId getServerID( in string applicationName ) 
 303                 raises (ServerNotRegistered) ;
 304     };
 305 };