Public Member Functions | Static Public Member Functions | Protected Member Functions

saga::sd::discoverer Class Reference

#include <discoverer.hpp>

Inheritance diagram for saga::sd::discoverer:

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 ()
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)
static discoverer create (saga::url loc=saga::url()) SAGA_THROW_SPEC() throw (saga::not_implemented, saga::incorrect_url, saga::not_implemented, 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.

Definition at line 179 of file discoverer.hpp.

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.

Definition at line 333 of file discoverer.hpp.

static discoverer saga::sd::discoverer::create ( saga::url  loc = saga::url()  )  throw (saga::not_implemented, saga::incorrect_url, saga::not_implemented, saga::authorization_failed, saga::authentication_failed, saga::timeout, saga::no_success) [inline, static]

Definition at line 379 of file discoverer.hpp.

template<typename Tag >
static saga::task saga::sd::discoverer::create ( saga::url  loc = saga::url()  )  [inline, static]

Definition at line 392 of file discoverer.hpp.

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

Definition at line 442 of file discoverer.hpp.

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

Definition at line 497 of file discoverer.hpp.

References saga::task::get_result().

The documentation for this class was generated from the following file:
Generated on Mon Jun 25 2012 12:33:33 for SAGA C++ API by  doxygen 1.7.1