org.csapi.jr.se.fw.fw_service.discovery
Interface FwServiceDiscovery

All Superinterfaces:
CsapiInterface, java.io.Serializable

public interface FwServiceDiscovery
extends CsapiInterface

This interface shall be implemented by a Framework with as a minimum requirement the listServiceTypes(), describeServiceType() and discoverService() methods.


Method Summary
 org.csapi.jr.se.fw.ServiceTypeDescription describeServiceType(java.lang.String name)
          This operation lets the caller obtain the details for a particular service type.
 org.csapi.jr.se.fw.Service[] discoverService(java.lang.String serviceTypeName, org.csapi.jr.se.fw.ServiceProperty[] desiredPropertyList, int max)
          The discoverService operation is the means by which the service supplier can retrieve a specific set of registered services that both belong to a given type and possess a specific set of "property values".
 org.csapi.jr.se.fw.Service[] listRegisteredServices()
          Returns a list of services so far registered in the framework.
 java.lang.String[] listServiceTypes()
          This operation returns the names of all service types that are in the repository.
 

Method Detail

listServiceTypes

public java.lang.String[] listServiceTypes()
                                    throws CommonException,
                                           PlatformException
This operation returns the names of all service types that are in the repository. The details of the service types can then be obtained using the describeServiceType() method. Returns : The names of the requested service types.

Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

describeServiceType

public org.csapi.jr.se.fw.ServiceTypeDescription describeServiceType(java.lang.String name)
                                                              throws CommonException,
                                                                     IllegalServiceTypeException,
                                                                     UnknownServiceTypeException,
                                                                     PlatformException
This operation lets the caller obtain the details for a particular service type. Returns : The description of the specified service type. The description provides information about: the service properties associated with this service type: that is a list of service property {name, mode and type} tuples, the names of the super types of this service type, and whether the service type is currently available or unavailable.

Parameters:
name - The name of the service type to be described. If the "name" is malformed, then the P_ILLEGAL_SERVICE_TYPE exception is raised. If the "name" does not exist in the repository, then the P_UNKNOWN_SERVICE_TYPE exception is raised.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
IllegalServiceTypeException - Illegal Service Type
UnknownServiceTypeException - Unknown Service Type
PlatformException - The implementation detected an internal (for example, communication) error

discoverService

public org.csapi.jr.se.fw.Service[] discoverService(java.lang.String serviceTypeName,
                                                    org.csapi.jr.se.fw.ServiceProperty[] desiredPropertyList,
                                                    int max)
                                             throws CommonException,
                                                    IllegalServiceTypeException,
                                                    UnknownServiceTypeException,
                                                    InvalidPropertyException,
                                                    PlatformException
The discoverService operation is the means by which the service supplier can retrieve a specific set of registered services that both belong to a given type and possess a specific set of "property values". The service supplier passes in a list of desired service properties to describe the service it is looking for, in the form of attribute/value pairs for the service properties. The service supplier also specifies the maximum number of matched responses it is willing to accept. The framework must not return more matches than the specified maximum, but it is up to the discretion of the Framework implementation to choose to return less than the specified maximum. The discoverService() operation returns a serviceID/Property pair list for those services that match the desired service property list that the service supplier provided. Returns : This parameter gives a list of matching services. Each service is characterised by its service ID and a list of service properties {name and value list} associated with the service.

Parameters:
serviceTypeName - The name of the required service type. If the string representation of the "type" does not obey the rules for service type identifiers, then the P_ILLEGAL_SERVICE_TYPE exception is raised. If the "type" is correct syntactically but is not recognised as a service type within the Framework, then the P_UNKNOWN_SERVICE_TYPE exception is raised. The framework may return a service of a subtype of the "type" requested. A service sub-type can be described by the properties of its supertypes.
desiredPropertyList - The "desiredPropertyList" parameter is a list of service properties {name and value list} that the required services should satisfy. These properties deal with the non-functional and non-computational aspects of the desired service. The property values in the desired property list must be logically interpreted as "minimum", "maximum", etc. by the framework (due to the absence of a Boolean constraint expression for the specification of the service criterion). It is suggested that, at the time of service registration, each property value be specified as an appropriate range of values, so that desired property values can specify an "enclosing" range of values to help in the selection of desired services.
max - The "max" parameter states the maximum number of services that are to be returned in the "serviceList" result.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
IllegalServiceTypeException - Illegal Service Type
UnknownServiceTypeException - Unknown Service Type
InvalidPropertyException - The framework does not recognise the property supplied by the client
PlatformException - The implementation detected an internal (for example, communication) error

listRegisteredServices

public org.csapi.jr.se.fw.Service[] listRegisteredServices()
                                                    throws CommonException,
                                                           PlatformException
Returns a list of services so far registered in the framework. Returns : The "serviceList" parameter returns a list of registered services. Each service is characterised by its service ID and a list of service properties {name and value list} associated with the service.

Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error