org.ogf.saga.sd
Interface Discoverer

All Superinterfaces:

Cloneable, SagaObject

public interface Discoverer
extends SagaObject

Provides the entry point for service discovery. Apart from the constructor it has one method: listServices which returns the list of descriptions of services matching the specified filter strings.

An implementation SHOULD return the results in a random order if there is more than one result to avoid any tendency to overload particular services while leaving others idle.

There are three filter strings: serviceFilter, dataFilter and authzFilter which act together to restrict the set of services returned. Each of the filter strings uses SQL92 syntax as if it were part of a WHERE clause acting to select from a single table that includes columns as described below for that filter type. SQL92 has been chosen because it is widely known and has the desired expressive power. Multi-valued attributes are treated as a set of values.

Three strings are used, rather than one, as this clarifies the description of the functionality, avoids problems with key values being themselves existing GLUE attributes, and facilitates implementation as it makes it impossible to specify constraints that correlate, for example, service and authz information. Only the following operators are permitted in expressions not involving multi-valued attributes: IN, LIKE, AND, OR, NOT, =, >=, >, <=, <, <> in addition to column names, parentheses, column values as single quoted strings, numeric values and the comma. For a multi-valued attribute, the name of the attribute MUST have the keyword ALL or ANY immediately before it, unless comparison with a set literal is intended. For each part of the expression, the attribute name MUST precede the literal value. An implementation SHOULD try to give an informative error message if the filter string does not conform. It is, however, sufficient to report in which filter string the syntax error was found.

The LIKE operator matches string patterns:

'%xyz' matches all entries with trailing xyz

'xyz%' matches all entries with leading xyz

'%xyz%' matches all entries with xyz being a substring

The ESCAPE keyword can be used with LIKE in the normal way.

Column names are not case sensitive but values are.

No use-case has been identified for the operators >=, >, <=, > to be applied to strings. An Implementation wishing to support these comparison operators on strings MUST select a collation sequence. Alternatively, an implementation CAN treat all string comparisons as true, or reject them as invalid SQL.

Service Filter

Column names in the serviceFilter are:

Capabilities

identifiable aspects of functionality

ImplementationVersion

the version of the service implementation

Implementor

name of the organisation providing the implementation of the service

InterfaceVersion

the version of the service interface

Name

name of service (not necessarily unique)

RelatedServices

the uids of services related to the one being looked for

Site

name of site the service is running at

Type

type of service. This API does not restrict values of the service type -- it might be a DNS name, a URN or any other non-empty string.

Uid

unique identifier of service

Url

the endpoint to contact the service - will normally be used with the LIKE operator

Some examples are:

ANY Capabilities = 'org.ogf.saga.service.job'

Site IN ('INFN-CNAF', 'RAL-LCG2')

Type = 'org.glite.ResourceBroker' AND Site LIKE '%.uk' AND Implementor = 'EGEE'

ANY RelatedServices = 'someServiceUID'

Note the use of the ANY keyword in two of these examples as |Capabilities| and |RelatedServices| are multi-valued.

Data Filter

Column names in the the dataFilter string are matched against the service data key/value pairs. No keys are predefined by this specification.

If values are specified as numeric values and not in single quotes, the service data will be converted from string to numeric for comparison.

Data attributes may be multi-valued. If a dataFilter string does not have the correct syntax to accept multi-valued attributes, and a service has more than one value for an attribute mentioned in the filter, that service MUST be rejected.

Some examples are:

source = 'RAL-LCG2' OR destination = 'RAL-LCG2'

RunningJobs >= 1 AND RunningJobs <= 5

Authz Filter

The set of column names in the authzFilter is not defined. Instead the list below shows a possible set of names and how they might be interpreted. Each of these column names could reasonably be related to an authorization decision. Implementations MAY reuse the attribute names defined for the org.ogf.saga.context.Contex class.

Vo

virtual organization - will often be used with the IN operator

Dn

an X.509 ``distinguished name''

Group

a grouping of people within a Virtual Organization

Role

values might include ``Administrator'' or ``ProductionManager''

It is expected that many of the attributes used in the authzFilter will be multi-valued.

Some examples, where VO is assumed to be multi-valued are:

ANY Vo IN ('cms', 'atlas')

Vo = ('dteam')

Note the use of the set constructor in both examples. Being a set, ('aaa','bbbb') is of course the same as ('bbb', 'aaa').

The listServices method is overloaded: the last parameter the authzFilter may be omitted. If it is omitted the authorization filtering is performed on the contexts in the session. This is quite different from including the authzFilter parameter with an empty string which means that there is no authz filtering.

Field Summary

Fields inherited from interface org.ogf.saga.SagaObject

NO_WAIT, WAIT_FOREVER

Method Summary

List<ServiceDescription>	listServices(String serviceFilter, String dataFilter) Returns the set of services that pass the set of specified filters, an implicit authzFilter is constructed from the contexts of the session.
List<ServiceDescription>	listServices(String serviceFilter, String dataFilter, String authzFilter) Returns the set of services that pass the set of specified filters.

Methods inherited from interface org.ogf.saga.SagaObject

clone, getId, getSession

Method Detail

listServices

List<ServiceDescription> listServices(String serviceFilter,
                                      String dataFilter)
                                      throws AuthenticationFailedException,
                                             AuthorizationFailedException,
                                             BadParameterException,
                                             NoSuccessException,
                                             TimeoutException

Returns the set of services that pass the set of specified filters, an implicit authzFilter is constructed from the contexts of the session. Note that this is different from an empty authzFilter, as that would apply no authorization filter at all.

Parameters:

serviceFilter - a string containing the filter for filtering on the basic service and site attributes and on related services

dataFilter - a string containing the filter for filtering on key/value pairs associated with the service

Returns:

list of service descriptions, in a random order, matching the filter criteria

Throws:

AuthenticationFailedException - if none of the available session contexts could successfully be used for authentication

AuthorizationFailedException - if none of the available contexts of the used session could be used for successful authorization. That error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

BadParameterException - if any filter has an invalid syntax or if any filter uses invalid keys. However the dataFilter never signals invalid keys as there is no schema with permissible key names.

NoSuccessException - if no result can be returned because of information system or other internal problems

TimeoutException - if a remote operation did not complete successfully because the network communication or the remote service timed out

listServices

List<ServiceDescription> listServices(String serviceFilter,
                                      String dataFilter,
                                      String authzFilter)
                                      throws AuthenticationFailedException,
                                             AuthorizationFailedException,
                                             BadParameterException,
                                             NoSuccessException,
                                             TimeoutException

Returns the set of services that pass the set of specified filters. A service will only be included once in the returned list of services.

Parameters:

serviceFilter - a string containing the filter for filtering on the basic service and site attributes and on related services

dataFilter - a string containing the filter for filtering on key/value pairs associated with the service

authzFilter - a string containing the filter for filtering on authorization information associated with the service

Returns:

list of service descriptions, in a random order, matching the filter criteria

Throws:

AuthenticationFailedException - if none of the available session contexts could successfully be used for authentication

AuthorizationFailedException - if none of the available contexts of the used session could be used for successful authorization. That error indicates that the resource could not be accessed at all, and not that an operation was not available due to restricted permissions.

BadParameterException - if any filter has an invalid syntax or if any filter uses invalid keys. However the dataFilter never signals invalid keys as there is no schema with permissible key names.

NoSuccessException - if no result can be returned because of information system or other internal problems

TimeoutException - if a remote operation did not complete successfully because the network communication or the remote service timed out