The interfaces for the runtime library, as described in SIDL, are:
//
// File: sidl.sidl
// Release: $Name: $
// Revision: @(#) $Revision: 4460 $
// Date: $Date: 2005-03-23 11:12:04 -0800 (Wed, 23 Mar 2005) $
// Description: SIDL interface description for the basic SIDL run-time library
//
// Copyright (c) 2001, The Regents of the University of Calfornia.
// Produced at the Lawrence Livermore National Laboratory.
// Written by the Components Team <components@llnl.gov>
// UCRL-CODE-2002-054
// All rights reserved.
//
// This file is part of Babel. For more information, see
// http://www.llnl.gov/CASC/components/. Please read the COPYRIGHT file
// for Our Notice and the LICENSE file for the GNU Lesser General Public
// License.
//
// This program is free software; you can redistribute it and/or modify it
// under the terms of the GNU Lesser General Public License (as published by
// the Free Software Foundation) version 2.1 dated February 1999.
//
// This program is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
// conditions of the GNU Lesser General Public License for more details.
//
// You should have recieved a copy of the GNU Lesser General Public License
// along with this program; if not, write to the Free Software Foundation,
// Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
/**
* The <code>SIDL</code> package contains the fundamental type and interface
* definitions for the <code>SIDL</code> interface definition language. It
* defines common run-time libraries and common base classes and interfaces.
* Every interface implicitly inherits from <code>sidl.BaseInterface</code>
* and every class implicitly inherits from <code>sidl.BaseClass</code>.
*
*/
package sidl version 0.9.0 {
/**
* 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);
/**
* Check whether the object can support the specified interface or
* class. If the <code>SIDL</code> type name in <code>name</code>
* is supported, then a reference to that object is returned with the
* reference count incremented. The callee will be responsible for
* calling <code>deleteRef</code> on the returned object. If
* the specified type is not supported, then a null reference is
* returned.
*/
BaseInterface queryInt(in string name);
/**
* 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);
/**
* Check whether the object can support the specified interface or
* class. If the <code>SIDL</code> type name in <code>name</code>
* is supported, then a reference to that object is returned with the
* reference count incremented. The callee will be responsible for
* calling <code>deleteRef</code> on the returned object. If
* the specified type is not supported, then a null reference is
* returned.
*/
BaseInterface queryInt(in string name);
/**
* 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();
}
/**
* Every exception implements <code>BaseException</code>. This interface
* declares the basic functionality to get and set error messages and stack
* traces.
*/
interface BaseException {
/**
* 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);
}
/**
* <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 {
}
/**
* When loading a dynamically linked library, there are three
* settings: LOCAL, GLOBAL and SCLSCOPE.
*/
enum Scope {
/** Attempt to load the symbols into a local namespace. */
LOCAL,
/** Attempt to load the symbols into the global namespace. */
GLOBAL,
/** Use the scope setting from the SCL file. */
SCLSCOPE
}
/**
* When loading a dynmaically linked library, there are three
* settings: LAZY, NOW, SCLRESOLVE
*/
enum Resolve {
/** Resolve symbols on an as needed basis. */
LAZY,
/** Resolve all symbols at load time. */
NOW,
/** Use the resolve setting from the SCL file. */
SCLRESOLVE
}
/**
* The <code>DLL</code> class encapsulates access to a single
* dynamically linked library. DLLs are loaded at run-time using
* the <code>loadLibrary</code> method and later unloaded using
* <code>unloadLibrary</code>. Symbols in a loaded library are
* resolved to an opaque pointer by method <code>lookupSymbol</code>.
* Class instances are created by <code>createClass</code>.
*/
class DLL {
/**
* Load a dynamic link library using the specified URI. The
* URI may be of the form "main:", "lib:", "file:", "ftp:", or
* "http:". A URI that starts with any other protocol string
* is assumed to be a file name. The "main:" URI creates a
* library that allows access to global symbols in the running
* program's main address space. The "lib:X" URI converts the
* library "X" into a platform-specific name (e.g., libX.so) and
* loads that library. The "file:" URI opens the DLL from the
* specified file path. The "ftp:" and "http:" URIs copy the
* specified library from the remote site into a local temporary
* file and open that file. This method returns true if the
* DLL was loaded successfully and false otherwise. Note that
* the "ftp:" and "http:" protocols are valid only if the W3C
* WWW library is available.
*
* @param uri the URI to load. This can be a .la file
* (a metadata file produced by libtool) or
* a shared library binary (i.e., .so,
* .dll or whatever is appropriate for your
* OS)
* @param loadGlobally <code>true</code> means that the shared
* library symbols will be loaded into the
* global namespace; <code>false</code>
* means they will be loaded into a
* private namespace. Some operating systems
* may not be able to honor the value presented
* here.
* @param loadLazy <code>true</code> instructs the loader to
* that symbols can be resolved as needed (lazy)
* instead of requiring everything to be resolved
* now (at load time).
*/
bool loadLibrary(in string uri,
in bool loadGlobally,
in bool loadLazy);
/**
* Get the library name. This is the name used to load the
* library in <code>loadLibrary</code> except that all file names
* contain the "file:" protocol.
*/
string getName();
/**
* Unload the dynamic link library. The library may no longer
* be used to access symbol names. When the library is actually
* unloaded from the memory image depends on details of the operating
* system.
*/
void unloadLibrary();
/**
* Lookup a symbol from the DLL and return the associated pointer.
* A null value is returned if the name does not exist.
*/
opaque lookupSymbol(in string linker_name);
/**
* Create an instance of the SIDL class. If the class constructor
* is not defined in this DLL, then return null.
*/
BaseClass createClass(in string sidl_name);
}
/**
* 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 search 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 {
/**
* 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.
*/
static 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.
*/
static 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.
*/
static void addSearchPath(in string path_fragment);
/**
* 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.
*
* @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);
}
/**
* This provides an interface to the meta-data available on the
* class.
*/
interface ClassInfo {
/**
* Return the name of the class.
*/
string getName();
/**
* Get the version of the intermediate object representation.
* This will be in the form of major_version.minor_version.
*/
string getIORVersion();
}
/**
* An implementation of the <code>ClassInfo</code> interface. This provides
* methods to set all the attributes that are read-only in the
* <code>ClassInfo</code> interface.
*/
class ClassInfoI implements-all ClassInfo {
/**
* Set the name of the class.
*/
final void setName(in string name);
/**
* Set the IOR major and minor version numbers.
*/
final void setIORVersion(in int major, in int minor);
}
}