no.ubicollab.osgi.service.discoverymanager
Interface ServiceDiscovery

All Known Implementing Classes:
DiscoveryManagerImpl

public interface ServiceDiscovery

This is the interface exported by the UbiCollab Service Discovery Manager (SDM). The methods provides Service Discovery (SD) access for UbiCollab applications and tools. In addition this module is general enough to also be used by other applications which is able to connect through the soap interface.

The principal functionality for the SDM is to be the broker between Service Discovery (SD) client applications (consumers) and SD plugins (producers). Client applications register their interests with the SDM and this information is passed on to the SD plugins which will search for matching services. The SD plugins will then register matching services in the queue that is assigned to the SD client, and he will retrive them from here.

Both clients and plugins must register with the SDM, before they can enter or retrieve any requests/interests. To maintain the principle of loose coupling, there is no unregister methods. Instead, sessions will be terminated by timeout.

Since:
0.1
Version:
0.6
Author:
Kim-Steve Johansen

Method Summary
 java.lang.String getClientRequest(int pluginID)
          Method where SD plugins can get the interests/requests registered by the SDM client(s).
 java.lang.String getLogItems(int logLevel, int numItems)
          Read from the log and return selected log items in a XML-formatted string.
 java.lang.String getSDPlugins()
          Method to return a list of the SD plugins which are registered with the SDM.
 java.lang.String getServices(int clientID)
          Return the result queue identified by the provided search request ID.
 int registerClient()
          This method allows any authenticated user (consumer/client app) to register as a client with the Service Discovery Manager (SDM).
 boolean registerClientRequest(int clientID, java.lang.String name, java.lang.String type, java.lang.String location, java.lang.String owner, java.lang.String description)
          This method allows any authenticated user (client) to register a search request with the Service Discovery Manager.
 int registerSDPlugin(java.lang.String protocolName)
          Register a Service Discovery plugin with the Service Discovery Manager.
 boolean registerService(int searchRequestorID, int protocolID, java.lang.String descriptionURI, java.lang.String serviceURI, java.lang.String friendlyName, java.lang.String type, java.lang.String description, java.lang.String owner, java.lang.String location)
          This method is provided for service discovery plugins to register services which matches client requests, with the Service Discovery Manager.
 

Method Detail

registerClient

int registerClient()
This method allows any authenticated user (consumer/client app) to register as a client with the Service Discovery Manager (SDM). When a client is registered a service queue is created and assigned to him. In this queue all services matching requests from the client will be placed, as well as services discovered by user initiated physical SD plugins like RFID.

Upon registration the client will also be assigned a unique ID which will be used for identification when sending messages/communicating with the SDM. The client will also be assigned a time-to-live which initially is set to 1 minute. Every time the client invokes getServices() this time will be reset. If a client fails to connect to SDM for 1 minute, his session will be garbage collected (by the housekeeper thread).

Returns:
the unique ID to be used for identification when communicating with the SDM.

registerClientRequest

boolean registerClientRequest(int clientID,
                              java.lang.String name,
                              java.lang.String type,
                              java.lang.String location,
                              java.lang.String owner,
                              java.lang.String description)
This method allows any authenticated user (client) to register a search request with the Service Discovery Manager. The manager will then make this request available to all registered service discovery plugins

After the request is placed, the client will get an ID which points to the queue of services found. This ID can then be used to poll for, and retrieve matching services using getServices.

When a request is placed the queue spawned will have a lifetime of 1 minute, and when the queue is queried a fresh minute is awarded.

Parameters:
owner - the Owner of the service
type - the service type to search for
description - the description of the service
location - the location of the service
clientID - the unique client ID
name - the name of the service to search for
Returns:
true, if client request is registered successfully, false otherwise.

getServices

java.lang.String getServices(int clientID)
Return the result queue identified by the provided search request ID. After the results are returned they will be removed from the queue.

The xml-structure used to represent the returned service list is:

   <?xml version='1.0'?>
      <Servicelist>
         <Service Protocol="String" 
            Name="String" 
            ServiceUri="String" 
            Location="String" 
            Owner="String" 
            DescriptionUri="String"
            Type="String" 
            Description="String"/>
... more services ...
</Servicelist>

Parameters:
clientID - the client ID (used to select the correct queue)
Returns:
The method returns "No matching services" if none are found (queue empty). "No such ID" if unknown or timed out ID. Otherwise a XML-formatted list of services is returned.

registerSDPlugin

int registerSDPlugin(java.lang.String protocolName)
Register a Service Discovery plugin with the Service Discovery Manager. When a plugin is registered it will get a unique ID which will be used for further communication.

The registration will have a lifespan of 30 seconds, and will be reset to 30 second every time getClientRequest() or registerService() is invoked. When this time runs out the plugin session will be garbage collected (by the housekeeper thread).

Parameters:
protocolName - the name of the protocol, e.g. UPnP or RFID
Returns:
the ID for identifying the plugin

getClientRequest

java.lang.String getClientRequest(int pluginID)
Method where SD plugins can get the interests/requests registered by the SDM client(s).

The returned string is a well formatted XML-string with the following structure:

   <?xml version='1.0'?>
      <ClientRequestList>
         <ClientRequest ClientID="int" 
            Name="String" 
            Type="String" 
            Location="String"
            Owner="String"
            Description="String"/>
          ... more ClientRequest items ...
</ClientRequestList>

Parameters:
pluginID - the plugin ID
Returns:
A xml-formatted String containing the client request if any requests have been registered

registerService

boolean registerService(int searchRequestorID,
                        int protocolID,
                        java.lang.String descriptionURI,
                        java.lang.String serviceURI,
                        java.lang.String friendlyName,
                        java.lang.String type,
                        java.lang.String description,
                        java.lang.String owner,
                        java.lang.String location)
This method is provided for service discovery plugins to register services which matches client requests, with the Service Discovery Manager. The service will be added to the queue identified by the provided searchRequestID. This method provides many options as parameters and all of these will not be applicable for each plugin. The ones not used should simply contain an empty string.

Parameters:
friendlyName - The user-friendly name of the service
descriptionURI - URI for service description (e.g. the URL to a WSDL-file).
type - The service type (classification)
owner - The person/company/responsible for the service.
description - Tags (words or short sentences) describing the service.
location - Location where the service can be found
searchRequestorID - the ID for the search request queue to add this service to
protocolID - The id for the service discovery protocol plugin.
serviceURI - The URI to invoke the service
Returns:
True if the service is successfully registered, false if the client id or protocol id does not exist.

getSDPlugins

java.lang.String getSDPlugins()
Method to return a list of the SD plugins which are registered with the SDM. Usefull for client who want to know which SD protocols they have support for.

The list returned is a well-formed xml-document, with the following structure:

 <Pluginlist>
   <Plugin Name="String" 
   Id="int" />
... more plugins ...
</Pluginlist>

Returns:
a list contained in a String with the SD plugins.

getLogItems

java.lang.String getLogItems(int logLevel,
                             int numItems)
Read from the log and return selected log items in a XML-formatted string. The levels with equal or higher severity than what have been queried for will be retuned.

The log levels are defined as follows:

 Level - description
   0   - DEBUG
   1   - INFO
   2   - WARNING
   3   - ERROR
   4   - FATAL
 
 

The xml-structure used to represent the returned log is:

   <?xml version='1.0'?>
      <Log>
          <Logitem Date="dd.mm.yyyy" 
            Time="hh:mm:ss" 
            LevelID="int" 
            Level="String" 
            Message="String"/>
... more log items ...
</Log>

Parameters:
logLevel - The log level to include in the report.
numItems - The number of log items to include in the report
Returns:
the String containg the resulting XML-document