File: node102.html

package info (click to toggle)
babel 0.10.2-1
links: PTS
area: contrib
in suites: sarge
size: 43,932 kB
ctags: 29,707
sloc: java: 74,695; ansic: 73,142; cpp: 40,649; sh: 18,411; f90: 10,062; fortran: 6,727; python: 6,406; makefile: 3,866; xml: 118; perl: 48
file content (542 lines) | stat: -rw-r--r-- 20,628 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Interfaces</TITLE>
<META NAME="description" CONTENT="Interfaces">
<META NAME="keywords" CONTENT="users_guide">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">

<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="users_guide.css">

<LINK REL="previous" HREF="node101.html">
<LINK REL="up" HREF="node100.html">
<LINK REL="next" HREF="node103.html">
</HEAD>

<BODY >

<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html2168"
  HREF="node103.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> 
<A NAME="tex2html2162"
  HREF="node100.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> 
<A NAME="tex2html2158"
  HREF="node101.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> 
<A NAME="tex2html2164"
  HREF="node14.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> 
<A NAME="tex2html2166"
  HREF="node317.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A> 
<BR>
<B> Next:</B> <A NAME="tex2html2169"
  HREF="node103.html">Objects</A>
<B> Up:</B> <A NAME="tex2html2163"
  HREF="node100.html">SIDL Runtime</A>
<B> Previous:</B> <A NAME="tex2html2159"
  HREF="node101.html">Inheritance</A>
 &nbsp; <B>  <A NAME="tex2html2165"
  HREF="node14.html">Contents</A></B> 
 &nbsp; <B>  <A NAME="tex2html2167"
  HREF="node317.html">Index</A></B> 
<BR>
<BR></DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION02452000000000000000">
Interfaces</A>
</H2>
The SIDL runtime library provides three sets of interfaces:

<P>
<DL>
<DT><STRONG>Base</STRONG></DT>
<DD>The base class, interface, and exception upon which all 
Babel-enabled software builds.
</DD>
<DT><STRONG>Library Handler</STRONG></DT>
<DD>The DLL and Loader classes facilitate dynamic loading
of objects at runtime.
</DD>
<DT><STRONG>Introspection</STRONG></DT>
<DD>The ClassInfo interface and ClassInfoI class enable
checking meta-data associated with a class.
</DD>
</DL>

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

<P>
<BR>
<PRE  CLASS="verbatim">//
// File:        sidl.sidl
// Release:     $Name:  $
// Revision:    @(#) $Revision: 4460 $
// Date:        $Date: 2005-03-23 11:12:04 -0800 (Wed, 23 Mar 2005) $
// Description: SIDL interface description for the basic SIDL run-time library
// 
// Copyright (c) 2001, The Regents of the University of Calfornia.
// Produced at the Lawrence Livermore National Laboratory.
// Written by the Components Team &lt;components@llnl.gov&gt;
// 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 &lt;code&gt;SIDL&lt;/code&gt; package contains the fundamental type and interface
 * definitions for the &lt;code&gt;SIDL&lt;/code&gt; interface definition language.  It
 * defines common run-time libraries and common base classes and interfaces.
 * Every interface implicitly inherits from &lt;code&gt;sidl.BaseInterface&lt;/code&gt;
 * and every class implicitly inherits from &lt;code&gt;sidl.BaseClass&lt;/code&gt;.
 * 
 */
package sidl version 0.9.0 {

  /**
   * Every interface in &lt;code&gt;SIDL&lt;/code&gt; implicitly inherits
   * from &lt;code&gt;BaseInterface&lt;/code&gt;, and it is implemented
   * by &lt;code&gt;BaseClass&lt;/code&gt; below.
   */
  interface BaseInterface {

    /**
     * &lt;p&gt;
     * Add one to the intrinsic reference count in the underlying object.
     * Object in &lt;code&gt;SIDL&lt;/code&gt; 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.
     * &lt;/p&gt;
     * &lt;p&gt;
     * This does not have a return value because there is no language
     * independent type that can refer to an interface or a
     * class.
     * &lt;/p&gt;
     */
    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 &lt;code&gt;SIDL&lt;/code&gt; 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 &lt;code&gt;obj&lt;/code&gt; refers to the same
     * object as this object.
     */
    bool isSame(in BaseInterface iobj);

    /**
     * Check whether the object can support the specified interface or
     * class.  If the &lt;code&gt;SIDL&lt;/code&gt; type name in &lt;code&gt;name&lt;/code&gt;
     * is supported, then a reference to that object is returned with the
     * reference count incremented.  The callee will be responsible for
     * calling &lt;code&gt;deleteRef&lt;/code&gt; on the returned object.  If
     * the specified type is not supported, then a null reference is
     * returned.
     */
    BaseInterface queryInt(in string name);

    /**
     * Return whether this object is an instance of the specified type.
     * The string name must be the &lt;code&gt;SIDL&lt;/code&gt; type name.  This
     * routine will return &lt;code&gt;true&lt;/code&gt; 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 &lt;code&gt;BaseClass&lt;/code&gt;.  This
   * class implements the methods in &lt;code&gt;BaseInterface&lt;/code&gt;.
   */
  class BaseClass implements BaseInterface {
    /**
     * &lt;p&gt;
     * Add one to the intrinsic reference count in the underlying object.
     * Object in &lt;code&gt;SIDL&lt;/code&gt; 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.
     * &lt;/p&gt;
     * &lt;p&gt;
     * This does not have a return value because there is no language
     * independent type that can refer to an interface or a
     * class.
     * &lt;/p&gt;
     */
    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 &lt;code&gt;SIDL&lt;/code&gt; 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 &lt;code&gt;obj&lt;/code&gt; refers to the same
     * object as this object.
     */
    final bool isSame(in BaseInterface iobj);

    /**
     * Check whether the object can support the specified interface or
     * class.  If the &lt;code&gt;SIDL&lt;/code&gt; type name in &lt;code&gt;name&lt;/code&gt;
     * is supported, then a reference to that object is returned with the
     * reference count incremented.  The callee will be responsible for
     * calling &lt;code&gt;deleteRef&lt;/code&gt; on the returned object.  If
     * the specified type is not supported, then a null reference is
     * returned.
     */
    BaseInterface queryInt(in string name);

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

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

  /**
   * Every exception implements &lt;code&gt;BaseException&lt;/code&gt;. This interface
   * declares the basic functionality to get and set error messages and stack
   * traces.
   */
  interface BaseException {

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

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

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

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

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

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

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

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

  /**
   * The &lt;code&gt;DLL&lt;/code&gt; class encapsulates access to a single
   * dynamically linked library.  DLLs are loaded at run-time using
   * the &lt;code&gt;loadLibrary&lt;/code&gt; method and later unloaded using
   * &lt;code&gt;unloadLibrary&lt;/code&gt;.  Symbols in a loaded library are
   * resolved to an opaque pointer by method &lt;code&gt;lookupSymbol&lt;/code&gt;.
   * Class instances are created by &lt;code&gt;createClass&lt;/code&gt;.
   */
  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 &lt;code&gt;true&lt;/code&gt; means that the shared
     *                     library symbols will be loaded into the
     *                     global namespace; &lt;code&gt;false&lt;/code&gt; 
     *                     means they will be loaded into a 
     *                     private namespace. Some operating systems
     *                     may not be able to honor the value presented
     *                     here.
     * @param loadLazy     &lt;code&gt;true&lt;/code&gt; 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 &lt;code&gt;loadLibrary&lt;/code&gt; except that all file names
     * contain the "file:" protocol.
     */
    string getName();

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

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

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

  /**
   * Class &lt;code&gt;Loader&lt;/code&gt; manages dyanamic loading and symbol name
   * resolution for the SIDL runtime system.  The &lt;code&gt;Loader&lt;/code&gt; class
   * manages a library search path and keeps a record of all libraries
   * loaded through this interface, including the initial "global" symbols
   * in the main program.  Unless explicitly set, the search path is taken
   * from the environment variable SIDL_DLL_PATH, which is a semi-colon
   * separated sequence of URIs as described in class &lt;code&gt;DLL&lt;/code&gt;.
   */
  class Loader {

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

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

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

    /**
     * Load the specified library if it has not already been loaded.
     * The URI format is defined in class &lt;code&gt;DLL&lt;/code&gt;.  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 &lt;code&gt;true&lt;/code&gt; means that the shared
     *                     library symbols will be loaded into the
     *                     global namespace; &lt;code&gt;false&lt;/code&gt; 
     *                     means they will be loaded into a 
     *                     private namespace. Some operating systems
     *                     may not be able to honor the value presented
     *                     here.
     * @param loadLazy     &lt;code&gt;true&lt;/code&gt; instructs the loader to
     *                     that symbols can be resolved as needed (lazy)
     *                     instead of requiring everything to be resolved
     *                     now.
     * @return if the load was successful, a non-NULL DLL object is returned.
     */
    static DLL loadLibrary(in string uri,
                           in bool loadGlobally,
                           in bool loadLazy);

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

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

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

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

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

  /**
   * An implementation of the &lt;code&gt;ClassInfo&lt;/code&gt; interface. This provides
   * methods to set all the attributes that are read-only in the
   * &lt;code&gt;ClassInfo&lt;/code&gt; 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);
  }
}
</PRE></td></tr></table></blockquote>
<P>

<P>
<BR><HR>
<ADDRESS>
<br><br>babel-0.10.2<br>users_guide Last Modified 2005-03-23<br><br><a href="http://www.llnl.gov/CASC/components">http://www.llnl.gov/CASC/components</a><br><a href="mailto:components@llnl.gov">components@llnl.gov</a>
</ADDRESS>
</BODY>
</HTML>