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
}