Interfaces

The SIDL runtime library provides six sets of interfaces:

Base
The base class, interface, and exception upon which all Babel-enabled software builds.
Contract Enforcement
Contract enforcement policy class and contract clause exceptions used to establish enforcement options and identify, at runtime, contract clause violations, respectively.
Library Handler
The DLL and Loader classes facilitate dynamic loading of objects at runtime.
Introspection
The ClassInfo interface and ClassInfoI class enable checking meta-data associated with a class.
I/O
The input-output package used for serializing and deserializing SIDL types.
RMI
The rmi package used for managing remote method invocations.

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
}





babel-1.4.0
users_guide Last Modified 2008-10-16

http://www.llnl.gov/CASC/components
components@llnl.gov