[Pipet Devel] Initial idl proposal

[Brad Chapman]

Hello all;
    Based on the broad design I mentioned yesterday for communicating 
between a small middle (part of the GUI) and the "data processing 
engine" of 'vsh', I drew up an idl as a starting point for this 
communication. This definately need a lot of work and if the first idl 
I've ever written, so I can use lots of comments and criticisms, but 
this will be something to build off of so we can get things going. I 
look forward to hearing comments!

Brad

// gui2dp.idl
//
// IDL for dealing with communication between the GUI (buffered by a 
small 
// middle) and the data processing engine.

/**
 * Organization of modules.
 * vsh: The overall module (the name can change when we decide on a 
formal 
 *      name).
 *   gui2dp: idl for communication between the GUI and the data 
processing 
 *           engine. 
 * 
 */

module vsh {
  module gui2dp {
    // ##### exceptions
    
    /**
     * Requested Id is already being used for another gui.
     */
    exception IdInUse {};
                            
    /**
     * Id number used for requested operation was not found in the 
list of
     * current gui ids being served by the data processor.
     */
    exception IdNotFound{};
                
    /**
     * The information for a node is not yet available because the 
process 
     * has not completed.
     */
    exception InfoNotAvailable{};
                            
    // ##### structs and typedefs
    /**
     * A sequence/list of strings. Useful for returning info like a 
list of 
     * program ids for available programs.
     */
    typedef sequence <string> stringList;
                            
    // ##### interfaces                 
                            
    /**
     * Functions for dealing with a front to middle connection.
     */
    interface Connection {
        /**
         * Initialize a connection from the gui to the data processing 
engine.
         * @parm gui_id - An unique id to represent the gui connection
         * @parm password - The password associated with this id.
         * @returns A boolean indicating the success of the 
initialization
         * @raises IdInUse - The passed gui_id is already in use by 
another gui.
         */
        boolean init_connection(in string gui_id, in string password)
            raises (IdInUse);
        /**
         * Close the connection between the gui and data processing 
engine. 
         * Used when closing down a GUI.
         * @parm gui_id - An unique id to represent the gui connection
         * @parm password - The password associated with this id.
         * @returns A boolean indicating the success of the 
initialization
         * @raises IdNotFound - The passed id was not found in the 
list of 
         *                      ids registerd with the data processing 
engine.
         */
        boolean close_connection(in string gui_id, in string password)
            raises (IdNotFound);
    };
    /**
     * Functions for passing XML information to the data processing 
engine. 
     */
    interface SendProcessingInfo {
        /** 
         * Send a string of XML to the data processing engine to be 
dealt with.
         * @parm xml_to_process: A big string of xml describing the 
nodes/loci
         *       to be processed and the relationship between them.
         * @returns An id to be used for getting information about the
         *          process sent.
         */
        string send_xml(in string xml_to_process);                     
 
    };
        
    /**
     * Functions dealing with a process that has been sent to the 
middle.
     */
    interface ProcessInformation {
        /**
         * Request information the status of the overall process.
         * @parm process_id - the unique id associated with a process.
         * @returns A double representing the progress towards 
completion.
         *          1 indicates completion, 0 indicates the process 
has not
         *          started, numbers between 0 and 1 represent the 
percent 
         *          completion, and -1 indicates an error in the 
process.
         * @raises IdNotFound - If the passed process_id is not found.
         */
        double query_process(in string process_id) raises (IdNotFound);
        
        /**
         * Request information about a particular node/locus in a 
process.
         * @parm process_id - the unique id associated with a process.
         * @parm node_id - the unique id associated with a node.
         * @returns A double representing the progress towards 
completion.
         *          1 indicates completion, 0 indicates the process 
has not
         *          started, numbers between 0 and 1 represent the 
percent 
         *          completion, and -1 indicates an error in the 
process.
         * @raises IdNotFound - if either the process or node id were 
not 
         *         found.
         */
        double query_process_node(in string process_id, in string 
node_id)
            raises (IdNotFound);
                
        /**
         * Get the information for a node so that is can be displayed 
in the 
         * GUI.
         * @parm process_id - the unique id associated with a process.
         * @parm node_id - the unique id associated with a node.
         * @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 get_node_info(in string process_id, in string node_id)
            raises (InfoNotAvailable);  
        
    };
    /**
     * Functions for getting information about programs and libraries 
registered
     * with the processing engine.
     */
    interface ProgramInformation {
        /**
         * Get a list of all the program ids of programs registered 
functional
         * (ie. loaded) with the processing engine.
         * @returns A sequence of strings (list) with the node_ids of 
available
         *          nodes.  
         */
        stringList get_program_ids();
        
        /**
         * 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.
         */ 
        boolean is_available(in string node_id);
        
    };
    
    
  };
};