# saga::sd::discoverer Class Reference

`#include <discoverer.hpp>`

Inheritance diagram for saga::sd::discoverer:

[legend]

List of all members.

## Public Member Functions
| discoverer (saga::url loc=saga::url()) SAGA_THROW_SPEC() throw (saga::not_implemented, saga::incorrect_url, saga::does_not_exist, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)
| discoverer (session const &s, saga::url loc=saga::url()) SAGA_THROW_SPEC() throw (saga::not_implemented, saga::incorrect_url, saga::does_not_exist, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)
| ~discoverer (void) SAGA_THROW_SPEC() throw ()
| SAGA_CALL_CREATE_2_DEF_1 (session const &, saga::url, saga::url()) static discoverer create(saga
discoverer & | operator= (saga::object const &o) SAGA_THROW_SPEC() throw ()
std::vector < saga::sd::service_description > | list_services (std::string service_filter, std::string data_filter, std::string authz_filter) SAGA_THROW_SPEC() throw (saga::bad_parameter, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)
std::vector < saga::sd::service_description > | list_services (std::string service_filter, std::string data_filter) SAGA_THROW_SPEC() throw (saga::bad_parameter, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)
## Static Public Member Functions
static discoverer | create (session const &s, saga::url loc=saga::url()) SAGA_THROW_SPEC() throw (saga::not_implemented, saga::incorrect_url, saga::does_not_exist, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)
template<typename Tag>
static saga::task | create (saga::url loc=saga::url())
## Protected Member Functions
TR1::shared_ptr < saga::impl::discoverer > | get_impl_sp (void) const
saga::impl::discoverer * | get_impl (void) const
| discoverer (saga::impl::discoverer *impl) SAGA_THROW_SPEC() throw (saga::not_implemented, saga::incorrect_url, saga::does_not_exist, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)

## Detailed Description

Provides the entry point for service discovery. Apart from the constructor and destructor it has one method: `list_services` 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: `svc_filter`, `authz_filter` and `data_filter` 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 `&g./saga/saga/call.hppt=`, `>`, `<=`, `>` 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:

`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 string.
`name`
  name of service (not necessarily unique)
`uid`
  unique identifier of service
`site`
  name of site the service is running at
`url`
  the endpoint to contact the service - will normally be used with the LIKE operator
`implementor`
  name of the organisation providing the implementation of the service
`relatedService`
  the uid of a service related to the one being looked for

Some examples are:
  `type = 'org.ogf.saga.service.job'` `site IN ('INFN-CNAF', 'RAL-LCG2')` `type = 'org.glite.ResourceBroker' AND Site LIKE '%.uk' AND implementor = 'EGEE'` `ANY relatedService = 'someServiceUID'`

Note the use of the `ANY` keyword in the last example as `relatedService` is multi-valued.

## Data Filter

Column names in the the `data_filter` 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 `data_filter` 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 `authz_filter` 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 saga::context 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 then `authzFilter` will be multi-valued.

Some examples, where `VO` is assmed 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.

## Constructor & Destructor Documentation

saga::sd::discoverer::discoverer | ( | saga::impl::discoverer * | impl | ) | throw (saga::not_implemented, saga::incorrect_url, saga::does_not_exist, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)`[explicit, protected]`

saga::sd::discoverer::discoverer | ( | saga::url | loc = `saga::url()` | ) | throw (saga::not_implemented, saga::incorrect_url, saga::does_not_exist, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)`[explicit]`

Default constructor. Constructs a discoverer object using a default session.

Parameters:

  | loc | URL to use.

Exceptions:

  | not_implemented | if the discoverer class is not implemented by the SAGA implementation at all.
  | incorrect_url | if an implementation cannot handle the specified protocol, or that access to the specified entity via the given protocol is impossible.
  | does_not_exist | if the url is syntactically valid, but no service can be contacted at that URL.
  | authorization_failed | 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.
  | authentication_failed | if none of the available session contexts could successfully be used for authentication.
  | timeout | if a remote operation did not complete successfully because the network communication or the remote service timed out.
  | no_success | if no result can be returned because of information system or other internal problems.

saga::sd::discoverer::discoverer | ( | session const & | s,
|  | saga::url | loc = `saga::url()` |
| ) |  |  | throw (saga::not_implemented, saga::incorrect_url, saga::does_not_exist, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)`[explicit]`

Constructor. Constructs a discoverer object using the given session.

Parameters:

  | s | Session to use.
  | loc | URL to use.

Exceptions:

  | not_implemented | if the discoverer class is not implemented by the SAGA implementation at all.
  | incorrect_url | if an implementation cannot handle the specified protocol, or that access to the specified entity via the given protocol is impossible.
  | does_not_exist | if the url is syntactically valid, but no service can be contacted at that URL.
  | authorization_failed | 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.
  | authentication_failed | if none of the available session contexts could successfully be used for authentication.
  | timeout | if a remote operation did not complete successfully because the network communication or the remote service timed out.
  | no_success | if no result can be returned because of information system or other internal problems.

saga::sd::discoverer::~discoverer | ( | void |  | ) | throw ()

Destructor

## Member Function Documentation

TR1::shared_ptr<saga::impl::discoverer> saga::sd::discoverer::get_impl_sp | ( | void |  | ) | const`[protected]`

saga::impl::discoverer* saga::sd::discoverer::get_impl | ( | void |  | ) | const`[protected]`

static discoverer saga::sd::discoverer::create | ( | session const & | s,
|  | saga::url | loc = `saga::url()` |
| ) |  |  | throw (saga::not_implemented, saga::incorrect_url, saga::does_not_exist, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)`[inline, static]`

discoverer factory. Constructs a discoverer object using the given session.

Parameters:

  | s | Session to use.
  | loc | URL to use.

Exceptions:

  | not_implemented | if the discoverer class is not implemented by the SAGA implementation at all.
  | incorrect_url | if an implementation cannot handle the specified protocol, or that access to the specified entity via the given protocol is impossible.
  | does_not_exist | if the url is syntactically valid, but no service can be contacted at that URL.
  | authorization_failed | 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.
  | authentication_failed | if none of the available session contexts could successfully be used for authentication.
  | timeout | if a remote operation did not complete successfully because the network communication or the remote service timed out.
  | no_success | if no result can be returned because of information system or other internal problems.

saga::sd::discoverer::SAGA_CALL_CREATE_2_DEF_1 | ( | session const & | ,
|  | saga::url | ,
|  | saga:: | url() |
| ) |  |  | `[inline]`

template<typename Tag>

static saga::task saga::sd::discoverer::create | ( | saga::url | loc = `saga::url()` | ) | `[inline, static]`

discoverer& saga::sd::discoverer::operator= | ( | saga::object const & | o | ) | throw ()

std::vector<saga::sd::service_description> saga::sd::discoverer::list_services | ( | std::string | service_filter,
|  | std::string | data_filter,
|  | std::string | authz_filter |
| ) |  |  | throw (saga::bad_parameter, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)`[inline]`

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:

  | service_filter | a string containing the filter for filtering on the basic service and site attributes and on related services
  | data_filter | a string containing the filter for filtering on key/value pairs associated with the service
  | authz_filter | 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

Exceptions:

  | bad_parameter | 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.
  | authorization_failed | 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.
  | authenticationfailed | if none of the available session contexts could successfully be used for authentication
  | timeout | if a remote operation did not complete successfully because the network communication or the remote service timed out
  | no_success | if no result can be returned because of information system or other internal problems

References saga::task::get_result().

Referenced by saga::sd::service_description::get_related_services().

std::vector<saga::sd::service_description> saga::sd::discoverer::list_services | ( | std::string | service_filter,
|  | std::string | data_filter |
| ) |  |  | throw (saga::bad_parameter, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success)`[inline]`

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

Parameters:

  | service_filter | a string containing the filter for filtering on the basic service and site attributes and on related services
  | data_filter | 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

Exceptions:

  | bad_parameter | 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.
  | authorization_failed | 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.
  | authentication_failed | if none of the available session contexts could successfully be used for authentication
  | timeout | if a remote operation did not complete successfully because the network communication or the remote service timed out
  | no_success | if no result can be returned because of information system or other internal problems

References saga::task::get_result().

The documentation for this class was generated from the following file:

- discoverer.hpp