Package org.ogf.saga.sd

This API provides a mechanism to locate services.

See:
Description

Interface Summary

Discoverer	Provides the entry point for service discovery.
ServiceData	Read access to the key/value pairs of a ServiceDescription instance.
ServiceDescription	Read access to the top level data of the service and a means to navigate to related services.

Class Summary

SDFactory

Factory for the creation of Discoverer objects.

Package org.ogf.saga.sd Description

This API provides a mechanism to locate services.

It is expected that this Service Discovery API will make use of various information systems or other service discovery mechanisms. The quality of the information returned will depend upon the quality of the data in the back-end system or systems.

Service Model

This API is based upon the GLUE (version 1.3) model of a service. This service model is also compatible with GLUE 2.0. A Site may host many Services and a Service has multiple ServiceData entries associated with it. Each ServiceData entry is represented by a key and a value, thus allowing any set of keyword/value pairs to be associated with an instance of a Service. In addition, a Service has a many-to-many relationship with itself. This allows the model to describe groupings of services.

It is possible that this Service Discovery API may be incompatible with a future version of GLUE. This issue will be addressed, if necessary, in a future revision of this API.

Classes

This API has a SDFactory class for the creation of Discoverer objects. There are two optional arguments for creating a Discoverer, org.ogf.saga.session and org.ogf.saga.url. The URL is to assist the implementation to locate the underlying information system such that it can be queried.

The Discoverer class has a single method: listServices. This method returns a list of objects of the ServiceDescription class, filtered according to several specified filters.

The ServiceDescription class has three methods. One of these, getUrl, is all that most people will use to obtain the address registered for the service. In the case of a Web Service, this will be the service endpoint. It also implements the org.ogf.saga.attributes.Attributes interface, and thus exposes additional ReadOnly properties of the service, such as its type and uid. These might be used by those who wish to generate a web page of services, or need detailed information for other purposes. There is a method getRelatedServices that returns the set of related ServiceDescription objects, which represent related services. Finally, there is a method getData to access the set of further key value pairs. This method returns a ServiceData object, which also implements the org.ogf.saga.attributes.Attributes interface giving ReadOnly access to all the key names and values in the ServiceData object.

By making the ServiceDescription implement the org.ogf.saga.attributes.Attributes interface, and by referencing a separate ServiceData object holding the key value pairs, potential key name clashes between the sets of pre-defined and free-form attributes are avoided.

Details

This API will typically use some underlying information system and should not contact the services to check their availability. The user must expect that a service provided by the Service Discovery API may not be available. Even if the API were to contact a service to confirm its availability, by the time the user attempts to use that service, it may have failed. Similarly the API cannot be guaranteed to provide a complete set of matching services - it is the responsibility of the implementation to apply any algorithm it chooses to return a set of services.

The API may try to use an underlying information system but not be able to access it. The precise behaviour is implementation dependent - for example if it uses adapters it may try a different one. If no result can be returned because of information system or other internal problems, it SHOULD throw the org.ogf.saga.error.NoSuccessException exception. Note that an implementation MAY choose to return search results from multiple backend services. In the case of an adaptor based implementation, several adaptors may get queried at once, and the results may be collated into a single list, if the specified URL does not limit the range of usable adaptors.

Since:

not released