The interfaces for the runtime library, as described in SIDL, are:
// // File: sidl.sidl // Revision: @(#) $Revision: 6563 $ // Date: $Date: 2008-10-16 15:03:20 -0700 (Thu, 16 Oct 2008) $ // Description: sidl interface description for the basic sidl run-time library // // Copyright (c) 2001-2007, 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>. * */ final package sidl version 0.9.17 { /** * 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> indicates an assertion within a precondition * clause of the interface contract has been violated. */ class PreViolation extends SIDLException implements RuntimeException { } /** * <code>PostViolation</code> indicates an assertion within a postcondition * clause of the interface contract has been violated. */ class PostViolation extends SIDLException implements RuntimeException { } /** * <code>InvViolation</code> indicates an assertion within a invariant * clause of the interface contract has been violated. */ class InvViolation extends SIDLException implements RuntimeException { } /** * Contract clause types. */ enum ClauseType { INVARIANT, PRECONDITION, POSTCONDITION, }; /** * Contract classification. The classification is used to filter * contract clauses by the corresponding characteristic(s). */ enum ContractClass { /** * All classifications of interface contract clauses. */ ALLCLASSES, /** * Only constant-time complexity, or O(1), clauses. */ CONSTANT, /** * Only cubic-time complexity, or O(n^3), clauses. */ CUBIC, /** * Only invariant clauses. */ INVARIANTS, /** * Invariant plus postcondition clauses. */ INVPOST, /** * Invariant plus precondition clauses. */ INVPRE, /** * Only linear-time complexity, or O(n), clauses. */ LINEAR, /** * Method calls. Only clauses containing at least one method call. */ METHODCALLS, /** * Only postcondition clauses. */ POSTCONDS, /** * Only precondition clauses. */ PRECONDS, /** * Precondition plus postcondition clauses. */ PREPOST, /** * Only quadratic-time complexity, or O(n^2), clauses. */ QUADRATIC, /** * Only quartic-time complexity, or O(n^4), clauses. */ QUARTIC, /** * Only quintic-time complexity, or O(n^5), clauses. */ QUINTIC, /** * Results. Only clauses containing at least one assertion on an * in, inout, or result argument. */ RESULTS, /** * Only septic-time complexity, or O(n^7), clauses. */ SEPTIC, /** * Only sextic-time complexity, or O(n^6), clauses. */ SEXTIC, /** * Simple expressions. Only clauses consisting solely of * simple expressions (i.e., no method calls). */ SIMPLEEXPRS, }; /** * Contract clause enforcement frequency. */ enum EnforceFreq { /** * Never. Disable enforcement by completely by-passing checks * regardless of the selected contract classification. */ NEVER, /** * Always. Every clause of the selected contract classification * is enforced. */ ALWAYS, /** * Adaptive fit. Check clauses of the selected contract classification * only if they will not result in exceeding the overhead limit based * on accumulations of estimated execution times. */ ADAPTFIT, /** * Adaptive timing. Check clauses of the selected contract classification * only if their estimated execution time is within the overhead limit * applied to the estimated time of the corresponding method. */ ADAPTTIMING, /** * Periodic. Check clauses of the selected contract classification * at the specified interval. */ PERIODIC, /** * Random. Check clauses of the selected contract classifcation on a * random basis using the specified maximum. */ RANDOM, /** * Simulated Annealing. Essentially Adaptive fit but checks are * allowed to randomly exceed the overhead limit with decreasing * probability over time. */ SIMANNEAL, }; /** * Contract enforcement tracing levels. Enforcement traces rely on * runtime timing automatically inserted within the middleware. */ enum EnfTraceLevel { /** * None. No tracing is to be performed. */ NONE, /** * Core. Time trace start and end only. This can be useful for * simple program timing. */ CORE, /** * Basic enforcement tracing. CORE plus interface contract clause timing. */ BASIC, /** * Overhead of enforcement decisions. BASIC plus timing of * enforcement decisions. (Experimental feature.) */ OVERHEAD, }; /** * <code>EnfPolicy</code> maintains the current interface * contract enforcement policy. */ class EnfPolicy { /** * Sets the enforcement policy to always check the specified * type(s) of contracts. This is equivalent to calling * setPolicy() with ALWAYS as the enforcement frequency * and the specified (or default) contract class. * * @param contractClass Contract classification * [Default = ALLCLASSES] * @param clearStats TRUE if enforcement statistics are to be * cleared; FALSE otherwise. */ static void setEnforceAll(in ContractClass contractClass, in bool clearStats); /** * Sets the policy options to disable all contract enforcement. * This is equivalent to calling setPolicy() with NEVER as the * enforcement frequency. * * @param clearStats TRUE if enforcement statistics are to be * cleared; FALSE otherwise. */ static void setEnforceNone(in bool clearStats); /** * Sets enforcement policy and options. This method should be * invoked directly to avoid the default enforcement behavior. * * @param contractClass Contract classification * [Default = ALLCLASSES] * @param enforceFreq Enforcement frequency * [Default = ALWAYS] * @param interval Sampling interval representing the * period (for PERIODIC) or maximum * random number/window (for RANDOM) * [Default = 0 if negative specified] * @param overheadLimit Limit on performance overhead [0.0 .. 1.0) * [Default = 0.0 (or 0%) if negative] * @param appAvgPerCall Average extra, application-specific * execution time, normalized by calls * to annotated methods * [Default = 0.0 if negative] * @param annealLimit Limit on simulated annealing function * to ensure its termination * (0.0 .. 2.72] * [Default = 2.72 if negative specified] * @param clearStats TRUE if enforcement statistics are to be * cleared; FALSE otherwise. */ static void setPolicy(in ContractClass contractClass, in EnforceFreq enforceFreq, in int interval, in double overheadLimit, in double appAvgPerCall, in double annealLimit, in bool clearStats); /** * Returns TRUE if contract enforcement is enabled; FALSE otherwise. */ static bool areEnforcing(); /** * Returns the contract classification policy option. */ static ContractClass getContractClass(); /** * Returns the enforcement frequency policy option. */ static EnforceFreq getEnforceFreq(); /** * Returns the interval for PERIODIC (i.e., the interval) or * RANDOM (i.e., the maximum random number). Returns 0 by default. */ static int getSamplingInterval(); /** * Returns the desired enforcement overhead limit for * performance-driven frequency options (i.e., ADAPTFIT, * ADAPTTIMING, and SIMANNEAL). Returns 0.0 by default. */ static double getOverheadLimit(); /** * Returns the average assumed execution time associated * with the program or application. Returns 0.0 by default. */ static double getAppAvgPerCall(); /** * Returns the annealing limit for SIMANNEAL enforcement * frequency option. Returns 0.0 by default. */ static double getAnnealLimit(); /** * Returns the name, or description, of the enforcement policy. * The caller is responsible for calling sidl_String_free() * on the name when done with it. * * @param useAbbrev TRUE if the abbreviated name is to be * returned. */ static string getPolicyName(in bool useAbbrev); /** * Prints statistics data to the file with the specified name. * The file is opened (for append) and closed on each call. * * @param filename Name of the file to which the statistics * data should be written. * @param header TRUE if the header line is to be printed * prior to the statistics line (for compressed * output only). * @param prefix String description for identifying information, * if any, intended to preceed the statistics * data. Useful for distinguishing between * different objects, for example. * @param compressed TRUE if the enforcer state is to be dumped * on a single line with semi-colon separators * between fields. */ static void dumpStats(in string filename, in bool header, in string prefix, in bool compressed); /** * Starts enforcement trace file generation. * * @param filename Name of the destination trace file. * @param traceLevel Level of trace timing and reporting required. * [Default = NONE] */ static void startTrace(in string filename, in EnfTraceLevel traceLevel); /** * Returns TRUE if contract enforcement tracing is enabled; * FALSE otherwise. */ static bool areTracing(); /** * Returns the name of the trace file. If one was not provided, * the default name is returned. */ static string getTraceFilename(); /** * Returns the level of enforcement tracing. */ static EnfTraceLevel getTraceLevel(); /** * Terminates enforcement trace file generation. Takes a final * timestamp and logs the remaining trace information. */ static void endTrace(); } /** * 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(); /** * Return true if the library was loaded into the global namespace. */ bool isGlobal(); /** * Return true if the library was loaded using lazy symbol resolution. */ bool isLazy(); /** * 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(); /** * Return the version number of the class. This should be a string * with a sequence of numbers separated by periods. */ string getVersion(); /** * 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 version number of the class. */ final void setVersion(in string ver); /** * 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. This exception is special in that it avoids any memory * allocation. For this reason, the trace or note may be truncated * to fit in the preallocated buffers. */ class MemAllocException extends sidl.SIDLException implements RuntimeException { /** * Returns the preallocated copy of this exception. Any * failure of memory allocation should throw the exception returned * by this method to avoid further allocation failures. */ static MemAllocException getSingletonException(); /** * 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); } /** * 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 Exception is thrown when a method is called that an * implmentation has not been written for yet. The throw code is * placed into the _Impl files automatically when they are generated. */ class NotImplementedException 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 ) ; void packChar( in string key, in char value ) ; void packInt( in string key, in int value ) ; void packLong( in string key, in long value ) ; void packOpaque( in string key, in opaque value ) ; void packFloat( in string key, in float value ) ; void packDouble( in string key, in double value ) ; void packFcomplex( in string key, in fcomplex value ) ; void packDcomplex( in string key, in dcomplex value ) ; void packString( in string key, in string value ) ; void packSerializable( in string key, in Serializable value ) ; /** * 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 ); void packCharArray( in string key, in array<char> value, in int ordering, in int dimen, in bool reuse_array ); void packIntArray( in string key, in array<int> value, in int ordering, in int dimen, in bool reuse_array ); void packLongArray( in string key, in array<long> value, in int ordering, in int dimen, in bool reuse_array ); void packOpaqueArray( in string key, in array<opaque> value, in int ordering, in int dimen, in bool reuse_array ); void packFloatArray( in string key, in array<float> value, in int ordering, in int dimen, in bool reuse_array ); void packDoubleArray( in string key, in array<double> value, in int ordering, in int dimen, in bool reuse_array ); void packFcomplexArray( in string key, in array<fcomplex> value, in int ordering, in int dimen, in bool reuse_array ); void packDcomplexArray( in string key, in array<dcomplex> value, in int ordering, in int dimen, in bool reuse_array ); void packStringArray( in string key, in array<string> value, in int ordering, in int dimen, in bool reuse_array ); void packGenericArray( in string key, in array<> value, in bool reuse_array ); void packSerializableArray( in string key, in array<Serializable> value, in int ordering, in int dimen, in bool reuse_array ); } /** * Standard interface for unpacking Babel types */ interface Deserializer { /* unpack values */ void unpackBool( in string key, inout bool value ); void unpackChar( in string key, inout char value ); void unpackInt( in string key, inout int value ); void unpackLong( in string key, inout long value ); void unpackOpaque( in string key, inout opaque value ); void unpackFloat( in string key, inout float value ); void unpackDouble( in string key, inout double value ); void unpackFcomplex( in string key, inout fcomplex value ); void unpackDcomplex( in string key, inout dcomplex value ); void unpackString( in string key, inout string value ); void unpackSerializable( in string key, inout Serializable value ); /** 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, inout array<bool> value, in int ordering, in int dimen, in bool isRarray ); void unpackCharArray( in string key, inout array<char> value, in int ordering, in int dimen, in bool isRarray ); void unpackIntArray( in string key, inout array<int> value, in int ordering, in int dimen, in bool isRarray ); void unpackLongArray( in string key, inout array<long> value, in int ordering, in int dimen, in bool isRarray ); void unpackOpaqueArray( in string key, inout array<opaque> value, in int ordering, in int dimen, in bool isRarray ); void unpackFloatArray( in string key, inout array<float> value, in int ordering, in int dimen, in bool isRarray ); void unpackDoubleArray( in string key, inout array<double> value, in int ordering, in int dimen, in bool isRarray ); void unpackFcomplexArray( in string key, inout array<fcomplex> value, in int ordering, in int dimen, in bool isRarray ); void unpackDcomplexArray( in string key, inout array<dcomplex> value, in int ordering, in int dimen, in bool isRarray ); void unpackStringArray( in string key, inout array<string> value, in int ordering, in int dimen, in bool isRarray ); void unpackGenericArray( in string key, inout array<> value); void unpackSerializableArray( in string key, inout array<Serializable> value, in int ordering, in int dimen, in bool isRarray ); } } //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(); void packObj( in sidl.io.Serializer ser ); void unpackObj( in sidl.io.Deserializer des ); void setErrno(in int err); int getErrno(); } /** * 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 exception thrown when one attempts to pass a local object remotely but * there is no local server running to serve the object */ class NoServerException 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 ); /** * Return the typeName associated with a particular prefix. * Return empty string if the prefix */ static string getProtocol( in string prefix ); /** * Remove a protocol from the active list. */ static bool deleteProtocol( in string prefix ); /** * 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 ); /** * 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 string typeName, in bool ar); /** * Request that a remote object be serialized to you. 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. */ static sidl.io.Serializable unserializeInstance( in string url); } /** * 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 ); /** * 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 string typeName, in bool ar); /** Get a connection specifically for the purpose for requesting a * serialization of a remote object (intended for use by the * ProtocolFactory, (see above). This should parse the url and * request the object. It should return a deserializer.. */ sidl.io.Serializable initUnserialize( in string url); /** return the short name of the protocol */ string getProtocol(); /** return the object ID for the remote object*/ string getObjectID(); /** * 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(); /** create a serializer handle to invoke the named method */ Invocation createInvocation( in string methodName ); /** * closes the connection (called by the destructor, if not done * explicitly) returns true if successful, false otherwise * (including subsequent calls) */ bool close(); } /** * 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(); /** * This method is second of the triad. It returns * a Ticket, from which a Response is later extracted. */ Ticket invokeNonblocking(); /** * 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(); } /** * 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(); } /** * 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); } /** * 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(); } /** * 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 ); /** * Register an instance of a class with the given instanceID * * If a different object already exists in registry under * the supplied name, a false is returned, if the object was * successfully registered, true is returned. */ static string registerInstance[ByString]( in sidl.BaseClass instance, in string instanceID); /** * returns a handle to the class based on the unique objectID * string, (null if the handle isn't in the table) */ static sidl.BaseClass getInstance[ByString]( in string instanceID ); /** * takes a class and returns the objectID string associated * with it. (null if the handle isn't in the table) */ static string getInstance[ByClass]( in sidl.BaseClass instance ); /** * removes an instance from the table based on its objectID * string.. returns a pointer to the object, which must be * destroyed. */ static sidl.BaseClass removeInstance[ByString]( in string instanceID ); /** * removes an instance from the table based on its BaseClass * pointer. returns the objectID string, which much be freed. */ static string removeInstance[ByClass]( in sidl.BaseClass instance ); } /** * 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); /** * 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); /** * 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 { /** * Register the server with the ServerRegistry. */ static void registerServer(in sidl.rmi.ServerInfo si); /** * Get the registered server from the Server Registery. */ static sidl.rmi.ServerInfo getServer(); /** * Perhaps this should take BaseClass and look the objectID up in * the Instance Registry */ static string getServerURL(in string objID); /** * 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); /** * 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(); } } //end package rmi }