SDLIP Server Development Kit

• Readme.html  -  this readme file
• Proxy.java, ProxyHelper.java, SourcePlugInterface.java, SessionHandler.java - the core toolkit source files
• Server.java -  the startup class to instantiate the server and register it with the ORB
• sdlip.idl  - the IDL definition of the SDLIP protocol

Note : By "data-source", I  mean any searchable source of data such as web search engines, databases, electronic catalogs, etc.

Model

• Requests from the client will be received by a persistent Proxy object (defined in Proxy.java) that would have been made available to the ORB when the Server is started up.
• The Proxy object instantiates a SessionHandler object (defined in SessionHandler.java) for every new search request that it receives and delegates all future work for that session to the newly created object. Both the Proxy object and the SessionHandler object assume the existence of a SourcePlug class that implements the SourcePlugInterface interface (defined in SourcePlugInterface.java).
• Every SessionHandler creates one instance of this SourcePlug class and uses the methods defined in the interface to execute queries and receive search results. At least conceptually, the SourcePlug stores the retrieved documents in a private result array. The SessionHandler object specifies the documents using a zero-based index into this array.  If the SessionHandler specifies one or more array indexes that are greater than what is currently available in the SourcePlug's result array, this causes the SourcePlug to go back to the data source and retrieve more documents. Of course, a particular implementaion of the SourcePlug could retrieve all result documents from the data source and actually store them in a private cache in which case it will not need to go back to the data source in future.
• The SourcePlug maintains enough state that it can retrieve more documents from the actual data source later on if required.

The SourcePlug class and Interface

Constructors :

• SourcePlug( )     -   the default constructor. This is used by the Proxy object to get access to methods like getPropertyInfo( ) and  getSubcolName( ) that are independent of any specific session.
• SourcePlug(String queryLanguage, String query, String[] docProps) - This is the constructor that will be used when the SessionHandler object needs to instantiate a SourcePlug object to handle a particular session. The parameter semantics should be obvious from the parameter names (if not, consult the javadoc documentation present in SourcePlugInterface.java).

Methods and Constants:

• int BAD_LANG     -   a constant integer error code that denotes a bad query language parameter
• int BAD_QUERY  -   a constant integer error code that denotes an incorrectly formatted query string
• int BAD_PROPS   -   a constant integer error code that denotes unavailable/unkown document properties
• int ALL_OKAY    -   a constant integer status code when none of the three error conditions listed above are encountered
• int validateRequest ( )   -  validate the three parameters that have been passed in the constructor (second type of constructor) and generate an appropriate integer code (one of the four constants  listed above) representing the result of the validation
• String getPropertyInfo( )  - generate and return an XML string representing the underlying attribute model of the data source being served out. For more details on the format of this XML string, refer to the SDLIP protocol specification.
• int getTimeOut(int timeOutReq)  - the parameter for this method is the amount of time for which the client wishes the server to retain state. The return value is the amount of time for which the server is willing to retain state. If the parameter has a value of -1, it means that the client is requesting that state be maintained forever.
• int extendTime(int additionalTime)  - the parameter for this method is the amount by which the client wishes to extend the state timeout. The return value is the additional time for which the server is willing to retain state.
• int getResultSize ( )  - the number of documents that can be expected in the result set for the query. Value is -1 if the total number of documents cannot be determined.
• int String getResult (String[] propList, String docsToGet) throws Exception  -  This is the method that actually returns the result documents to the SessionHandler. The propList parameter is the list of properties to be returned for each document. The docsToGet paramter is a suitably formatted list of document indexes that specify which documents are to be retrieved (for the format of this String, refer to the SDLIP protocol specification). The return value for this method should be an XML string that confirms to the SearchResult DTD described in the SDLIP protocol specification. Exceptions can be raised when one or more of the input parameters are incorrect. If an error is encountered in the propList parameter, a java.lang.Exception is thrown with the following string as the descriptive message - "INVALID PROPS". On the other hand, if an error is encountered in the format or content of the docsToGet parameter, a java.lang.Exception is thrown with the following string as the descriptive message - "INVALID DOC INDICES". Note that in both cases, the descriptive message should be exactly identical to what has been mentioned here, including the capital letters, spaces, etc.
• String getSubcolName ( )  - return a String representing the name by which this data source will be identified in a list of subcollections. For details on the format of the subcollection lists and their uses, refer to the SDLIP protocol specification.

Compiling and Running the SDLIP Server

• Run    idl2java sdlip.idl This will create a directory called SDLIP and dump a lot of source files in it
• Since the Proxy and the SessionHandler objects make use of services provided by the XMLServices package and the SdlipUtils.XML package, make sure that these two packages are included int the current CLASSPATH.
• Compile the Server using    vbjc Server.java
• Decide on a logcial name (a String constant) with which this SDLIP server will be associated on the ORB. This is the name that clients will use to get a handle to this server obejct.
• Verify that a Visibroker smart agent is running somewhere on the local network. If not, start one using the command    osagent -v
• Run the server using       vbj Server <logical-name>  where <logical-name> is the one described in the previous step

For any questions and clarifications, please contact rsram@cs.stanford.edu