org.csapi.jr.se.fw.fw_application.discovery
Interface ServiceDiscovery

All Superinterfaces:
CsapiInterface, java.io.Serializable

public interface ServiceDiscovery
extends CsapiInterface

The service discovery interface, shown below, consists of four methods. Before a service can be discovered, the enterprise operator (or the client applications) must know what "types" of services are supported by the Framework and what service "properties" are applicable to each service type. The listServiceType() method returns a list of all "service types" that are currently supported by the framework and the "describeServiceType()" returns a description of each service type. The description of service type includes the "service-specific properties" that are applicable to each service type. Then the enterprise operator (or the client applications) can discover a specific set of registered services that both belong to a given type and possess the desired "property values", by using the "discoverService() method. Once the enterprise operator finds out the desired set of services supported by the framework, it subscribes to (a sub-set of) these services using the Subscription Interfaces. The enterprise operator (or the client applications in its domain) can find out the set of services available to it (that is, the service that it can use) by invoking "listSubscribedServices()". The service discovery APIs are invoked by the enterprise operators or client applications. They are described below. 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 a client application is able to obtain the service IDs of the services that meet its requirements.
 java.lang.String[] listServiceTypes()
          This operation returns the names of all service super and sub types that are in the repository.
 org.csapi.jr.se.fw.Service[] listSubscribedServices()
          Returns a list of services so far subscribed by the enterprise operator.
 

Method Detail

listServiceTypes

public java.lang.String[] listServiceTypes()
                                    throws CommonException,
                                           AccessDeniedException,
                                           PlatformException
This operation returns the names of all service super and sub types that are in the repository. The details of the service types can then be obtained using the describeServiceType() method. If a sub type of a service is registered, this method returns, besides the sub type, also the super type. Returns : The names of the requested service types.

Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
AccessDeniedException - The client is not currently authenticated with the framework
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,
                                                                     AccessDeniedException,
                                                                     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.
AccessDeniedException - The client is not currently authenticated with the framework
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,
                                                    AccessDeniedException,
                                                    IllegalServiceTypeException,
                                                    UnknownServiceTypeException,
                                                    InvalidPropertyException,
                                                    PlatformException
The discoverService operation is the means by which a client application is able to obtain the service IDs of the services that meet its requirements. The client application 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 client application 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 client application provided. The service properties returned form a complete view of what the client application can do with the service, as per the service level agreement. If the framework supports service subscription, the service level agreement will be encapsulated in the subscription properties contained in the contract/profile for the client application, which will be a restriction of the registered properties. 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 "serviceTypeName" parameter conveys the required service type. It is key to the central purpose of "service trading". It is the basis for type safe interactions between the service exporters (via registerService) and service importers (via discoverService). By stating a service type, the importer implies the service type and a domain of discourse for talking about properties of service. · 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. The requestor may also request for a service of a specific subtype. The framework will not return the corresponding supertype(s) in this case.
desiredPropertyList - The "desiredPropertyList" parameter is a list of service property {name, mode and value list} tuples that the discovered set of 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. The desiredPropertyList only contains service properties that are relevant for the application. If an application is not interested in the value of a certain service property, this service property shall not be included in the desiredPropertyList. P_INVALID_PROPERTY is raised when an application includes an unknown service property name or invalid service property value.
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.
AccessDeniedException - The client is not currently authenticated with the framework
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

listSubscribedServices

public org.csapi.jr.se.fw.Service[] listSubscribedServices()
                                                    throws CommonException,
                                                           AccessDeniedException,
                                                           PlatformException
Returns a list of services so far subscribed by the enterprise operator. The enterprise operator (or the client applications in the enterprise domain) can obtain a list of subscribed services that they are allowed to access. Returns : The "serviceList" parameter returns a list of subscribed 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.
AccessDeniedException - The client is not currently authenticated with the framework
PlatformException - The implementation detected an internal (for example, communication) error