Interfaces

The SIDL runtime library provides three sets of interfaces:

Base
The base class, interface, and exception upon which all Babel-enabled software builds.
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.

The interfaces for the runtime library, as described in SIDL, are:


//
// File:        sidl.sidl
// Revision:    @(#) $Revision: 5162 $
// Date:        $Date: 2005-12-20 10:14:46 -0800 (Tue, 20 Dec 2005) $
// Description: sidl interface description for the basic sidl run-time library
// 
// Copyright (c) 2001, The Regents of the University of Calfornia.
// Produced at the Lawrence Livermore National Laboratory.
// Written by the Components Team <components@llnl.gov>
// UCRL-CODE-2002-054
// All rights reserved.
// 
// This file is part of Babel. For more information, see
// http://www.llnl.gov/CASC/components/. Please read the COPYRIGHT file
// for Our Notice and the LICENSE file for the GNU Lesser General Public
// License.
// 
// This program is free software; you can redistribute it and/or modify it
// under the terms of the GNU Lesser General Public License (as published by
// the Free Software Foundation) version 2.1 dated February 1999.
// 
// This program is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
// conditions of the GNU Lesser General Public License for more details.
// 
// You should have recieved a copy of the GNU Lesser General Public License
// along with this program; if not, write to the Free Software Foundation,
// Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

/**
 * The <code>sidl</code> package contains the fundamental type and interface
 * definitions for the <code>sidl</code> interface definition language.  It
 * defines common run-time libraries and common base classes and interfaces.
 * Every interface implicitly inherits from <code>sidl.BaseInterface</code>
 * and every class implicitly inherits from <code>sidl.BaseClass</code>.
 * 
 */
package sidl version 0.9.12 {

  /**
   * Every interface in <code>sidl</code> implicitly inherits
   * from <code>BaseInterface</code>, and it is implemented
   * by <code>BaseClass</code> below.
   */
  interface BaseInterface {

    /**
     * <p>
     * Add one to the intrinsic reference count in the underlying object.
     * Object in <code>sidl</code> have an intrinsic reference count.
     * Objects continue to exist as long as the reference count is
     * positive. Clients should call this method whenever they
     * create another ongoing reference to an object or interface.
     * </p>
     * <p>
     * This does not have a return value because there is no language
     * independent type that can refer to an interface or a
     * class.
     * </p>
     */
    void addRef();

    /**
     * Decrease by one the intrinsic reference count in the underlying
     * object, and delete the object if the reference is non-positive.
     * Objects in <code>sidl</code> have an intrinsic reference count.
     * Clients should call this method whenever they remove a
     * reference to an object or interface.
     */
    void deleteRef();

    /**
     * Return true if and only if <code>obj</code> refers to the same
     * object as this object.
     */
    bool isSame(in BaseInterface iobj);

    /**
     * Return whether this object is an instance of the specified type.
     * The string name must be the <code>sidl</code> type name.  This
     * routine will return <code>true</code> if and only if a cast to
     * the string type name would succeed.
     */
    bool isType(in string name);

    /**
     * Return the meta-data about the class implementing this interface.
     */
    ClassInfo getClassInfo();
  }

  /**
   * Every class implicitly inherits from <code>BaseClass</code>.  This
   * class implements the methods in <code>BaseInterface</code>.
   */
  class BaseClass implements BaseInterface {
    /**
     * <p>
     * Add one to the intrinsic reference count in the underlying object.
     * Object in <code>sidl</code> have an intrinsic reference count.
     * Objects continue to exist as long as the reference count is
     * positive. Clients should call this method whenever they
     * create another ongoing reference to an object or interface.
     * </p>
     * <p>
     * This does not have a return value because there is no language
     * independent type that can refer to an interface or a
     * class.
     * </p>
     */
    final void addRef();

    /**
     * Decrease by one the intrinsic reference count in the underlying
     * object, and delete the object if the reference is non-positive.
     * Objects in <code>sidl</code> have an intrinsic reference count.
     * Clients should call this method whenever they remove a
     * reference to an object or interface.
     */
    final void deleteRef();

    /**
     * Return true if and only if <code>obj</code> refers to the same
     * object as this object.
     */
    final bool isSame(in BaseInterface iobj);

    /**
     * Return whether this object is an instance of the specified type.
     * The string name must be the <code>sidl</code> type name.  This
     * routine will return <code>true</code> if and only if a cast to
     * the string type name would succeed.
     */
    bool isType(in string name);

    /**
     * Return the meta-data about the class implementing this interface.
     */
    final ClassInfo getClassInfo();
  }

  /** 
   * This package has some I/O capability that's not core to the 
   * SIDL object model, but still needed by parts of the generated code
   */
  package io { 
   /**
    *	 Objects that implement Serializable will be serializable (copyable)
    * over RMI, or storable to streams.  Classes that can pack or unpack 
    *  themselves should implement this interface
    */ 
    interface Serializable { 
      void packObj( in Serializer ser );
      void unpackObj( in Deserializer des );
    } 
  }

  /**
   * Every exception implements <code>BaseException</code>. This interface
   * declares the basic functionality to get and set error messages and stack
   * traces.
   */
  interface BaseException extends sidl.io.Serializable{

    /**
     * Return the message associated with the exception.
     */
    string getNote();

    /**
     * Set the message associated with the exception.
     */
    void setNote(in string message);

    /**
     * Returns formatted string containing the concatenation of all 
     * tracelines.
     */
    string getTrace();

    /**
     * Adds a stringified entry/line to the stack trace.
     */
    void add[Line](in string traceline);

    /**
     * Formats and adds an entry to the stack trace based on the 
     * file name, line number, and method name.
     */
    void add(in string filename, in int lineno, in string methodname);
  }

  /**
   * This exception type is the default exception for every method.
   * 
   */
  interface RuntimeException extends BaseException {}

  /**
   * <code>SIDLException</code> provides the basic functionality of the
   * <code>BaseException</code> interface for getting and setting error
   * messages and stack traces.
   */
  class SIDLException implements-all BaseException {
  }

  /**
   * <code>PreViolation</code> provides the basic marker for 
   * a pre-condition exception.
   */
  class PreViolation extends SIDLException implements RuntimeException {
  }

  /**
   * <code>PostViolation</code> provides the basic marker for 
   * a post-condition exception.
   */
  class PostViolation extends SIDLException implements RuntimeException {
  }

  /**
   * <code>InvViolation</code> provides the basic marker for 
   * a invariant exception.
   */
  class InvViolation extends SIDLException implements RuntimeException {
  }

  /**
   * When loading a dynamically linked library, there are three 
   * settings: LOCAL, GLOBAL and SCLSCOPE.
   */
  enum Scope {
     /** Attempt to load the symbols into a local namespace. */
     LOCAL,
     /** Attempt to load the symbols into the global namespace. */
     GLOBAL,
     /** Use the scope setting from the SCL file. */
     SCLSCOPE
  }

  /**
   * When loading a dynmaically linked library, there are three
   * settings: LAZY, NOW, SCLRESOLVE
   */
   enum Resolve {
     /** Resolve symbols on an as needed basis. */
     LAZY,
     /** Resolve all symbols at load time. */
     NOW,
     /** Use the resolve setting from the SCL file. */
     SCLRESOLVE
   }

  /**
   * The <code>DLL</code> class encapsulates access to a single
   * dynamically linked library.  DLLs are loaded at run-time using
   * the <code>loadLibrary</code> method and later unloaded using
   * <code>unloadLibrary</code>.  Symbols in a loaded library are
   * resolved to an opaque pointer by method <code>lookupSymbol</code>.
   * Class instances are created by <code>createClass</code>.
   */
  class DLL {

    /**
     * Load a dynamic link library using the specified URI.  The
     * URI may be of the form "main:", "lib:", "file:", "ftp:", or
     * "http:".  A URI that starts with any other protocol string
     * is assumed to be a file name.  The "main:" URI creates a
     * library that allows access to global symbols in the running
     * program's main address space.  The "lib:X" URI converts the
     * library "X" into a platform-specific name (e.g., libX.so) and
     * loads that library.  The "file:" URI opens the DLL from the
     * specified file path.  The "ftp:" and "http:" URIs copy the
     * specified library from the remote site into a local temporary
     * file and open that file.  This method returns true if the
     * DLL was loaded successfully and false otherwise.  Note that
     * the "ftp:" and "http:" protocols are valid only if the W3C
     * WWW library is available.
     *
     * @param uri          the URI to load. This can be a .la file
     *                     (a metadata file produced by libtool) or
     *                     a shared library binary (i.e., .so,
     *                     .dll or whatever is appropriate for your
     *                     OS)
     * @param loadGlobally <code>true</code> means that the shared
     *                     library symbols will be loaded into the
     *                     global namespace; <code>false</code> 
     *                     means they will be loaded into a 
     *                     private namespace. Some operating systems
     *                     may not be able to honor the value presented
     *                     here.
     * @param loadLazy     <code>true</code> instructs the loader to
     *                     that symbols can be resolved as needed (lazy)
     *                     instead of requiring everything to be resolved
     *                     now (at load time).
     */
    bool loadLibrary(in string uri,
                     in bool loadGlobally,
                     in bool loadLazy);

    /**
     * Get the library name.  This is the name used to load the
     * library in <code>loadLibrary</code> except that all file names
     * contain the "file:" protocol.
     */
    string getName();

    /**
     * Unload the dynamic link library.  The library may no longer
     * be used to access symbol names.  When the library is actually
     * unloaded from the memory image depends on details of the operating
     * system.
     */
    void unloadLibrary();

    /**
     * Lookup a symbol from the DLL and return the associated pointer.
     * A null value is returned if the name does not exist.
     */
    opaque lookupSymbol(in string linker_name);

    /**
     * Create an instance of the sidl class.  If the class constructor
     * is not defined in this DLL, then return null.
     */
    BaseClass createClass(in string sidl_name);
  }

  /**
   * Interface <code>Finder</code> is an interface for classes that resolve 
   * dynamic libraries.  
   * Class <code>Loader</code> takes one of these interfaces through the 
   * method <code>setFinder</code>.  If NULL is passed to setFinder, the 
   * class <code>DefaultFinder</code> is used.
   */
  interface Finder {
    /**
     * Find a DLL containing the specified information for a sidl
     * class. This method searches through the files in set set path
     * looking for a shared library that contains the client-side or IOR
     * for a particular sidl class.
     *
     * @param sidl_name  the fully qualified (long) name of the
     *                   class/interface to be found. Package names
     *                   are separated by period characters from each
     *                   other and the class/interface name.
     * @param target     to find a client-side binding, this is
     *                   normally the name of the language.
     *                   To find the implementation of a class
     *                   in order to make one, you should pass
     *                   the string "ior/impl" here.
     * @param lScope     this specifies whether the symbols should
     *                   be loaded into the global scope, a local
     *                   scope, or use the setting in the file.
     * @param lResolve   this specifies whether symbols should be
     *                   resolved as needed (LAZY), completely
     *                   resolved at load time (NOW), or use the
     *                   setting from the file.
     * @return a non-NULL object means the search was successful.
     *         The DLL has already been added.
     */
    DLL findLibrary(in string  sidl_name,
                           in string  target,
                           in Scope   lScope,
                           in Resolve lResolve);

    /**
     * Set the search path, which is a semi-colon separated sequence of
     * URIs as described in class <code>DLL</code>.  This method will
     * invalidate any existing search path.
     */
    void setSearchPath(in string path_name);

    /**
     * Return the current search path.  If the search path has not been
     * set, then the search path will be taken from environment variable
     * SIDL_DLL_PATH.
     */
    string getSearchPath();

    /**
     * Append the specified path fragment to the beginning of the
     * current search path.  If the search path has not yet been set
     * by a call to <code>setSearchPath</code>, then this fragment will
     * be appended to the path in environment variable SIDL_DLL_PATH.
     */
    void addSearchPath(in string path_fragment);

  }

  /**
   *  This class is the Default Finder.  If no Finder is set in class Loader,
   *  this finder is used.  It uses SCL files from the filesystem to
   *  resolve dynamic libraries.
   *
   * The initial search path is taken from the SIDL_DLL_PATH
   * environment variable.
   */

  class DFinder implements-all Finder {
  }


  /**
   * Class <code>Loader</code> manages dyanamic loading and symbol name
   * resolution for the sidl runtime system.  The <code>Loader</code> class
   * manages a library search path and keeps a record of all libraries
   * loaded through this interface, including the initial "global" symbols
   * in the main program.
   * 
   * Unless explicitly set, the <code>Loader</code> uses the default
   * <code>sidl.Finder</code> implemented in <code>sidl.DFinder</code>.
   * This class searches the filesystem for <code>.scl</code> files when
   * trying to find a class. The initial path is taken from the
   * environment variable SIDL_DLL_PATH, which is a semi-colon
   * separated sequence of URIs as described in class <code>DLL</code>.
   */
  class Loader {

    /**
     * Load the specified library if it has not already been loaded.
     * The URI format is defined in class <code>DLL</code>.  The search
     * path is not searched to resolve the library name.
     *
     * @param uri          the URI to load. This can be a .la file
     *                     (a metadata file produced by libtool) or
     *                     a shared library binary (i.e., .so,
     *                     .dll or whatever is appropriate for your
     *                     OS)
     * @param loadGlobally <code>true</code> means that the shared
     *                     library symbols will be loaded into the
     *                     global namespace; <code>false</code> 
     *                     means they will be loaded into a 
     *                     private namespace. Some operating systems
     *                     may not be able to honor the value presented
     *                     here.
     * @param loadLazy     <code>true</code> instructs the loader to
     *                     that symbols can be resolved as needed (lazy)
     *                     instead of requiring everything to be resolved
     *                     now.
     * @return if the load was successful, a non-NULL DLL object is returned.
     */
    static DLL loadLibrary(in string uri,
                           in bool loadGlobally,
                           in bool loadLazy);

    /**
     * Append the specified DLL to the beginning of the list of already
     * loaded DLLs.
     */
    static void addDLL(in DLL dll);

    /**
     * Unload all dynamic link libraries.  The library may no longer
     * be used to access symbol names.  When the library is actually
     * unloaded from the memory image depends on details of the operating
     * system.
     */
    static void unloadLibraries();

    /**
     * Find a DLL containing the specified information for a sidl
     * class. This method searches SCL files in the search path looking
     * for a shared library that contains the client-side or IOR
     * for a particular sidl class.
     *
     * This call is implemented by calling the current
     * <code>Finder</code>. The default finder searches the local
     * file system for <code>.scl</code> files to locate the
     * target class/interface.
     *
     * @param sidl_name  the fully qualified (long) name of the
     *                   class/interface to be found. Package names
     *                   are separated by period characters from each
     *                   other and the class/interface name.
     * @param target     to find a client-side binding, this is
     *                   normally the name of the language.
     *                   To find the implementation of a class
     *                   in order to make one, you should pass
     *                   the string "ior/impl" here.
     * @param lScope     this specifies whether the symbols should
     *                   be loaded into the global scope, a local
     *                   scope, or use the setting in the SCL file.
     * @param lResolve   this specifies whether symbols should be
     *                   resolved as needed (LAZY), completely
     *                   resolved at load time (NOW), or use the
     *                   setting from the SCL file.
     * @return a non-NULL object means the search was successful.
     *         The DLL has already been added.
     */
    static DLL findLibrary(in string  sidl_name,
                           in string  target,
                           in Scope   lScope,
                           in Resolve lResolve);

    /**
     * Set the search path, which is a semi-colon separated sequence of
     * URIs as described in class <code>DLL</code>.  This method will
     * invalidate any existing search path.
     *
     * This updates the search path in the current <code>Finder</code>.
     */
    static void setSearchPath(in string path_name);

    /**
     * Return the current search path.  The default
     * <code>Finder</code> initializes the search path
     * from environment variable SIDL_DLL_PATH.
     *
     */
    static string getSearchPath();

    /**
     * Append the specified path fragment to the beginning of the
     * current search path.  This method operates on the Loader's
     * current <code>Finder</code>. This will add a path to the
     * current search path. Normally, the search path is initialized
     * from the SIDL_DLL_PATH environment variable.
     */
    static void addSearchPath(in string path_fragment);

    /**
     * This method sets the <code>Finder</code> that
     * <code>Loader</code> will use to find DLLs.  If no
     * <code>Finder</code> is set or if NULL is passed in, the Default
     * Finder <code>DFinder</code> will be used.
     * 
     * Future calls to <code>findLibrary</code>,
     * <code>addSearchPath</code>, <code>getSearchPath</code>, and
     * <code>setSearchPath</code> are deligated to the
     * <code>Finder</code> set here.
     */
    static void setFinder(in Finder f);

    /**
     * This method gets the <code>Finder</code> that <code>Loader</code>
     * uses to find DLLs.  
     */
    static Finder getFinder();
  }

  /**
   * This provides an interface to the meta-data available on the
   * class.
   */
  interface ClassInfo {
     /**
      * Return the name of the class.
      */
     string getName();

    /**
     * Get the version of the intermediate object representation.
     * This will be in the form of major_version.minor_version.
     */
     string getIORVersion();
  }

  /** 
   * An implementation of the <code>ClassInfo</code> interface. This
   * provides methods to set all the attributes that are read-only in
   * the <code>ClassInfo</code> interface.
   */
  class ClassInfoI implements-all ClassInfo {
     /**
      * Set the name of the class.
      */
     final void setName(in string name);

     /**
      * Set the IOR major and minor version numbers.
      */
     final void setIORVersion(in int major, in int minor);
  }

  /**
   * Exception thrown from Babel internals when memory allocation
   * fails 
   */
  class MemoryAllocationException extends sidl.SIDLException 
    implements RuntimeException {
  }

  /**
   * Exception is thrown when a cast fails and the failure needs to
   * be communicated up the call stack.  (Note: babel _cast does NOT
   * throw this exception)
   */
  class CastException extends sidl.SIDLException 
     implements RuntimeException {
  } 

  /** 
   * This Exception is thrown by the Babel runtime when a non SIDL
   * exception is thrown from an exception throwing language such as
   * C++ or Java.
   */
  class LangSpecificException extends sidl.SIDLException 
      implements RuntimeException {
  } 

  /** 
   * This package has some I/O capability that's not core to the SIDL
   * object model, but still needed by parts of the generated code
   */
  package io { 
      
    /** generic exception for I/O issues */
    class IOException extends sidl.SIDLException 
       implements RuntimeException {
    }


    /**
     * Standard interface for packing Babel types
     */
    interface Serializer { 
      void packBool( in string key, in bool value ) 
         throws IOException ;
      void packChar( in string key, in char value )
         throws IOException ;
      void packInt( in string key, in int value )
         throws IOException ;
      void packLong( in string key, in long value )
         throws IOException ;
      void packOpaque(	in string key, in opaque value ) 
         throws IOException ;
      void packFloat( in string key, in float value ) 
         throws IOException ;
      void packDouble( in string key, in double value )
         throws IOException ;
      void packFcomplex( in string key, in fcomplex value )
         throws IOException ;
      void packDcomplex( in string key, in dcomplex value )
         throws IOException ;
      void packString( in string key, in string value )
         throws IOException ;
      void packSerializable( in string key, in Serializable value ) 
         throws IOException;
	  
      /** 
       * pack arrays of values.  It is possible to ensure an array is
       * in a certain order by passing in ordering and dimension
       * requirements.  ordering should represent a value in the
       * sidl_array_ordering enumeration in sidlArray.h If either
       * argument is 0, it means there is no restriction on that
       * aspect.  The boolean reuse_array flag is set to true if the
       * remote unserializer should try to reuse the array that is
       * passed into it or not.
       */ 
      void packBoolArray( in string key, in array<bool> value, 
                          in int ordering, in int dimen, 
                          in bool reuse_array ) 
         throws IOException ;
      void packCharArray( in string key, in array<char> value,
                          in int ordering, in int dimen, 
                          in bool reuse_array )
         throws IOException ;
      void packIntArray( in string key, in array<int> value,
                         in int ordering, in int dimen, 
                         in bool reuse_array )
         throws IOException ;
      void packLongArray( in string key, in array<long> value,
                          in int ordering, in int dimen,
                          in bool reuse_array ) 
         throws IOException ;
      void packOpaqueArray( in string key, in array<opaque> value,
                            in int ordering, in int dimen, 
                            in bool reuse_array ) 
         throws IOException ;
      void packFloatArray( in string key, in array<float> value, 
                           in int ordering, in int dimen, 
                           in bool reuse_array )
         throws IOException ;
      void packDoubleArray( in string key, in array<double> value,
                            in int ordering, in int dimen,
                            in bool reuse_array )
         throws IOException ;
      void packFcomplexArray( in string key, in array<fcomplex> value,
                              in int ordering, in int dimen, 
                              in bool reuse_array )
         throws IOException ;
      void packDcomplexArray( in string key, in array<dcomplex> value,
                              in int ordering, in int dimen, 
                              in bool reuse_array ) 
         throws IOException ;
      void packStringArray( in string key, in array<string> value, 
                            in int ordering, in int dimen, 
                            in bool reuse_array ) 
         throws IOException ;
      void packGenericArray( in string key, in array<> value,
                             in bool reuse_array ) 
         throws IOException ;
      void packSerializableArray( in string key, 
                                  in array<Serializable> value,
                                  in int ordering, in int dimen,
                                  in bool reuse_array )
         throws IOException;
    }

    /**
     * Standard interface for unpacking Babel types
     */
    interface Deserializer { 
      /* unpack values */
      void unpackBool( in string key, out bool value ) 
         throws IOException ;
      void unpackChar( in string key, out char value ) 
         throws IOException ;
      void unpackInt( in string key, out int value ) 
         throws IOException ;
      void unpackLong( in string key, out long value ) 
         throws IOException ;
      void unpackOpaque( in string key, out opaque value ) 
         throws IOException ;
      void unpackFloat( in string key, out float value ) 
         throws IOException ;
      void unpackDouble( in string key, out double value ) 
         throws IOException ;
      void unpackFcomplex( in string key, out fcomplex value ) 
         throws IOException ;
      void unpackDcomplex( in string key, out dcomplex value )
         throws IOException ;
      void unpackString( in string key, out string value ) 
         throws IOException ;
      void unpackSerializable( in string key, out Serializable value ) 
         throws IOException;
	  
      /** unpack arrays of values 
       * It is possible to ensure an array is
       * in a certain order by passing in ordering and dimension
       * requirements.  ordering should represent a value in the
       * sidl_array_ordering enumeration in sidlArray.h If either
       * argument is 0, it means there is no restriction on that
       * aspect.  The rarray flag should be set if the array being
       * passed in is actually an rarray.  The semantics are slightly
       * different for rarrays.  The passed in array MUST be reused,
       * even if the array has changed bounds.
       */
      void unpackBoolArray( in string key, out array<bool> value, 
                            in int ordering, in int dimen, 
                            in bool isRarray ) 
         throws IOException ;
      void unpackCharArray( in string key, out array<char> value, 
                            in int ordering, in int dimen,
                            in bool isRarray  ) 
         throws IOException ;
      void unpackIntArray( in string key, out array<int> value,
                           in int ordering, in int dimen, 
                           in bool isRarray  ) 
         throws IOException ;
      void unpackLongArray( in string key, out array<long> value, 
                            in int ordering, in int dimen, 
                            in bool isRarray  )
         throws IOException ;
      void unpackOpaqueArray( in string key, out array<opaque> value, 
                              in int ordering, in int dimen, 
                              in bool isRarray  ) 
         throws IOException ;
      void unpackFloatArray( in string key, out array<float> value,
                             in int ordering, in int dimen,
                             in bool isRarray  )
         throws IOException ;
      void unpackDoubleArray( in string key, out array<double> value,
                              in int ordering, in int dimen,
                              in bool isRarray  ) 
         throws IOException ;
      void unpackFcomplexArray( in string key, out array<fcomplex> value, 
                                in int ordering, in int dimen,
                                in bool isRarray  )
         throws IOException ;
      void unpackDcomplexArray( in string key, 
                                out array<dcomplex> value, 
                                in int ordering, in int dimen, 
                                in bool isRarray  ) 
         throws IOException ;
      void unpackStringArray( in string key, out array<string> value,
                              in int ordering, in int dimen, 
                              in bool isRarray  ) 
         throws IOException ;
      void unpackGenericArray( in string key, out array<> value) 
         throws IOException ;
      void unpackSerializableArray( in string key, 
                                    out array<Serializable> value,
                                    in int ordering, in int dimen,
                                    in bool isRarray  )
         throws IOException ;
    }

  } //end package io

  /** 
   * This package contains necessary interfaces for RMI protocols to
   * hook into Babel, plus a Protocol Factory class.  The intention is
   * that authors of new protocols will create classes that implement
   * InstanceHandle, Invocation and Response (they could even have one
   * object that implements all three interfaces).
   */
  package rmi { 

    /**
     * Generic Network Exception
     */
     class NetworkException extends sidl.io.IOException {
	int getHopCount();
    }	

    /**
     * This exception is thrown by the RMI library when a 
     * host can not be found by a DNS lookup.
     */
     class UnknownHostException extends NetworkException {}

    /** 
     * This exception is normally thrown by the RMI library when the
     * server is started up and the port it is assigned to use is
     * already in use.
     */
     class BindException extends NetworkException {}
     
    /**
     * This exception is thrown by the RMI library when an 
     * attempt to connect to a remote host fails.
     */
     class ConnectException extends NetworkException {}

    /**
     * This exception is thrown by the RMI library when a host 
     * can be found by DNS, but is not reachable.  It usually means 
     * a router is down.
     */
     class NoRouteToHostException extends NetworkException {}

    /**
     * This exception is thrown by the RMI library when a request 
     * times out. 
     */
     class TimeOutException extends NetworkException {}

    /**
     * This exception is thrown by the RMI library when the network 
     * unexpected loses it's connection.  Can be caused by reset, 
     * software connection abort, connection reset by peer, etc. 
     */
     class UnexpectedCloseException extends NetworkException {}

    /**
     * This exception is thrown by a server when a passed in object 
     * id does not match any known object. 
     */
     class ObjectDoesNotExistException extends NetworkException {}

    /**
     * This exception is thrown by the RMI library when a passed in URL 
     * is malformed.
     */
     class MalformedURLException extends NetworkException {}

    /**
     * This is a base class for all protocol specific exceptions.
     */
     class ProtocolException extends NetworkException {}

    /** 
     * This singleton class keeps a table of string prefixes
     * (e.g. "babel" or "proteus") to protocol implementations.  The
     * intent is to parse a URL (e.g. "babel://server:port/class") and
     * create classes that implement
     * <code>sidl.rmi.InstanceHandle</code>.
     */
    class ProtocolFactory { 
      /** 
       * Associate a particular prefix in the URL to a typeName
       * <code>sidl.Loader</code> can find.  The actual type is
       * expected to implement <code>sidl.rmi.InstanceHandle</code>
       * Return true iff the addition is successful.  (no collisions
       * allowed)
       */
       static bool addProtocol( in string prefix, in string typeName ) 
	   throws NetworkException;
	  
      /**
       * Return the typeName associated with a particular prefix.
       * Return empty string if the prefix
       */
       static string getProtocol( in string prefix )
          throws NetworkException;

      /**
       * Remove a protocol from the active list.
       */
       static bool deleteProtocol( in string prefix ) 
          throws NetworkException;
	  
      /**
       * Create a new remote object and return an instance handle for that
       * object. 
       * The server and port number are in the url.  Return nil 
       * if protocol unknown or InstanceHandle.init() failed.
       */
      static InstanceHandle createInstance( in string url,
                                            in string typeName )
	    throws NetworkException;

      /** 
       * Create an new connection linked to an already existing
       * object on a remote server.  The server and port number are in
       * the url, the objectID is the unique ID of the remote object
       * in the remote instance registry.  Return null if protocol
       * unknown or InstanceHandle.init() failed.  The boolean addRef
       * should be true if connect should remotely addRef
       */
       static InstanceHandle connectInstance( in string url, in bool ar) 
	   throws NetworkException;	
     }

    /** 
     * This interface holds the state information for handles to
     * remote objects.  Client-side messaging libraries are expected
     * to implement <code>sidl.rmi.InstanceHandle</code>,
     * <code>sidl.rmi.Invocation</code> and
     * <code>sidl.rmi.Response</code>.
     * 
     * Every stub with a connection to a remote object holds a pointer
     * to an InstanceHandle that manages the connection. Multiple
     * stubs may point to the same InstanceHandle, however.  Babel
     * takes care of the reference counting, but the developer should
     * keep concurrency issues in mind.
     *	
     *  When a new remote object is created:
     *       sidl_rmi_InstanceHandle c = 
     *         sidl_rmi_ProtocolFactory_createInstance( url, typeName,
     *               _ex );
     * 
     *  When a new stub is created to connect to an existing remote
     * instance:
     *        sidl_rmi_InstanceHandle c = 
     *          sidl_rmi_ProtocolFactory_connectInstance( url, _ex );
     *
     *  When a method is invoked:
     *       sidl_rmi_Invocation i = 
     *          sidl_rmi_InstanceHandle_createInvocation( methodname );
     *       sidl_rmi_Invocation_packDouble( i, "input_val" , 2.0 );
     *       sidl_rmi_Invocation_packString( i, "input_str", "Hello" );
     *       ...
     *       sidl_rmi_Response r = sidl_rmi_Invocation_invokeMethod( i );
     *       sidl_rmi_Response_unpackBool( i, "_retval", &succeeded );
     *       sidl_rmi_Response_unpackFloat( i, "output_val", &f );
     * 
     */	
    interface InstanceHandle {

      /** initialize a connection (intended for use by the
       * ProtocolFactory, (see above).  This should parse the url and
       * do everything necessary to create the remote object.
       */
       bool initCreate( in string url, in string typeName ) 
	   throws NetworkException;

      /**
       * initialize a connection (intended for use by the ProtocolFactory) 
       * This should parse the url and do everything necessary to connect 
       * to a remote object.
       */
       bool initConnect( in string url, in bool ar) throws NetworkException;

      /** return the short name of the protocol */
       string getProtocol() throws NetworkException;

      /** return the object ID for the remote object*/
       string getObjectID() throws NetworkException;

      /** 
       * return the full URL for this object, takes the form: 
       * protocol://serviceID/objectID (where serviceID would = server:port 
       * on TCP/IP)
       * So usually, like this: protocol://server:port/objectID
       */
      string getObjectURL() throws NetworkException;

      /** create a serializer handle to invoke the named method */
      Invocation createInvocation( in string methodName ) 
          throws NetworkException;
  
      /** 
       * closes the connection (called by the destructor, if not done
       * explicitly) returns true if successful, false otherwise
       * (including subsequent calls)
       */
      bool close() throws NetworkException;
    }

    /**
     * This type is used to pack arguments and make the Client->Server 
     * method invocation.
     */	 
    interface Invocation extends sidl.io.Serializer {

      /** 
       * this method is one of a triad.  Only one of which 
       * may be called, and it must the the last method called
       * in the object's lifetime.
       */
      Response invokeMethod() throws NetworkException;

      /**
       * This method is second of the triad.  It returns
       * a Ticket, from which a Response is later extracted.
       */
      Ticket invokeNonblocking() throws NetworkException;

      /**
       * This method is third of the triad.  It returns
       * and exception iff the invocation cannot be delivered
       * reliably.  It does not wait for the invocation to 
       * be acted upon and returns no values from the invocation.
       */
      void invokeOneWay() throws NetworkException;
    }

    /** 
     * This type is created when an invokeMethod is called on an
     * Invocation.  It encapsulates all the results that users will
     * want to pull out of a remote method invocation.
     */
    interface Response extends sidl.io.Deserializer { 

      /** 
       * May return a communication exception or an execption thrown
       * from the remote server.  If it returns null, then it's safe
       * to unpack arguments
       */
      sidl.BaseException getExceptionThrown() throws NetworkException;
	  
    }

    /** 
     * This interface is implemented by the Server side deserializer.
     * Deserializes method arguments in preperation for the method
     * call.
     */
    interface Call extends sidl.io.Deserializer { }

    /** 
     * This interface is implemented by the Server side serializer.
     * Serializes method arguments after the return from the method
     * call.
     */
    interface Return extends sidl.io.Serializer {

      /** 
       * This method serialized exceptions thrown on the server side
       * that should be returned to the client.  Assumed to invalidate
       * in previously serialized arguments.  (Also assumed that no
       * more arguments will be serialized.)
       */
      void throwException(in sidl.BaseException ex_to_throw) 
         throws NetworkException;
    }

    /**
     * Used in lieu of a Response in nonblocking calls
     */
    interface Ticket { 
	
	/** blocks until the Response is recieved */
	void block();

	/** 
         * returns immediately: true iff the Response is already
         * received */
	bool test();

        /** creates an empty container specialized for Tickets */
        TicketBook createEmptyTicketBook();

	/** returns immediately: returns Response or null 
         *  (NOTE: needed for implementors of communication
         *         libraries, not expected for general use).
         */
	Response getResponse() throws NetworkException;

    }

    /**
     * This is a collection of Tickets that itself can be viewed
     * as a ticket.  
     */
    interface TicketBook extends Ticket { 
        
        /** insert a ticket with a user-specified ID */
        void insertWithID( in Ticket t, in int id );

        /** insert a ticket and issue a unique ID */
        int insert( in Ticket t );

        /** remove a ready ticket from the TicketBook
         *  returns 0 (and null) on an empty TicketBook
         */
        int removeReady( out Ticket t );

        /**
         * immediate, returns the number of Tickets in the book.
         */
        bool isEmpty();

    }

    /** 
     * This singleton class is implemented by Babel's runtime for RMI
     * libraries to invoke methods on server objects.  It maps
     * objectID strings to sidl_BaseClass objects and vice-versa.
     *
     * The InstanceRegistry creates and returns a unique string when a
     * new object is added to the registry.  When an object's refcount
     * reaches 0 and it is collected, it is removed from the Instance
     * Registry.
     *
     * Objects are added to the registry in 3 ways:
     * 1) Added to the server's registry when an object is
     *    create[Remote]'d.
     * 2) Implicity added to the local registry when an object is
     *    passed as an argument in a remote call.
     * 3) A user may manually add a reference to the local registry
     *    for publishing purposes.  The user hsould keep a reference
     *    to the object.  Currently, the user cannot provide their own
     *    objectID, this capability should probably be added.
     */
    class InstanceRegistry { 

      /** 
       * Register an instance of a class.
       *  
       * the registry will return an objectID string guaranteed to be
       * unique for the lifetime of the process
       */	      
      static string registerInstance( in sidl.BaseClass instance ) 
	  throws NetworkException;

      /** 
       * returns a handle to the class based on the unique objectID
       * string, (null if the handle isn't in the table)
       */
      static sidl.BaseClass getInstanceString( in string instanceID ) 
	  throws NetworkException;

      /** 
       * takes a class and returns the objectID string associated
       * with it.  (null if the handle isn't in the table)
       */
      static string getInstanceClass( in sidl.BaseClass instance ) 
	  throws NetworkException;

      /** 
       * removes an instance from the table based on its objectID
       * string..  returns a pointer to the object, which must be
       * destroyed.
       */
      static sidl.BaseClass removeInstanceString( in string instanceID ) 
	  throws NetworkException;
    
      /** 
       * removes an instance from the table based on its BaseClass
       * pointer.  returns the objectID string, which much be freed.
       */
      static string removeInstanceClass( in sidl.BaseClass instance ) 
	  throws NetworkException;
    }

    /** 
     * This singleton class is implemented by Babel's runtime for to
     * allow RMI downcasting of objects.  When we downcast an RMI
     * object, we may be required to create a new derived class object
     * with a connect function.  We store all the connect functions in
     * this table for easy access.
     *
     * This Class is for Babel internal use only.
     */
    class ConnectRegistry { 

      /** 
       * The key is the SIDL classname the registered connect belongs
       * to.  Multiple registrations under the same key are possible,
       * this must be protected against in the user code.  Babel does
       * this internally with a static boolean.
       */	      
      static void registerConnect( in string key, in opaque func);

      /** 
       * Returns the connect method for the class named in the key
       */
      static opaque getConnect( in string key );

      /** 
       * Returns the connect method for the class named in the key,
       * and removes it from the table.
       */
      static opaque removeConnect( in string key );
    }	

    /** 
     * ServerInfo is an interface (possibly implemented by the ORB
     * itself) that provides functions to deal with the problems
     * associated with passing local object remotely.  It should be
     * registered with the ServerRegistry for general use.
     */
    interface ServerInfo {
      string getServerURL(in string objID) throws NetworkException;

      /** 
       * For internal Babel use ONLY. Needed by Babel to determine if
       * a url points to a local or remote object.  Returns the
       * objectID if is local, Null otherwise.
       */ 
      string isLocalObject(in string url) throws NetworkException;

      /** 
       * This gets an array of logged exceptions.  If an exception
       * can not be thrown back to the caller, we log it with the
       * Server.  This gets the array of all those exceptions.  THIS
       * IS SOMETHING OF A TEST! THIS MAY CHANGE!
       */
      array<sidl.io.Serializable,1> getExceptions();
    }

    /** 
     * This singleton class is simply a place to register a
     * ServerInfo interface for general access.  This ServerInfo
     * should give info about the ORB being used to export RMI objects
     * for the current Babel process.
     *
     * This Registry provides two important functions, a way to get
     * the URL for local object we wish to expose over RMI, and a way
     * to tell if an object passed to this process via RMI is actually
     * a local object.  This abilities are protocol specific, the
     * ServerInfo interface must by implemented by the protocol
     * writer.
     *
     * THIS CLASS IS NOT DESIGNED FOR CONCURRENT WRITE ACCESS.  (Only
     * one server is assumed per Babel process)
     */
    class ServerRegistry {
      static void registerServer(in sidl.rmi.ServerInfo si) 
	  throws NetworkException;

      /**
       * Perhaps this should take BaseClass and look the objectID up in 
       * the Instance Registry
       */ 
      static string getServerURL(in string objID) throws NetworkException;

      /**
       * For internal Babel use ONLY. Needed by Babel to determine if a 
       * url points to a local or remote object.  Returns the objectID 
       * if is local, Null otherwise.
       */ 
      static string isLocalObject(in string url) throws NetworkException;

      /** 
       * This gets an array of logged exceptions.  If an exception
       * can not be thrown back to the caller, we log it with the
       * Server.  This gets the array of all those exceptions.  THIS
       * IS SOMETHING OF A TEST! THIS MAY CHANGE!
       */
      static array<sidl.io.Serializable,1> getExceptions();		
      
    }

    /** This is the basic interface that all RMI servers should implement.*/
    interface BaseServer {
      /** 
       * The url string is necessary to give the server the info it
       * needs to start up.  The string is protocol dependant.  In
       * most TCP/IP based protocols, only the port number is really
       * required, but it is suggested they accept a full url of the
       * form: protocol://localhost:port
       */
      void init(in string url) throws sidl.rmi.NetworkException;

      /** 
       * Starts the server running.  It is expected that most servers
       * will be threaded, and this function returns a long that can
       * be used as a server thread id to join to is necessary.
       */
      long run() throws sidl.rmi.NetworkException;	
    }
      
  } //end package rmi
}





babel-0.11.0
users_guide Last Modified 2005-12-20

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