[Pipet Devel] new idl

Brad Chapman chapmanb at arches.uga.edu
Sun Mar 26 17:16:03 EST 2000


Oops, I screwed stuff up and that last idl didn't attach so well. (I'm 
also using an open source beta version mailer with lots o' bugs, so 
maybe I can pretend to blame it on that :-) How about if I just paste 
it on in? 
    Hope this is better :)

Brad

// dl2bl.idl
//
// IDL for dealing with communication between the GUI (buffered by a 
small
// middle) and the data processing engine.
//
// Changelog:
//      23 Mar 2000     : Brad, creation 
//      25 Mar 2000     : Jarl, added gms naming
//      26 Mar 2000     : Renamed again :) added\remove some functions
//                        Actually compiled this :)
//      27 Mar 2000     : Brad, case changes, moved a few functions 
around
//                        Added a struct for returning more info about 
a 
//                        node/process.
/**
 * Acronyms
 * vsh: The overall module (the name can change when we decide on a 
formal
 *      name).
 * dl2bl: idl for communication between the scripting/XML layer and 
the 
 *      data processing engine.
 * dl : definition layer, involved in the creation of an XML script to 
define
 *  structures.
 * bl: Brokering Layer, layer that does the 
distribution\authentication\etc
 * pl: Processing Layer, layer that does the 'real' dataflow work.
 * 
 */
module vsh {
  /**
   * Communication between the definition layer (XML script generator) 
and
   * the brokering layer, which distributes the XML info to the 
processing 
   * layer.
   */
  module dl2bl {
    // ##### exceptions
    // ----------------
    /**
     * Requested Id is already being used for another gui.
     */
    exception DLIdInUse {};
    /**
     * Id number used for requested operation was not found in the 
list of
     * current gui ids being served by the data processor.
     */
    exception DLIdNotFound{};
    /**
     * The information for a node is not yet available because the 
process
     * has not completed.
     */
    exception DLInfoNotAvailable{};                     
    /**
     * The definition layer couldn't accept the XML document and so 
didn't 
     * allocate an uri.
     */
    exception URIUndefined{};
    /**
     * The uri is already defined.
     */
    exception URIInUse{};
    /**
     * The uri cant be found, it does not excist or is not accessable.
     */
    exception URINotFound{};
    /**
     * Requested information was not found.
     */
    exception InfoNotAvailable{};
    
    // ##### structs, enums and typedefs
    // ---------------------------------
    /**
     * DL identification number, or 'account name'.
     */
    typedef long DLIdT;
    /**
     * Passwords.
     */
    typedef string passwordT;
    /**
     * Connection type:
     *   -1 = Unconnected
     *    0 = Unknown
     *    1 = Plain connection
     *    2 = Encrypted connection, based on {TODO:type} encryption
     */
    enum connectionE {
        UNKNOWN,
        UNCONNECTED,
        PLAIN,
        ENCRYPTED1
    };
    /**
     * Current state of a node or process:
     * -1 = Error (TODO: Other negative values to define various 
errors)
     *  0 = Unknown
     *  1 = Passing
     *  2 = Blocking
     *  4 = Temporary
     *  8 = Isolated
     */
    typedef long stateT;
    
    /**
     * A value between zero and one indicating the process towards 
completion
     * for a process, subnet or node. This is useful if you have 
really long
     * programs and want to check on their status.
     * 1 -> finished (100% done)
     * intermediate -> % towards completion
     * 0 -> not started (0% done)
     */
    typedef double progressT;
    
    /**
     * Struct for returning the status of a particular node or process.
     * @mem state - The current state of the node or process.
     * @mem progress - The progress towards completion of the node or 
     *                 process.
     */
    struct statusT{
        stateT state;
        progressT progress;
    };
        
    /**
     * URI type, a 128bits locating id:
     * bits 0-31 : instance id
     * bits 32-63 : brokering id, or subnet id
     * bits 64-127 : node i
     * uriT is in a IP (Internet protocol) style
     *      uriT = 2.0.0 -> All subnets and nodes local in instance 2
     *      uriT = 74.35.0 -> All nodes in subnet 35 of instance 74.
     *      uriT = 1.2.3 -> Node 3 in subnet 2 of instance 1.
     */
    struct uriT {
        long instanceID;
        long subnetID;
        long nodeID;
    };
    
    /**
     * A sequence/list of uriTs. Useful for returning info like a list 
of
     * program ids for available programs.
     * 
     */
    typedef sequence <string> uriListT;
                            
    // ##### interfaces                 
    // ----------------
                            
    /**
     * Functions for establishing a connection between the definition 
layer
     * and brokering layer (which controls access to the processing 
layer).
     */
    interface Connection {
        // TODO: introduce a 'access level', so ADM's can be limited
        
        /** setup
         * Initialize a connection from the dl to the 
brokering/processing 
         * layer.
         * @parm    dlid- An unique id to represent the connection.
         * @parm    password - The password associated with this id.
         * @parm    connecttype - requested connection type.
         * @returns A boolean indicating the success of the 
initialization.
         * @raises  DLIdInUse - The passed dlid is already in use by 
another 
         * gui.
         * TODO: Add more exceptions to raise as we see what problems 
come up.
         */
        boolean setup(in DLIdT dlid, in passwordT password, in 
connectionE 
                      connecttype) 
            raises (DLIdInUse);
        /** release
         * Close the connection between the definition layer and the 
brokering
         * processing layer
         * @parm    dlid - An unique id to represent the connection.
         * @parm    password - The password associated with this id.
         * @returns A boolean indicating the success of the 
initialization
         * @raises  DLIdNotFound - The passed id was not found in the 
list of
         *          ids registerd with the data processing engine.
         */
        boolean release(in DLIdT dlid, in passwordT password)
            raises (DLIdNotFound);
            
        /** checkConnection
         * Checks if the DL with id 'dlid' has been connected.
         * @parm    dlid - An unique id represting the connection.
         * @returns type of connection
         * @raises  DLInfoNotAvailable - this connection isn't setup 
correctly
         */
        connectionE checkConnection(in DLIdT dlid)
            raises (DLInfoNotAvailable);
    };
    /**
     * Functions for passing XML information to the data processing 
engine
     * and synchronizing the document.
     */
    interface XmlRepresentation {
        /** upload
         * Uploads a XML document to the DL, which will pass most of 
it to the 
         * PL.
         * @parm    xmldocument: A big string of xml describing the 
nodes/loci
         *          to be processed and the relationship between them.
         * @parm    dlid - The ID of the DL that uploads the document
         * @parm    password - The password associated with this id.
         * @returns the URI the uploaded structure got assigned by the 
DL.
         * @raises  URIUndefined, the DL/PL couldn't accept the XML 
document. 
         *          Use RetrieveInfo::check to see what is wrong.
         */
        uriT upload(in string xmldocument, in DLIdT dlid, in passwordT 
password)
            raises (URIUndefined);
            
        /** update
         * Updates an excisting structure.
         * @parm    xmldocument - The XML document
         * @parm    uri - the uri id of the structure to be 
overwritten.
         * @parm    dlid - The ID of the DL that uploads the document
         * @parm    password - The password associated with this id.
         * @returns boolean success status.
         * @raises  URIInUse, the uri is currently running or the DDL 
is not 
         *          authorized to overwrite it.         
         */
        boolean update(in string xmldocument, in uriT uri, in DLIdT 
dlid, 
                       in passwordT password)
            raises (URIInUse);
        
        /** download
         * Downloads a XML document from the BL to the DL.
         * @parm    uri - uri of the structure to be downloaded.
         * @parm    dld - The ID of the DL that uploaded the document
         * @parm    password - The password associated with this id.
         * @returns An XML document.
         * @raises  URINotFound when uri doesn't exist or is not 
reachable.
         */
        string download(in uriT uri, in DLIdT dlid, in passwordT 
password)
            raises (URINotFound);
            
     };
    /**
     * Functions to provide status information for the core (brokering 
and 
     * processing layers), and for getting information about programs 
and
     * libraries registered with the processing engine.
     */
    interface RetrieveInfo {
        /** checkStatus
         * Used for checking the status of an URI 
         * @parm    uri - uri of the structure to be checked.
         * @parm    dlid - The ID of the DL that uploads the document
         * @parm    password - The password associated with this id.
         * @returns Status of the structure uri.
         * @raises  URINotFound when uri doesn't excist or is not 
reachable.
         */
        statusT checkStatus(in uriT uri, in DLIdT dlid, in passwordT 
password)
            raises (URINotFound);
                
        /**
         * Get the information for a node so that is can be displayed 
in
         * the visual user interface.
         * @parm processid - the unique id associated with a process.
         * @parm uri - uri of the node to be checked.
         * @returns A string with the info from the node.
         *          TODO: Need a structured and generalized way to 
return info
         *          and pass it to a visual so it can be seen in the 
GUI
         *          Strings aren't going to cut it for everything, 
         *          I don't think.
         * @raises InfoNotAvailable - If the node currently doesn't 
have any
         *         information to send (ie. process is not complete).
         */
        string getNodeInfo(in passwordT processid, in uriT uri)
            raises (InfoNotAvailable);  
        
        /**
         * Get a list of all the program ids of programs registered 
functional
         * (ie. loaded) with the processing engine.
         * @returns A sequence of uri's with ids of available 
         *          nodes/subnets/programs. These will be returned 
with leading 
         *          zeros. For instance you could get back a list like 
the 
         *          following:
         *          ['0.0.27', '0.0.345', '0.0.123'...] 
         *          It will be up to the definition layer to keep a 
dictionary 
         *          to translate between these uri's and the actual 
program 
         *          names.
         */
        uriListT getProgramIds();
        
        /**
         * Query a specific node to see if it is available.
         * @parm node_id - the unique id of a node (program/function).
         * @returns 1 if the program is loaded, 0 if it is not.
         * @raises URINotFound - If the requested URI can not be 
located.
         */ 
        boolean isAvailable(in uriT uri)
            raises (URINotFound); 
    };
    
  };
};







More information about the Pipet-Devel mailing list