[Saga-devel] saga SVN commit 3334: /trunk/
paul.livesey at stfc.ac.uk
paul.livesey at stfc.ac.uk
Mon Jan 19 09:02:06 CST 2009
User: svn_plivesey
Date: 2009/01/19 09:02 AM
Modified:
/trunk/adaptors/bqp/sd/
bqp_sd_discoverer.cpp, bqp_sd_discoverer.hpp
/trunk/adaptors/default/sd/
default_discoverer.cpp, default_discoverer.hpp
/trunk/saga/impl/packages/sd/
discoverer.cpp, discoverer.hpp, discoverer_cpi.hpp, info_provider.hpp, service_description.cpp, service_description.hpp
/trunk/saga/saga/packages/sd/
discoverer.cpp, discoverer.hpp, service_data.hpp, service_description.cpp, service_description.hpp
Log:
Addition of 2 parameter version of list_services() method.
This vesrion does not take a vo_filter string, it is
up to the adapter to provide an appropriate default.
Also, Doxygen documentation added for discoverer,
service_description and service_data classes.
File Changes:
Directory: /trunk/adaptors/bqp/sd/
==================================
File [modified]: bqp_sd_discoverer.cpp
Delta lines: +7 -7
===================================================================
--- trunk/adaptors/bqp/sd/bqp_sd_discoverer.cpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/adaptors/bqp/sd/bqp_sd_discoverer.cpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -34,17 +34,17 @@
/////////////////////////////////////////////////////////////////////////////
//
-void discoverer_cpi_impl::sync_list_services (std::vector<saga::sd::service_description>& retval,
- std::string svc_filter,
- std::string data_filter)
+void discoverer_cpi_impl::sync_list_services2 (std::vector<saga::sd::service_description>& retval,
+ std::string svc_filter,
+ std::string data_filter)
{
}
/////////////////////////////////////////////////////////////////////////////
//
-void discoverer_cpi_impl::sync_list_services (std::vector<saga::sd::service_description>& retval,
- std::string svc_filter,
- std::string vo_filter,
- std::string data_filter)
+void discoverer_cpi_impl::sync_list_services3 (std::vector<saga::sd::service_description>& retval,
+ std::string svc_filter,
+ std::string vo_filter,
+ std::string data_filter)
{
}
File [modified]: bqp_sd_discoverer.hpp
Delta lines: +7 -7
===================================================================
--- trunk/adaptors/bqp/sd/bqp_sd_discoverer.hpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/adaptors/bqp/sd/bqp_sd_discoverer.hpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -39,14 +39,14 @@
~discoverer_cpi_impl (void);
- void sync_list_services (std::vector<saga::sd::service_description>&,
- std::string svc_filter,
- std::string data_filter);
+ void sync_list_services2 (std::vector<saga::sd::service_description>&,
+ std::string svc_filter,
+ std::string data_filter);
- void sync_list_services (std::vector<saga::sd::service_description>&,
- std::string svc_filter,
- std::string vo_filter,
- std::string data_filter);
+ void sync_list_services3 (std::vector<saga::sd::service_description>&,
+ std::string svc_filter,
+ std::string vo_filter,
+ std::string data_filter);
};
Directory: /trunk/adaptors/default/sd/
======================================
File [modified]: default_discoverer.cpp
Delta lines: +17 -4
===================================================================
--- trunk/adaptors/default/sd/default_discoverer.cpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/adaptors/default/sd/default_discoverer.cpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -38,25 +38,38 @@
/*
* SAGA API functions
*/
-void discoverer_cpi_impl::sync_list_services (
+void discoverer_cpi_impl::sync_list_services3 (
std::vector<saga::sd::service_description>& retval, std::string svc_filter,
std::string vo_filter, std::string data_filter)
{
}
+void discoverer_cpi_impl::sync_list_services2 (
+ std::vector<saga::sd::service_description>& retval, std::string svc_filter,
+ std::string data_filter)
+{
+}
+
#if ! defined(SAGA_DEFAULT_FILE_ADAPTOR_NO_ASYNCS)
///////////////////////////////////////////////////////////////////////////////
// The async call is something special because it creates a new connection to
// the XmlRpc server which is used for this call only. Note that the async
// close has no relation to this and does not influence any of the connections
// created by the async call.
-saga::task discoverer_cpi_impl::async_list_services (
+saga::task discoverer_cpi_impl::async_list_services3 (
std::string svc_filter, std::string vo_filter, std::string data_filter)
{
- return saga::adaptors::task("discoverer_cpi_impl::sync_list_services",
- shared_from_this(), &discoverer_cpi_impl::sync_list_services,
+ return saga::adaptors::task("discoverer_cpi_impl::sync_list_services3",
+ shared_from_this(), &discoverer_cpi_impl::sync_list_services3,
svc_filter, vo_filter, data_filter);
}
+
+saga::task discoverer_cpi_impl::async_list_services2 (
+ std::string svc_filter, std::string data_filter)
+{
+ return discoverer_cpi_impl::async_list_services3(svc_filter, "", data_filter);
+
+}
#endif
///////////////////////////////////////////////////////////////////////////////
File [modified]: default_discoverer.hpp
Delta lines: +8 -2
===================================================================
--- trunk/adaptors/default/sd/default_discoverer.hpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/adaptors/default/sd/default_discoverer.hpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -47,14 +47,20 @@
~discoverer_cpi_impl (void);
/*! implementation of SAGA::rpc functions */
- void sync_list_services (std::vector<saga::sd::service_description>&,
+ void sync_list_services3 (std::vector<saga::sd::service_description>&,
std::string svc_filter, std::string vo_filter,
std::string data_filter);
+ void sync_list_services2 (std::vector<saga::sd::service_description>&,
+ std::string svc_filter, std::string data_filter);
+
#if ! defined(SAGA_DEFAULT_FILE_ADAPTOR_NO_ASYNCS)
- saga::task async_list_services (
+ saga::task async_list_services3 (
std::string svc_filter, std::string vo_filter,
std::string data_filter);
+
+ saga::task async_list_services2 (
+ std::string svc_filter, std::string data_filter);
#endif
};
Directory: /trunk/saga/impl/packages/sd/
========================================
File [modified]: discoverer.cpp
Delta lines: +3 -1
===================================================================
--- trunk/saga/impl/packages/sd/discoverer.cpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/impl/packages/sd/discoverer.cpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -55,8 +55,10 @@
}
// methods for discoverer
+ SAGA_CALL_IMPL_IMPL_2 (discoverer, discoverer_cpi,
+ list_services2, std::string, std::string)
SAGA_CALL_IMPL_IMPL_3 (discoverer, discoverer_cpi,
- list_services, std::string, std::string, std::string)
+ list_services3, std::string, std::string, std::string)
} // namespace impl
} // namespace saga
////////////////////////////////////////////////////////////////////////////////////////////////////
File [modified]: discoverer.hpp
Delta lines: +3 -1
===================================================================
--- trunk/saga/impl/packages/sd/discoverer.hpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/impl/packages/sd/discoverer.hpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -31,7 +31,9 @@
void create_impl_sync(saga::sd::discoverer& retval);
static saga::task create_impl_async(saga::session const& s);
- SAGA_CALL_IMPL_DECL_3 (list_services,
+ SAGA_CALL_IMPL_DECL_2 (list_services2,
+ std::string, std::string)
+ SAGA_CALL_IMPL_DECL_3 (list_services3,
std::string, std::string, std::string)
};
} // namespace impl
File [modified]: discoverer_cpi.hpp
Delta lines: +6 -2
===================================================================
--- trunk/saga/impl/packages/sd/discoverer_cpi.hpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/impl/packages/sd/discoverer_cpi.hpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -42,7 +42,10 @@
cpi::type get_type() const { return cpi::ServiceDiscoverer; }
- SAGA_CALL_CPI_DECL_VIRT_3 (discoverer_cpi, std::vector<saga::sd::service_description>, list_services,
+ SAGA_CALL_CPI_DECL_VIRT_2 (discoverer_cpi, std::vector<saga::sd::service_description>, list_services2,
+ std::string, std::string)
+
+ SAGA_CALL_CPI_DECL_VIRT_3 (discoverer_cpi, std::vector<saga::sd::service_description>, list_services3,
std::string, std::string, std::string)
}; // class discoverer_cpi
}}} // namespace saga::impl::v1_0
@@ -67,7 +70,8 @@
typedef saga::impl::v1_0::discoverer_cpi base_cpi;
- SAGA_REGISTER_MEMBER(retval, info, base_cpi, Derived, list_services, prefs)
+ SAGA_REGISTER_MEMBER(retval, info, base_cpi, Derived, list_services2, prefs)
+ SAGA_REGISTER_MEMBER(retval, info, base_cpi, Derived, list_services3, prefs)
infos.push_back(info);
return retval; // is true if at least one function got registered
File [modified]: info_provider.hpp
Delta lines: +6 -1
===================================================================
--- trunk/saga/impl/packages/sd/info_provider.hpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/impl/packages/sd/info_provider.hpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -17,11 +17,16 @@
virtual ~info_provider() { };
protected:
- virtual void list_services(std::string svc_filter, std::string vo_filter, std::string data_filter,
+ virtual void list_services3(std::string svc_filter, std::string vo_filter, std::string data_filter,
std::vector<saga::sd::service_description> &svc_desc)
{
}
+ virtual void list_services2(std::string svc_filter, std::string data_filter,
+ std::vector<saga::sd::service_description> &svc_desc)
+ {
+ }
+
virtual void get_service_data(saga::sd::service_description *svc_desc)
{
}
File [modified]: service_description.cpp
Delta lines: +8 -2
===================================================================
--- trunk/saga/impl/packages/sd/service_description.cpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/impl/packages/sd/service_description.cpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -21,10 +21,16 @@
_provider->get_service_data(sd);
}
- void service_description::list_services(std::string svc_filter, std::string vo_filter,
+ void service_description::list_services2(std::string svc_filter, std::string data_filter,
+ std::vector<saga::sd::service_description> &sl)
+ {
+ _provider->list_services2(svc_filter, data_filter, sl);
+ }
+
+ void service_description::list_services3(std::string svc_filter, std::string vo_filter,
std::string data_filter, std::vector<saga::sd::service_description> &sl)
{
- _provider->list_services(svc_filter, vo_filter, data_filter, sl);
+ _provider->list_services3(svc_filter, vo_filter, data_filter, sl);
}
service_description::service_description ()
File [modified]: service_description.hpp
Delta lines: +3 -1
===================================================================
--- trunk/saga/impl/packages/sd/service_description.hpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/impl/packages/sd/service_description.hpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -32,7 +32,9 @@
bool provider_set;
void set_provider(const boost::shared_ptr<glite_sd_adaptor::info_provider>);
void get_service_data(saga::sd::service_description *sd);
- void list_services(std::string svc_filter, std::string vo_filter,
+ void list_services2(std::string svc_filter, std::string data_filter,
+ std::vector<saga::sd::service_description> &slist);
+ void list_services3(std::string svc_filter, std::string vo_filter,
std::string data_filter, std::vector<saga::sd::service_description> &slist);
friend class saga::sd::service_description;
public:
Directory: /trunk/saga/saga/packages/sd/
========================================
File [modified]: discoverer.cpp
Delta lines: +2 -16
===================================================================
--- trunk/saga/saga/packages/sd/discoverer.cpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/saga/packages/sd/discoverer.cpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -13,11 +13,6 @@
namespace sd {
discoverer::discoverer (session const &s)
throw(saga::not_implemented,
- saga::incorrect_url,
- saga::does_not_exist,
- saga::authorization_failed,
- saga::authentication_failed,
- saga::timeout,
saga::no_success)
: saga::object(new saga::impl::discoverer (s))
{
@@ -26,11 +21,6 @@
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)
: saga::object(impl)
{
@@ -38,11 +28,6 @@
discoverer::discoverer(void)
throw(saga::not_implemented,
- saga::incorrect_url,
- saga::does_not_exist,
- saga::authorization_failed,
- saga::authentication_failed,
- saga::timeout,
saga::no_success)
{
}
@@ -69,7 +54,8 @@
SAGA_CALL_CREATE_IMP_1(discoverer, impl::discoverer, session const&)
// methods for service discoverer
- SAGA_CALL_IMP_3 (discoverer, list_services, std::string, std::string, std::string)
+ SAGA_CALL_IMP_2_EX (discoverer, list_services, list_services2, std::string, std::string)
+ SAGA_CALL_IMP_3_EX (discoverer, list_services, list_services3, std::string, std::string, std::string)
} // namespace sd
} // namespace saga
File [modified]: discoverer.hpp
Delta lines: +293 -33
===================================================================
--- trunk/saga/saga/packages/sd/discoverer.hpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/saga/packages/sd/discoverer.hpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -20,6 +20,160 @@
//////////////////////////////////////////////////////////////////
// service discoverer
+/**
+ * <p>
+ * Provides the entry point for service discovery. Apart from the constructor
+ * and destructor it has one method: <code>list_services</code> which returns
+ * the list of descriptions of services matching the specified filter strings.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * There are three filter strings: <code>svc_filter</code>,
+ * <code>authz_filter</code> and <code>data_filter</code> 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 <code>WHERE</code> 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.
+ * </p>
+ * <p>
+ * 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: <code>IN</code>, <code>LIKE</code>,
+ * <code>AND</code>, <code>OR</code>, <code>NOT</code>, <code>=</code>,
+ * <code>>=</code>, <code>></code>, <code><=</code>,
+ * <code><</code>, <code>><</code> 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 <code>ALL</code> or <code>ANY</code> 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.
+ * </p>
+ * <dl>
+ * <dt>The <code>LIKE</code> operator matches string patterns:</dt>
+ * <dd><code>'%xyz'</code> matches all entries with trailing xyz</dd>
+ * <dd><code>'xyz%'</code> matches all entries with leading xyz </dd>
+ * <dd><code>'%xyz%'</code> matches all entries with xyz being a substring</dd>
+ * </dl>
+ * <p>
+ * The <code>ESCAPE</code> keyword can be used with <code>LIKE</code> in the
+ * normal way.
+ * </p>
+ * <p>
+ * Column names are not case sensitive but values are.
+ * </p>
+ * <p>
+ * No use-case has been identified for the operators <code>&g./saga/saga/call.hppt=</code>,
+ * <code>></code>, <code><=</code>, <code>></code> 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.
+ * </p>
+ * <h2>Service Filter</h2>
+ * <p>
+ * Column names in the <code>serviceFilter</code> are:
+ * </p>
+ * <dl>
+ * <dt><code>type</code></dt>
+ * <dd>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.</dd>
+ * <dt><code>name</code></dt>
+ * <dd>name of service (not necessarily unique)</dd>
+ * <dt><code>uid</code></dt>
+ * <dd>unique identifier of service</dd>
+ * <dt><code>site</code></dt>
+ * <dd>name of site the service is running at</dd>
+ * <dt><code>url</code></dt>
+ * <dd>the endpoint to contact the service - will normally be used with the
+ * LIKE operator</dd>
+ * <dt><code>implementor</code></dt>
+ * <dd>name of the organisation providing the implementation of the service</dd>
+ * <dt><code>relatedService</code></dt>
+ * <dd>the uid of a service related to the one being looked for</dd>
+ * </dl>
+ * <dl>
+ * <dt>Some examples are:</dt>
+ * <dd><code>type = 'org.ogf.saga.service.job'</code></dd>
+ * <dd><code>site IN ('INFN-CNAF', 'RAL-LCG2')</code></dd>
+ * <dd><code>type = 'org.glite.ResourceBroker' AND Site LIKE '%.uk' AND implementor = 'EGEE'</code></dd>
+ * <dd><code>ANY relatedService = 'someServiceUID'</code></dd>
+ * </dl>
+ * <p>
+ * Note the use of the <code>ANY</code> keyword in the last example as
+ * <code>relatedService</code> is multi-valued.
+ * </p>
+ * <h2>Data Filter</h2>
+ * <p>
+ * Column names in the the <code>data_filter</code> string are matched against
+ * the service data key/value pairs. No keys are predefined by this
+ * specification.
+ * </p>
+ * <p>
+ * If values are specified as numeric values and not in single quotes, the
+ * service data will be converted from string to numeric for comparison.
+ * </p>
+ * <p>
+ * Data attributes may be multi-valued. If a <code>data_filter</code> 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.
+ * </p>
+ * <dl>
+ * <dt>Some examples are:</dt>
+ * <dd><code>source = 'RAL-LCG2' OR destination = 'RAL-LCG2'</code></dd>
+ * <dd><code>RunningJobs >= 1 AND RunningJobs <= 5</code></dd>
+ * </dl>
+ * <h2>Authz Filter</h2>
+ * <p>
+ * The set of column names in the <code>authz_filter</code> 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.
+ * </p>
+ * <dl>
+ * <dt>vo</dt>
+ * <dd>virtual organization - will often be used with the IN operator</dd>
+ * <dt>dn</dt>
+ * <dd>an X.509 ``distinguished name''</dd>
+ * <dt>group</dt>
+ * <dd>a grouping of people within a Virtual Organization</dd>
+ * <dt>role</dt>
+ * <dd>values might include ``Administrator'' or ``ProductionManager''</dd>
+ * </dl>
+ * <p>
+ * It is expected that many of the attributes used in then
+ * <code>authzFilter</code> will be multi-valued.
+ * </p>
+ * <dl>
+ * <dt>Some examples, where <code>VO</code> is assmed to be multi-valued are:</dt>
+ * <dd><code>ANY VO IN ('cms', 'atlas')</code></dd>
+ * <dd><code>VO = ('dteam')</code></dd>
+ * </dl>
+ * <p>
+ * Note the use of the set constructor in both examples. Being a set,
+ * ('aaa','bbbb') is of course the same as ('bbb', 'aaa').
+ * </p>
+ * <p>
+ * The <code>listServices</code> method is overloaded: the last parameter the
+ * <code>authzFilter</code> 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 <code>authzFilter</code> parameter with an
+ * empty string which means that there is <b>no</b> authz filtering.
+ * </p>
+ */
class SAGA_SD_PACKAGE_EXPORT discoverer
: public saga::object
{
@@ -30,6 +184,7 @@
// factory
SAGA_CALL_CREATE_PRIV_1(session const&);
+ SAGA_CALL_PRIV_2 (list_services, std::string, std::string);
SAGA_CALL_PRIV_3 (list_services, std::string, std::string, std::string);
protected:
@@ -37,43 +192,62 @@
friend class saga::impl::discoverer;
explicit 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);
public:
+ /**
+ * Default constructor. Constructs a discoverer object using a default
+ * session.
+ *
+ * @throws not_implemented
+ * if the discoverer class is not implemented
+ * by the SAGA implementation at all.
+ * @throws no_success
+ * if no result can be returned because of
+ * information system or other internal problems.
+ */
discoverer() throw(saga::not_implemented,
- saga::incorrect_url,
- saga::does_not_exist,
- saga::authorization_failed,
- saga::authentication_failed,
- saga::timeout,
saga::no_success);
+ /**
+ * Constructor. Constructs a discoverer object using the given
+ * session.
+ *
+ * @param s
+ * Session to use.
+ *
+ * @throws not_implemented
+ * if the discoverer class is not implemented
+ * by the SAGA implementation at all.
+ * @throws no_success
+ * if no result can be returned because of
+ * information system or other internal problems.
+ */
explicit discoverer(session const& s) throw(saga::not_implemented,
- saga::incorrect_url,
- saga::does_not_exist,
- saga::authorization_failed,
- saga::authentication_failed,
- saga::timeout,
saga::no_success);
// explicit discoverer(saga::object const& o); // is this ctor necessary?
+ /**
+ * Destructor
+ */
~discoverer (void) throw();
- /*! \brief Factory function resembling discoverer(session)
- * constructor
- */
+ /**
+ * discoverer factory. Constructs a discoverer object using
+ * the given session.
+ *
+ * @param s
+ * Session to use.
+ *
+ * @throws not_implemented
+ * if the discoverer class is not implemented
+ * by the SAGA implementation at all.
+ * @throws no_success
+ * if no result can be returned because of
+ * information system or other internal problems.
+ */
static discoverer create(session const& s)
throw(saga::not_implemented,
- saga::incorrect_url,
- saga::does_not_exist,
- saga::authorization_failed,
- saga::authentication_failed,
- saga::timeout,
saga::no_success)
{
return discoverer(s);
@@ -85,15 +259,47 @@
// public methods for the service discoverer
- /*! \brief List services synchronously
- * \param service_filter SQL expression using service attributes
- * \param vo_filter SQL expression using VO names
- * \param data_filter SQL expression using service data key/value pairs
- *
- */
+ /**
+ * 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.
+ *
+ * @param service_filter
+ * a string containing the filter for filtering on the basic
+ * service and site attributes and on related services
+ * @param authz_filter
+ * a string containing the filter for filtering on
+ * authorization information associated with the service
+ * @param data_filter
+ * a string containing the filter for filtering on key/value
+ * pairs associated with the service
+ * @return list of service descriptions, in a random order, matching the
+ * filter criteria
+ *
+ * @throws bad_parameter
+ * if any filter has an invalid syntax or if any filter uses
+ * invalid keys. However the <code>dataFilter</code> never
+ * signals invalid keys as there is no schema with
+ * permissible key names.
+ * @throws 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.
+ * @throws authenticationfailed
+ * if none of the available session contexts could
+ * successfully be used for authentication
+ * @throws timeout
+ * if a remote operation did not complete successfully
+ * because the network communication or the remote service
+ * timed out
+ * @throws no_success
+ * if no result can be returned because of
+ * information system or other internal problems
+ */
std::vector<saga::sd::service_description>
- list_services(std::string svc_filter,
- std::string vo_filter,
+ list_services(std::string service_filter,
+ std::string authz_filter,
std::string data_filter)
throw(saga::bad_parameter,
saga::authorization_failed,
@@ -101,12 +307,66 @@
saga::timeout,
saga::no_success)
{
- saga::task t = list_servicespriv(svc_filter, vo_filter, data_filter,
- saga::task_base::Sync());
+ saga::task t = list_servicespriv(service_filter,
+ authz_filter,
+ data_filter,
+ saga::task_base::Sync());
return t.get_result<std::vector<saga::sd::service_description> >();
}
SAGA_CALL_PUB_3_DEF_0 (list_services, std::string, std::string, std::string);
+ /**
+ * Returns the set of services that pass the set of specified filters, an
+ * implicit <code>authz_filter</code> is constructed from the contexts of
+ * the session. Note that this is different from an empty
+ * <code>authz_filter</code>, as that would apply no authorization filter
+ * at all.
+ *
+ * @param service_filter
+ * a string containing the filter for filtering on the basic
+ * service and site attributes and on related services
+ * @param data_filter
+ * a string containing the filter for filtering on key/value
+ * pairs associated with the service
+ * @return list of service descriptions, in a random order, matching the
+ * filter criteria
+ * @throws bad_parameter
+ * if any filter has an invalid syntax or if any filter uses
+ * invalid keys. However the <code>dataFilter</code> never
+ * signals invalid keys as there is no schema with
+ * permissible key names.
+ * @throws 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.
+ * @throws authentication_failed
+ * if none of the available session contexts could
+ * successfully be used for authentication
+ * @throws timeout
+ * if a remote operation did not complete successfully
+ * because the network communication or the remote service
+ * timed out
+ * @throws no_success
+ * if no result can be returned because of information
+ * system or other internal problems
+ */
+ std::vector<saga::sd::service_description>
+ 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)
+ {
+ saga::task t = list_servicespriv(service_filter,
+ data_filter,
+ saga::task_base::Sync());
+ return t.get_result<std::vector<saga::sd::service_description> >();
+ }
+ SAGA_CALL_PUB_2_DEF_0 (list_services, std::string, std::string);
}; // discoverer
} // namespace sd
} // namespace saga
File [modified]: service_data.hpp
Delta lines: +10 -0
===================================================================
--- trunk/saga/saga/packages/sd/service_data.hpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/saga/packages/sd/service_data.hpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -23,6 +23,16 @@
namespace sd {
+/**
+ * Read access to the key/value pairs of a service_description instance.
+ * This class implements the
+ * saga::attributes interface and
+ * offers getter methods for the user to read key/value pairs defined by the
+ * service publisher. Service publishers are completely free to define their own
+ * key names. Access to the keys and values is through the
+ * <code>saga::attributes</code> interface. The class provides no other
+ * methods.
+ */
class SAGA_SD_PACKAGE_EXPORT service_data
: public saga::object,
public saga::detail::attribute<service_data>
File [modified]: service_description.cpp
Delta lines: +1 -1
===================================================================
--- trunk/saga/saga/packages/sd/service_description.cpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/saga/packages/sd/service_description.cpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -150,7 +150,7 @@
#endif
boost::shared_ptr<saga::impl::service_description> sptr =
boost::dynamic_pointer_cast<saga::impl::service_description>(this->get_impl());
- sptr->list_services(svc_filter, vo_filter, data_filter, rsvc_list);
+ sptr->list_services3(svc_filter, vo_filter, data_filter, rsvc_list);
}
}
return rsvc_list;
File [modified]: service_description.hpp
Delta lines: +73 -0
===================================================================
--- trunk/saga/saga/packages/sd/service_description.hpp 2009-01-19 13:01:16 UTC (rev 3333)
+++ trunk/saga/saga/packages/sd/service_description.hpp 2009-01-19 15:01:34 UTC (rev 3334)
@@ -46,6 +46,36 @@
/////////////////////////////////////////////////////////
// service description
+/**
+ * <p>
+ * Read access to the top level data of the service and a means to navigate to
+ * related services. This class implements the
+ * attributes interface and
+ * offers getter methods to obtain details of that service. The attributes are
+ * based on those found in GLUE. They are:
+ * </p>
+ * <dl>
+ * <dt><code>Url</code></dt>
+ * <dd>url to contact the service. The get_url method obtains
+ * the same information.
+ * <dt><code>Type</code></dt>
+ * <dd>type of service. This field is not an empty string.</dd>
+ * <dt><code>Uid</code></dt>
+ * <dd>unique identifier of service. This field is not an empty string.</dd>
+ * <dt><code>Site</code></dt>
+ * <dd>name of site. This field is not an empty string.</dd>
+ * <dt><code>Name</code></dt>
+ * <dd>name of service - not necessarily unique. This field is not an empty
+ * string.</dd>
+ * <dt><code>implementor</code></dt>
+ * <dd>name of the organisation providing the implementation of the service.
+ * This field is not an empty string.</dd>
+ * <dt><code>Related_Services</code></dt>
+ * <dd>uids of related services. This returns the uids of the related services.
+ * This is unlike the method get_related_services
+ * which returns a vector of service_description objects.</dd>
+ * </dl>
+ */
class SAGA_SD_PACKAGE_EXPORT service_description
: public saga::object,
public saga::detail::attribute<service_description>
@@ -77,23 +107,66 @@
using saga::detail::attribute<service_description>::get_attribute;
using saga::detail::attribute<service_description>::get_vector_attribute;
+ /**
+ * Default constructor
+ */
service_description (void);
explicit service_description (saga::object const& o);
+ /**
+ * Destructor
+ */
~service_description (void) throw();
// default operator=() and copy ctor are ok
service_description &operator= (saga::object const& o) throw();
// special getters
+ /**
+ * Returns the <code>URL</code> to contact the service. The
+ * <code>URL</code> may also be obtained using the
+ * <code>saga::attributes</code> interface.
+ *
+ * @return a string containing the URL to contact this service
+ */
std::string get_url() throw();
+ /**
+ * Returns a vector of related services. Alternatively, the
+ * <code>saga::attributes</code> interface may be used to get the uids of
+ * the related services.
+ *
+ * @return a set of related services. This may be an empty set.
+ * @throws 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.
+ * @throws authentication_failed
+ * if none of the available session contexts could
+ * successfully be used for authentication
+ * @throws timeout
+ * if a remote operation did not complete successfully
+ * because the network communication or the remote service
+ * timed out
+ * @throws no_success
+ * if no result can be returned because of information
+ * system or other internal problems
+ */
std::vector<saga::sd::service_description> get_related_services()
throw(saga::authorization_failed,
saga::authentication_failed,
saga::timeout,
saga::no_success);
+ /**
+ * Returns a <code>service_data</code> object with the service data
+ * key/value pairs.
+ *
+ * @return the service data for this service.
+ * This may be empty, i.e.has no attributes at all.
+ */
saga::sd::service_data &get_data() throw();
}; // service_description
} // namespace sd
More information about the saga-devel
mailing list