The interfaces for the runtime library, as described in SIDL, are:
// // File: sidl.sidl // Revision: @(#) $Revision: 5162 $ // Date: $Date: 2005-12-20 10:14:46 -0800 (Tue, 20 Dec 2005) $ // Description: sidl interface description for the basic sidl run-time library // // Copyright (c) 2001, The Regents of the University of Calfornia. // Produced at the Lawrence Livermore National Laboratory. // Written by the Components Team <components@llnl.gov> // UCRL-CODE-2002-054 // All rights reserved. // // This file is part of Babel. For more information, see // http://www.llnl.gov/CASC/components/. Please read the COPYRIGHT file // for Our Notice and the LICENSE file for the GNU Lesser General Public // License. // // This program is free software; you can redistribute it and/or modify it // under the terms of the GNU Lesser General Public License (as published by // the Free Software Foundation) version 2.1 dated February 1999. // // This program 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 terms and // conditions of the GNU Lesser General Public License for more details. // // You should have recieved a copy of the GNU Lesser General Public License // along with this program; if not, write to the Free Software Foundation, // Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA /** * The <code>sidl</code> package contains the fundamental type and interface * definitions for the <code>sidl</code> interface definition language. It * defines common run-time libraries and common base classes and interfaces. * Every interface implicitly inherits from <code>sidl.BaseInterface</code> * and every class implicitly inherits from <code>sidl.BaseClass</code>. * */ package sidl version 0.9.12 { /** * Every interface in <code>sidl</code> implicitly inherits * from <code>BaseInterface</code>, and it is implemented * by <code>BaseClass</code> below. */ interface BaseInterface { /** * <p> * Add one to the intrinsic reference count in the underlying object. * Object in <code>sidl</code> have an intrinsic reference count. * Objects continue to exist as long as the reference count is * positive. Clients should call this method whenever they * create another ongoing reference to an object or interface. * </p> * <p> * This does not have a return value because there is no language * independent type that can refer to an interface or a * class. * </p> */ void addRef(); /** * Decrease by one the intrinsic reference count in the underlying * object, and delete the object if the reference is non-positive. * Objects in <code>sidl</code> have an intrinsic reference count. * Clients should call this method whenever they remove a * reference to an object or interface. */ void deleteRef(); /** * Return true if and only if <code>obj</code> refers to the same * object as this object. */ bool isSame(in BaseInterface iobj); /** * Return whether this object is an instance of the specified type. * The string name must be the <code>sidl</code> type name. This * routine will return <code>true</code> if and only if a cast to * the string type name would succeed. */ bool isType(in string name); /** * Return the meta-data about the class implementing this interface. */ ClassInfo getClassInfo(); } /** * Every class implicitly inherits from <code>BaseClass</code>. This * class implements the methods in <code>BaseInterface</code>. */ class BaseClass implements BaseInterface { /** * <p> * Add one to the intrinsic reference count in the underlying object. * Object in <code>sidl</code> have an intrinsic reference count. * Objects continue to exist as long as the reference count is * positive. Clients should call this method whenever they * create another ongoing reference to an object or interface. * </p> * <p> * This does not have a return value because there is no language * independent type that can refer to an interface or a * class. * </p> */ final void addRef(); /** * Decrease by one the intrinsic reference count in the underlying * object, and delete the object if the reference is non-positive. * Objects in <code>sidl</code> have an intrinsic reference count. * Clients should call this method whenever they remove a * reference to an object or interface. */ final void deleteRef(); /** * Return true if and only if <code>obj</code> refers to the same * object as this object. */ final bool isSame(in BaseInterface iobj); /** * Return whether this object is an instance of the specified type. * The string name must be the <code>sidl</code> type name. This * routine will return <code>true</code> if and only if a cast to * the string type name would succeed. */ bool isType(in string name); /** * Return the meta-data about the class implementing this interface. */ final ClassInfo getClassInfo(); } /** * This package has some I/O capability that's not core to the * SIDL object model, but still needed by parts of the generated code */ package io { /** * Objects that implement Serializable will be serializable (copyable) * over RMI, or storable to streams. Classes that can pack or unpack * themselves should implement this interface */ interface Serializable { void packObj( in Serializer ser ); void unpackObj( in Deserializer des ); } } /** * Every exception implements <code>BaseException</code>. This interface * declares the basic functionality to get and set error messages and stack * traces. */ interface BaseException extends sidl.io.Serializable{ /** * Return the message associated with the exception. */ string getNote(); /** * Set the message associated with the exception. */ void setNote(in string message); /** * Returns formatted string containing the concatenation of all * tracelines. */ string getTrace(); /** * Adds a stringified entry/line to the stack trace. */ void add[Line](in string traceline); /** * Formats and adds an entry to the stack trace based on the * file name, line number, and method name. */ void add(in string filename, in int lineno, in string methodname); } /** * This exception type is the default exception for every method. * */ interface RuntimeException extends BaseException {} /** * <code>SIDLException</code> provides the basic functionality of the * <code>BaseException</code> interface for getting and setting error * messages and stack traces. */ class SIDLException implements-all BaseException { } /** * <code>PreViolation</code> provides the basic marker for * a pre-condition exception. */ class PreViolation extends SIDLException implements RuntimeException { } /** * <code>PostViolation</code> provides the basic marker for * a post-condition exception. */ class PostViolation extends SIDLException implements RuntimeException { } /** * <code>InvViolation</code> provides the basic marker for * a invariant exception. */ class InvViolation extends SIDLException implements RuntimeException { } /** * When loading a dynamically linked library, there are three * settings: LOCAL, GLOBAL and SCLSCOPE. */ enum Scope { /** Attempt to load the symbols into a local namespace. */ LOCAL, /** Attempt to load the symbols into the global namespace. */ GLOBAL, /** Use the scope setting from the SCL file. */ SCLSCOPE } /** * When loading a dynmaically linked library, there are three * settings: LAZY, NOW, SCLRESOLVE */ enum Resolve { /** Resolve symbols on an as needed basis. */ LAZY, /** Resolve all symbols at load time. */ NOW, /** Use the resolve setting from the SCL file. */ SCLRESOLVE } /** * The <code>DLL</code> class encapsulates access to a single * dynamically linked library. DLLs are loaded at run-time using * the <code>loadLibrary</code> method and later unloaded using * <code>unloadLibrary</code>. Symbols in a loaded library are * resolved to an opaque pointer by method <code>lookupSymbol</code>. * Class instances are created by <code>createClass</code>. */ class DLL { /** * Load a dynamic link library using the specified URI. The * URI may be of the form "main:", "lib:", "file:", "ftp:", or * "http:". A URI that starts with any other protocol string * is assumed to be a file name. The "main:" URI creates a * library that allows access to global symbols in the running * program's main address space. The "lib:X" URI converts the * library "X" into a platform-specific name (e.g., libX.so) and * loads that library. The "file:" URI opens the DLL from the * specified file path. The "ftp:" and "http:" URIs copy the * specified library from the remote site into a local temporary * file and open that file. This method returns true if the * DLL was loaded successfully and false otherwise. Note that * the "ftp:" and "http:" protocols are valid only if the W3C * WWW library is available. * * @param uri the URI to load. This can be a .la file * (a metadata file produced by libtool) or * a shared library binary (i.e., .so, * .dll or whatever is appropriate for your * OS) * @param loadGlobally <code>true</code> means that the shared * library symbols will be loaded into the * global namespace; <code>false</code> * means they will be loaded into a * private namespace. Some operating systems * may not be able to honor the value presented * here. * @param loadLazy <code>true</code> instructs the loader to * that symbols can be resolved as needed (lazy) * instead of requiring everything to be resolved * now (at load time). */ bool loadLibrary(in string uri, in bool loadGlobally, in bool loadLazy); /** * Get the library name. This is the name used to load the * library in <code>loadLibrary</code> except that all file names * contain the "file:" protocol. */ string getName(); /** * Unload the dynamic link library. The library may no longer * be used to access symbol names. When the library is actually * unloaded from the memory image depends on details of the operating * system. */ void unloadLibrary(); /** * Lookup a symbol from the DLL and return the associated pointer. * A null value is returned if the name does not exist. */ opaque lookupSymbol(in string linker_name); /** * Create an instance of the sidl class. If the class constructor * is not defined in this DLL, then return null. */ BaseClass createClass(in string sidl_name); } /** * Interface <code>Finder</code> is an interface for classes that resolve * dynamic libraries. * Class <code>Loader</code> takes one of these interfaces through the * method <code>setFinder</code>. If NULL is passed to setFinder, the * class <code>DefaultFinder</code> is used. */ interface Finder { /** * Find a DLL containing the specified information for a sidl * class. This method searches through the files in set set path * looking for a shared library that contains the client-side or IOR * for a particular sidl class. * * @param sidl_name the fully qualified (long) name of the * class/interface to be found. Package names * are separated by period characters from each * other and the class/interface name. * @param target to find a client-side binding, this is * normally the name of the language. * To find the implementation of a class * in order to make one, you should pass * the string "ior/impl" here. * @param lScope this specifies whether the symbols should * be loaded into the global scope, a local * scope, or use the setting in the file. * @param lResolve this specifies whether symbols should be * resolved as needed (LAZY), completely * resolved at load time (NOW), or use the * setting from the file. * @return a non-NULL object means the search was successful. * The DLL has already been added. */ DLL findLibrary(in string sidl_name, in string target, in Scope lScope, in Resolve lResolve); /** * Set the search path, which is a semi-colon separated sequence of * URIs as described in class <code>DLL</code>. This method will * invalidate any existing search path. */ void setSearchPath(in string path_name); /** * Return the current search path. If the search path has not been * set, then the search path will be taken from environment variable * SIDL_DLL_PATH. */ string getSearchPath(); /** * Append the specified path fragment to the beginning of the * current search path. If the search path has not yet been set * by a call to <code>setSearchPath</code>, then this fragment will * be appended to the path in environment variable SIDL_DLL_PATH. */ void addSearchPath(in string path_fragment); } /** * This class is the Default Finder. If no Finder is set in class Loader, * this finder is used. It uses SCL files from the filesystem to * resolve dynamic libraries. * * The initial search path is taken from the SIDL_DLL_PATH * environment variable. */ class DFinder implements-all Finder { } /** * Class <code>Loader</code> manages dyanamic loading and symbol name * resolution for the sidl runtime system. The <code>Loader</code> class * manages a library search path and keeps a record of all libraries * loaded through this interface, including the initial "global" symbols * in the main program. * * Unless explicitly set, the <code>Loader</code> uses the default * <code>sidl.Finder</code> implemented in <code>sidl.DFinder</code>. * This class searches the filesystem for <code>.scl</code> files when * trying to find a class. The initial path is taken from the * environment variable SIDL_DLL_PATH, which is a semi-colon * separated sequence of URIs as described in class <code>DLL</code>. */ class Loader { /** * Load the specified library if it has not already been loaded. * The URI format is defined in class <code>DLL</code>. The search * path is not searched to resolve the library name. * * @param uri the URI to load. This can be a .la file * (a metadata file produced by libtool) or * a shared library binary (i.e., .so, * .dll or whatever is appropriate for your * OS) * @param loadGlobally <code>true</code> means that the shared * library symbols will be loaded into the * global namespace; <code>false</code> * means they will be loaded into a * private namespace. Some operating systems * may not be able to honor the value presented * here. * @param loadLazy <code>true</code> instructs the loader to * that symbols can be resolved as needed (lazy) * instead of requiring everything to be resolved * now. * @return if the load was successful, a non-NULL DLL object is returned. */ static DLL loadLibrary(in string uri, in bool loadGlobally, in bool loadLazy); /** * Append the specified DLL to the beginning of the list of already * loaded DLLs. */ static void addDLL(in DLL dll); /** * Unload all dynamic link libraries. The library may no longer * be used to access symbol names. When the library is actually * unloaded from the memory image depends on details of the operating * system. */ static void unloadLibraries(); /** * Find a DLL containing the specified information for a sidl * class. This method searches SCL files in the search path looking * for a shared library that contains the client-side or IOR * for a particular sidl class. * * This call is implemented by calling the current * <code>Finder</code>. The default finder searches the local * file system for <code>.scl</code> files to locate the * target class/interface. * * @param sidl_name the fully qualified (long) name of the * class/interface to be found. Package names * are separated by period characters from each * other and the class/interface name. * @param target to find a client-side binding, this is * normally the name of the language. * To find the implementation of a class * in order to make one, you should pass * the string "ior/impl" here. * @param lScope this specifies whether the symbols should * be loaded into the global scope, a local * scope, or use the setting in the SCL file. * @param lResolve this specifies whether symbols should be * resolved as needed (LAZY), completely * resolved at load time (NOW), or use the * setting from the SCL file. * @return a non-NULL object means the search was successful. * The DLL has already been added. */ static DLL findLibrary(in string sidl_name, in string target, in Scope lScope, in Resolve lResolve); /** * Set the search path, which is a semi-colon separated sequence of * URIs as described in class <code>DLL</code>. This method will * invalidate any existing search path. * * This updates the search path in the current <code>Finder</code>. */ static void setSearchPath(in string path_name); /** * Return the current search path. The default * <code>Finder</code> initializes the search path * from environment variable SIDL_DLL_PATH. * */ static string getSearchPath(); /** * Append the specified path fragment to the beginning of the * current search path. This method operates on the Loader's * current <code>Finder</code>. This will add a path to the * current search path. Normally, the search path is initialized * from the SIDL_DLL_PATH environment variable. */ static void addSearchPath(in string path_fragment); /** * This method sets the <code>Finder</code> that * <code>Loader</code> will use to find DLLs. If no * <code>Finder</code> is set or if NULL is passed in, the Default * Finder <code>DFinder</code> will be used. * * Future calls to <code>findLibrary</code>, * <code>addSearchPath</code>, <code>getSearchPath</code>, and * <code>setSearchPath</code> are deligated to the * <code>Finder</code> set here. */ static void setFinder(in Finder f); /** * This method gets the <code>Finder</code> that <code>Loader</code> * uses to find DLLs. */ static Finder getFinder(); } /** * This provides an interface to the meta-data available on the * class. */ interface ClassInfo { /** * Return the name of the class. */ string getName(); /** * Get the version of the intermediate object representation. * This will be in the form of major_version.minor_version. */ string getIORVersion(); } /** * An implementation of the <code>ClassInfo</code> interface. This * provides methods to set all the attributes that are read-only in * the <code>ClassInfo</code> interface. */ class ClassInfoI implements-all ClassInfo { /** * Set the name of the class. */ final void setName(in string name); /** * Set the IOR major and minor version numbers. */ final void setIORVersion(in int major, in int minor); } /** * Exception thrown from Babel internals when memory allocation * fails */ class MemoryAllocationException extends sidl.SIDLException implements RuntimeException { } /** * Exception is thrown when a cast fails and the failure needs to * be communicated up the call stack. (Note: babel _cast does NOT * throw this exception) */ class CastException extends sidl.SIDLException implements RuntimeException { } /** * This Exception is thrown by the Babel runtime when a non SIDL * exception is thrown from an exception throwing language such as * C++ or Java. */ class LangSpecificException extends sidl.SIDLException implements RuntimeException { } /** * This package has some I/O capability that's not core to the SIDL * object model, but still needed by parts of the generated code */ package io { /** generic exception for I/O issues */ class IOException extends sidl.SIDLException implements RuntimeException { } /** * Standard interface for packing Babel types */ interface Serializer { void packBool( in string key, in bool value ) throws IOException ; void packChar( in string key, in char value ) throws IOException ; void packInt( in string key, in int value ) throws IOException ; void packLong( in string key, in long value ) throws IOException ; void packOpaque( in string key, in opaque value ) throws IOException ; void packFloat( in string key, in float value ) throws IOException ; void packDouble( in string key, in double value ) throws IOException ; void packFcomplex( in string key, in fcomplex value ) throws IOException ; void packDcomplex( in string key, in dcomplex value ) throws IOException ; void packString( in string key, in string value ) throws IOException ; void packSerializable( in string key, in Serializable value ) throws IOException; /** * pack arrays of values. It is possible to ensure an array is * in a certain order by passing in ordering and dimension * requirements. ordering should represent a value in the * sidl_array_ordering enumeration in sidlArray.h If either * argument is 0, it means there is no restriction on that * aspect. The boolean reuse_array flag is set to true if the * remote unserializer should try to reuse the array that is * passed into it or not. */ void packBoolArray( in string key, in array<bool> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packCharArray( in string key, in array<char> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packIntArray( in string key, in array<int> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packLongArray( in string key, in array<long> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packOpaqueArray( in string key, in array<opaque> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packFloatArray( in string key, in array<float> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packDoubleArray( in string key, in array<double> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packFcomplexArray( in string key, in array<fcomplex> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packDcomplexArray( in string key, in array<dcomplex> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packStringArray( in string key, in array<string> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException ; void packGenericArray( in string key, in array<> value, in bool reuse_array ) throws IOException ; void packSerializableArray( in string key, in array<Serializable> value, in int ordering, in int dimen, in bool reuse_array ) throws IOException; } /** * Standard interface for unpacking Babel types */ interface Deserializer { /* unpack values */ void unpackBool( in string key, out bool value ) throws IOException ; void unpackChar( in string key, out char value ) throws IOException ; void unpackInt( in string key, out int value ) throws IOException ; void unpackLong( in string key, out long value ) throws IOException ; void unpackOpaque( in string key, out opaque value ) throws IOException ; void unpackFloat( in string key, out float value ) throws IOException ; void unpackDouble( in string key, out double value ) throws IOException ; void unpackFcomplex( in string key, out fcomplex value ) throws IOException ; void unpackDcomplex( in string key, out dcomplex value ) throws IOException ; void unpackString( in string key, out string value ) throws IOException ; void unpackSerializable( in string key, out Serializable value ) throws IOException; /** unpack arrays of values * It is possible to ensure an array is * in a certain order by passing in ordering and dimension * requirements. ordering should represent a value in the * sidl_array_ordering enumeration in sidlArray.h If either * argument is 0, it means there is no restriction on that * aspect. The rarray flag should be set if the array being * passed in is actually an rarray. The semantics are slightly * different for rarrays. The passed in array MUST be reused, * even if the array has changed bounds. */ void unpackBoolArray( in string key, out array<bool> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackCharArray( in string key, out array<char> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackIntArray( in string key, out array<int> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackLongArray( in string key, out array<long> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackOpaqueArray( in string key, out array<opaque> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackFloatArray( in string key, out array<float> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackDoubleArray( in string key, out array<double> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackFcomplexArray( in string key, out array<fcomplex> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackDcomplexArray( in string key, out array<dcomplex> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackStringArray( in string key, out array<string> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; void unpackGenericArray( in string key, out array<> value) throws IOException ; void unpackSerializableArray( in string key, out array<Serializable> value, in int ordering, in int dimen, in bool isRarray ) throws IOException ; } } //end package io /** * This package contains necessary interfaces for RMI protocols to * hook into Babel, plus a Protocol Factory class. The intention is * that authors of new protocols will create classes that implement * InstanceHandle, Invocation and Response (they could even have one * object that implements all three interfaces). */ package rmi { /** * Generic Network Exception */ class NetworkException extends sidl.io.IOException { int getHopCount(); } /** * This exception is thrown by the RMI library when a * host can not be found by a DNS lookup. */ class UnknownHostException extends NetworkException {} /** * This exception is normally thrown by the RMI library when the * server is started up and the port it is assigned to use is * already in use. */ class BindException extends NetworkException {} /** * This exception is thrown by the RMI library when an * attempt to connect to a remote host fails. */ class ConnectException extends NetworkException {} /** * This exception is thrown by the RMI library when a host * can be found by DNS, but is not reachable. It usually means * a router is down. */ class NoRouteToHostException extends NetworkException {} /** * This exception is thrown by the RMI library when a request * times out. */ class TimeOutException extends NetworkException {} /** * This exception is thrown by the RMI library when the network * unexpected loses it's connection. Can be caused by reset, * software connection abort, connection reset by peer, etc. */ class UnexpectedCloseException extends NetworkException {} /** * This exception is thrown by a server when a passed in object * id does not match any known object. */ class ObjectDoesNotExistException extends NetworkException {} /** * This exception is thrown by the RMI library when a passed in URL * is malformed. */ class MalformedURLException extends NetworkException {} /** * This is a base class for all protocol specific exceptions. */ class ProtocolException extends NetworkException {} /** * This singleton class keeps a table of string prefixes * (e.g. "babel" or "proteus") to protocol implementations. The * intent is to parse a URL (e.g. "babel://server:port/class") and * create classes that implement * <code>sidl.rmi.InstanceHandle</code>. */ class ProtocolFactory { /** * Associate a particular prefix in the URL to a typeName * <code>sidl.Loader</code> can find. The actual type is * expected to implement <code>sidl.rmi.InstanceHandle</code> * Return true iff the addition is successful. (no collisions * allowed) */ static bool addProtocol( in string prefix, in string typeName ) throws NetworkException; /** * Return the typeName associated with a particular prefix. * Return empty string if the prefix */ static string getProtocol( in string prefix ) throws NetworkException; /** * Remove a protocol from the active list. */ static bool deleteProtocol( in string prefix ) throws NetworkException; /** * Create a new remote object and return an instance handle for that * object. * The server and port number are in the url. Return nil * if protocol unknown or InstanceHandle.init() failed. */ static InstanceHandle createInstance( in string url, in string typeName ) throws NetworkException; /** * Create an new connection linked to an already existing * object on a remote server. The server and port number are in * the url, the objectID is the unique ID of the remote object * in the remote instance registry. Return null if protocol * unknown or InstanceHandle.init() failed. The boolean addRef * should be true if connect should remotely addRef */ static InstanceHandle connectInstance( in string url, in bool ar) throws NetworkException; } /** * This interface holds the state information for handles to * remote objects. Client-side messaging libraries are expected * to implement <code>sidl.rmi.InstanceHandle</code>, * <code>sidl.rmi.Invocation</code> and * <code>sidl.rmi.Response</code>. * * Every stub with a connection to a remote object holds a pointer * to an InstanceHandle that manages the connection. Multiple * stubs may point to the same InstanceHandle, however. Babel * takes care of the reference counting, but the developer should * keep concurrency issues in mind. * * When a new remote object is created: * sidl_rmi_InstanceHandle c = * sidl_rmi_ProtocolFactory_createInstance( url, typeName, * _ex ); * * When a new stub is created to connect to an existing remote * instance: * sidl_rmi_InstanceHandle c = * sidl_rmi_ProtocolFactory_connectInstance( url, _ex ); * * When a method is invoked: * sidl_rmi_Invocation i = * sidl_rmi_InstanceHandle_createInvocation( methodname ); * sidl_rmi_Invocation_packDouble( i, "input_val" , 2.0 ); * sidl_rmi_Invocation_packString( i, "input_str", "Hello" ); * ... * sidl_rmi_Response r = sidl_rmi_Invocation_invokeMethod( i ); * sidl_rmi_Response_unpackBool( i, "_retval", &succeeded ); * sidl_rmi_Response_unpackFloat( i, "output_val", &f ); * */ interface InstanceHandle { /** initialize a connection (intended for use by the * ProtocolFactory, (see above). This should parse the url and * do everything necessary to create the remote object. */ bool initCreate( in string url, in string typeName ) throws NetworkException; /** * initialize a connection (intended for use by the ProtocolFactory) * This should parse the url and do everything necessary to connect * to a remote object. */ bool initConnect( in string url, in bool ar) throws NetworkException; /** return the short name of the protocol */ string getProtocol() throws NetworkException; /** return the object ID for the remote object*/ string getObjectID() throws NetworkException; /** * return the full URL for this object, takes the form: * protocol://serviceID/objectID (where serviceID would = server:port * on TCP/IP) * So usually, like this: protocol://server:port/objectID */ string getObjectURL() throws NetworkException; /** create a serializer handle to invoke the named method */ Invocation createInvocation( in string methodName ) throws NetworkException; /** * closes the connection (called by the destructor, if not done * explicitly) returns true if successful, false otherwise * (including subsequent calls) */ bool close() throws NetworkException; } /** * This type is used to pack arguments and make the Client->Server * method invocation. */ interface Invocation extends sidl.io.Serializer { /** * this method is one of a triad. Only one of which * may be called, and it must the the last method called * in the object's lifetime. */ Response invokeMethod() throws NetworkException; /** * This method is second of the triad. It returns * a Ticket, from which a Response is later extracted. */ Ticket invokeNonblocking() throws NetworkException; /** * This method is third of the triad. It returns * and exception iff the invocation cannot be delivered * reliably. It does not wait for the invocation to * be acted upon and returns no values from the invocation. */ void invokeOneWay() throws NetworkException; } /** * This type is created when an invokeMethod is called on an * Invocation. It encapsulates all the results that users will * want to pull out of a remote method invocation. */ interface Response extends sidl.io.Deserializer { /** * May return a communication exception or an execption thrown * from the remote server. If it returns null, then it's safe * to unpack arguments */ sidl.BaseException getExceptionThrown() throws NetworkException; } /** * This interface is implemented by the Server side deserializer. * Deserializes method arguments in preperation for the method * call. */ interface Call extends sidl.io.Deserializer { } /** * This interface is implemented by the Server side serializer. * Serializes method arguments after the return from the method * call. */ interface Return extends sidl.io.Serializer { /** * This method serialized exceptions thrown on the server side * that should be returned to the client. Assumed to invalidate * in previously serialized arguments. (Also assumed that no * more arguments will be serialized.) */ void throwException(in sidl.BaseException ex_to_throw) throws NetworkException; } /** * Used in lieu of a Response in nonblocking calls */ interface Ticket { /** blocks until the Response is recieved */ void block(); /** * returns immediately: true iff the Response is already * received */ bool test(); /** creates an empty container specialized for Tickets */ TicketBook createEmptyTicketBook(); /** returns immediately: returns Response or null * (NOTE: needed for implementors of communication * libraries, not expected for general use). */ Response getResponse() throws NetworkException; } /** * This is a collection of Tickets that itself can be viewed * as a ticket. */ interface TicketBook extends Ticket { /** insert a ticket with a user-specified ID */ void insertWithID( in Ticket t, in int id ); /** insert a ticket and issue a unique ID */ int insert( in Ticket t ); /** remove a ready ticket from the TicketBook * returns 0 (and null) on an empty TicketBook */ int removeReady( out Ticket t ); /** * immediate, returns the number of Tickets in the book. */ bool isEmpty(); } /** * This singleton class is implemented by Babel's runtime for RMI * libraries to invoke methods on server objects. It maps * objectID strings to sidl_BaseClass objects and vice-versa. * * The InstanceRegistry creates and returns a unique string when a * new object is added to the registry. When an object's refcount * reaches 0 and it is collected, it is removed from the Instance * Registry. * * Objects are added to the registry in 3 ways: * 1) Added to the server's registry when an object is * create[Remote]'d. * 2) Implicity added to the local registry when an object is * passed as an argument in a remote call. * 3) A user may manually add a reference to the local registry * for publishing purposes. The user hsould keep a reference * to the object. Currently, the user cannot provide their own * objectID, this capability should probably be added. */ class InstanceRegistry { /** * Register an instance of a class. * * the registry will return an objectID string guaranteed to be * unique for the lifetime of the process */ static string registerInstance( in sidl.BaseClass instance ) throws NetworkException; /** * returns a handle to the class based on the unique objectID * string, (null if the handle isn't in the table) */ static sidl.BaseClass getInstanceString( in string instanceID ) throws NetworkException; /** * takes a class and returns the objectID string associated * with it. (null if the handle isn't in the table) */ static string getInstanceClass( in sidl.BaseClass instance ) throws NetworkException; /** * removes an instance from the table based on its objectID * string.. returns a pointer to the object, which must be * destroyed. */ static sidl.BaseClass removeInstanceString( in string instanceID ) throws NetworkException; /** * removes an instance from the table based on its BaseClass * pointer. returns the objectID string, which much be freed. */ static string removeInstanceClass( in sidl.BaseClass instance ) throws NetworkException; } /** * This singleton class is implemented by Babel's runtime for to * allow RMI downcasting of objects. When we downcast an RMI * object, we may be required to create a new derived class object * with a connect function. We store all the connect functions in * this table for easy access. * * This Class is for Babel internal use only. */ class ConnectRegistry { /** * The key is the SIDL classname the registered connect belongs * to. Multiple registrations under the same key are possible, * this must be protected against in the user code. Babel does * this internally with a static boolean. */ static void registerConnect( in string key, in opaque func); /** * Returns the connect method for the class named in the key */ static opaque getConnect( in string key ); /** * Returns the connect method for the class named in the key, * and removes it from the table. */ static opaque removeConnect( in string key ); } /** * ServerInfo is an interface (possibly implemented by the ORB * itself) that provides functions to deal with the problems * associated with passing local object remotely. It should be * registered with the ServerRegistry for general use. */ interface ServerInfo { string getServerURL(in string objID) throws NetworkException; /** * For internal Babel use ONLY. Needed by Babel to determine if * a url points to a local or remote object. Returns the * objectID if is local, Null otherwise. */ string isLocalObject(in string url) throws NetworkException; /** * This gets an array of logged exceptions. If an exception * can not be thrown back to the caller, we log it with the * Server. This gets the array of all those exceptions. THIS * IS SOMETHING OF A TEST! THIS MAY CHANGE! */ array<sidl.io.Serializable,1> getExceptions(); } /** * This singleton class is simply a place to register a * ServerInfo interface for general access. This ServerInfo * should give info about the ORB being used to export RMI objects * for the current Babel process. * * This Registry provides two important functions, a way to get * the URL for local object we wish to expose over RMI, and a way * to tell if an object passed to this process via RMI is actually * a local object. This abilities are protocol specific, the * ServerInfo interface must by implemented by the protocol * writer. * * THIS CLASS IS NOT DESIGNED FOR CONCURRENT WRITE ACCESS. (Only * one server is assumed per Babel process) */ class ServerRegistry { static void registerServer(in sidl.rmi.ServerInfo si) throws NetworkException; /** * Perhaps this should take BaseClass and look the objectID up in * the Instance Registry */ static string getServerURL(in string objID) throws NetworkException; /** * For internal Babel use ONLY. Needed by Babel to determine if a * url points to a local or remote object. Returns the objectID * if is local, Null otherwise. */ static string isLocalObject(in string url) throws NetworkException; /** * This gets an array of logged exceptions. If an exception * can not be thrown back to the caller, we log it with the * Server. This gets the array of all those exceptions. THIS * IS SOMETHING OF A TEST! THIS MAY CHANGE! */ static array<sidl.io.Serializable,1> getExceptions(); } /** This is the basic interface that all RMI servers should implement.*/ interface BaseServer { /** * The url string is necessary to give the server the info it * needs to start up. The string is protocol dependant. In * most TCP/IP based protocols, only the port number is really * required, but it is suggested they accept a full url of the * form: protocol://localhost:port */ void init(in string url) throws sidl.rmi.NetworkException; /** * Starts the server running. It is expected that most servers * will be threaded, and this function returns a long that can * be used as a server thread id to join to is necessary. */ long run() throws sidl.rmi.NetworkException; } } //end package rmi }