DOC-LISP Interface Design ------------------------- This file contains a description of the DOC-LISP Interface Design and a description of the developement that must take place to implement the interface. Design Description ------------------ #################### ################################### # # # # # DOC Client # # Remote Service Server # # ---------- # # --------------------- # # # # # # +----------+ # # +---------+ +---------+ # # | Client |----#------#---->| Service |---->| LISP | # # | Object | # # | Broker | | Service | # # +----------+ # # +---------+ +---------+ # # ^ | | # # | | | | # # | | | # # V | | | # # | | | # # +-----------------+ | | | # # | | +------#------#-->| Service Manager |<-+ | | # # | | # # +-----------------+ | | # # | | # # | | # # | +---------#------#--------------------------+ | # # +-----------+ # # | # # | Messenger |<--#------#----------------------------+ # # +-----------+ # # # # # # # #################### ################################### Client Object : An object that wishes to invoke a Service. Service : Provides a data processing function for the Client Object. Messenger : Receives messages from a Service and passes them onto the Client Object. The Messenger object is necessary because Client Objects are not implemented as CORBA Objects and hence are not available to the Service. Service Manager: Makes the Service and other server side objects such as the File Broker (not shown) available to the Client Object. There is one Service Manager created for every Service provided to Client Objects. Service Broker : Causes a Service to be created and provides it to a Client Object via a Service Manager. There is one persistent instance of a Service Broker responsible for taking requests from Client Objects to create Services. The process of providing a Service to a Client Object works as follows: 1) The Client Object creates a Messenger. 2) The Client Object requests a Service Manager from the Service Broker. The Messenger is passed to the Service Broker. 3) The Service Broker creates a Service Manager. The Messenger is passed to the Service manager 4) The Service Broker invokes a Service in an exec'ed process. The IOR of the Service Manager is passed to the Service. 5) The Service passes itself to the Service Manager indicating that it is ready. 6) The Service gets the Messenger from the Service Manager. 7) The Service sends messages to the Client object by invoking methods on the Messenger which relays the messages to the Client object. 8) The Service Broker queries the Service Manager until the Service Manager has received the Service. 9) The Service Broker returns the Service Manager to the Client. 10) The Client Object obtains the Service from the Service Manager, runs the Service, and receives messages from the Service. Required Development Items -------------------------- Items of LISP development provided by the DOC developers - A Base service class called doc-lisp-service which upon instantiation: - Passes itself to the Service Manager, - Gets the Messenger object from the Service Manager and provides access to the Messenger via a doc-messenger method. - "Main" program which will: - Parse the LISP image command line, - Determine, from the command line, the mode in which the LISP service will operate (CORBA access in the present scenario). - Instantiate the Service object. Items required by the LISP Service developers from the DOC developers: - LISP doc-lisp-service base class. - IDL description - The Service run/stop methods, - Possibly message error types. (It has not yet been decided whether these should be specified as strings or by the DOC_Messages::error_type.) (rsp2/controller/new_controller/services/service.idl) - LISP functions for sending messages back to the DOC. Items which the LISP Service developers are being asked to address: - Provide the implementation of a run method each for Service class. The interface for the run methods are specified in the IDL provided by the DOC developers. - Modify message generation to call the LISP DOC messenger functions: (doc-status-message text index maximum) (doc-error-message text error-type) (doc-log-message text) (doc-final-status-message text) (doc-other-message text) doc-status-message is used to indicate the progress of the service. A text message for display to user indicates the current processing task. Progress is indicated by an integer "index" on a scale from zero to an integer "maximum". doc-error-message is used to indicate that a problem has arisen. There are three types of error messages. It has not yet been decided whether these should be specified as strings or by the DOC_Messages::error_type specified in the service.idl file referenced above. a. Warning: Warnings are basic information that does not affect the proposal processing. b. Data Error: Refer to problems programs find with data. These include syntax errors, missing data, etc. c. System: System errors are caused by broken pieces of the system, like missing library, syntax errors in code, etc. doc-log-message is used to generate a generic message to be saved to a log file by the DOC. The service may log any message. The log messages are date and time stamped when written to the log file. doc-final-status-message is used to indicate that the service has run to completion, normally or not, and should return the same text string that is currently written to stdout upon completion. doc-other-message is used to send any other message to the DOC. At this time, this will have no effect, but is included to allow for passing other, as of yet undetermined, message functionality. Because the various LISP images may be invoked in access modes other than DOC/CORBA, a boolean LISP function called doc-mode-p will be provided by the DOC developers to indicate if the current access mode is via DOC/CORBA. The stop method on the LISP Services is not yet required because we do not fully understand what is capable under LISP to provide "cleanly" stopping separate threads. This functionality will be initially provided by externally killing the LISP process which will be required any way in order to kill a "frozen" LISP process.