[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