From d109ddea07ee90d75a503c0afd55e9c96213d4d8 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Michal=20Voc=C5=AF?= Date: Mon, 28 Feb 2005 15:02:09 +0000 Subject: [PATCH] added documentation --- org.glite.lb.client-interface/interface/Event.h.T | 2 +- .../interface/JobStatus.h.T | 216 ++++++++--- .../interface/ServerConnection.h | 412 +++++++++++++++++---- 3 files changed, 519 insertions(+), 111 deletions(-) diff --git a/org.glite.lb.client-interface/interface/Event.h.T b/org.glite.lb.client-interface/interface/Event.h.T index 3365576..714a7c0 100644 --- a/org.glite.lb.client-interface/interface/Event.h.T +++ b/org.glite.lb.client-interface/interface/Event.h.T @@ -32,7 +32,7 @@ EWL_BEGIN_NAMESPACE * by name()) there is a list of allowed attributes (returned by * getAttrs()). The Event class provides methods for reading these * attributes, but no means of changing the - * event are provided (except assigning new one). + * event are provided; this class is used as a result of L&B queries. */ class Event { friend class Job; diff --git a/org.glite.lb.client-interface/interface/JobStatus.h.T b/org.glite.lb.client-interface/interface/JobStatus.h.T index 8b63de1..f183a33 100644 --- a/org.glite.lb.client-interface/interface/JobStatus.h.T +++ b/org.glite.lb.client-interface/interface/JobStatus.h.T @@ -19,18 +19,26 @@ EWL_BEGIN_NAMESPACE; -/** - * Description of job status. - * The status is computed from a sequence of logged events +/** Class representing status of job. + * + * This class is used to represent all information about the job status + * as computed and stored in the bookkeeping server's database. Job + * status is, like Event, list of attribute -- value pairs. One of the + * attributes is the job's state as seen by the L&B, ie. something + * like RUNNING or * DONE, other attributes contain + * more information about the job. + * + * The JobStatus class provides methods for reading values of these + * attributes and it is used as a result of server queries. */ - - class JobStatus { friend class Job; friend class CountRef; public: + + /** Symbolic names of job states. */ enum Code { - UNDEF = 0, /**< indicates invalid, i.e. uninitialized instance */ + UNDEF = 0, /**< Indicates invalid, i.e. uninitialized instance. */ @@@{ for my $stat ($status->getTypesOrdered) { @@ -41,9 +49,14 @@ public: }; } @@@} - CODE_MAX + CODE_MAX /**< Limit for range checking. */ }; + /** Symbolic names of attributes. + * + * These constants are used for naming individual attributes + * when invoking their access methods. + */ enum Attr { @@@{ selectType $status '_common_'; @@ -56,7 +69,7 @@ public: gen "\t/** $f->{comment} */\n\t\t$u,\n"; } @@@} - ATTR_MAX + ATTR_MAX /**< Limit for range checking. */ }; @@@{ @@ -80,61 +93,176 @@ public: } } @@@} - enum AttrType { INT_T, - STRING_T, - TIMEVAL_T, - BOOL_T, - JOBID_T, - INTLIST_T, - STRLIST_T, - TAGLIST_T, - STSLIST_T + /** Symbolic names of attribute types. + * + * These constants are used to name the various attribute + * types. + */ + enum AttrType { INT_T, /**< Integer type. */ + STRING_T, /**< String type. */ + TIMEVAL_T, /**< struct timeval type. */ + BOOL_T, /**< Boolean type (true or false). */ + JOBID_T, /**< Job id type. */ + INTLIST_T, /**< List of integer values. */ + STRLIST_T, /**< List of string values. */ + TAGLIST_T, /**< List of user tags. */ + STSLIST_T /**< List of states. */ }; - /** Numeric status code */ + /** Numeric status code. + * + * This code represents the state of the job. + * \see Code. + */ Code status; - /** String representation of the status code */ + /** Get state name. + * + * Returns string representation of the job's state. + */ const std::string & name(void) const; - /** Retrieve integer attribute */ - int getValInt(Attr) const; + /** Access method for attribute values. + * + * Retrieve integer value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + int getValInt(Attr name) const; - /** Retrieve string attribute */ - std::string getValString(Attr) const; + /** Access method for attribute values. + * + * Retrieve string value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + std::string getValString(Attr name) const; - /** Retrieve time attribute */ - struct timeval getValTime(Attr) const; + /** Access method for attribute values. + * + * Retrieve struct timeval value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + struct timeval getValTime(Attr name) const; - /** Retrieve jobid attribute */ - const glite::wmsutils::jobid::JobId getValJobId(Attr) const; + /** Access method for attribute values. + * + * Retrieve JobId value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const glite::wmsutils::jobid::JobId getValJobId(Attr name) const; - /** Retrieve bool attribute */ - bool getValBool(Attr) const; + /** Access method for attribute values. + * + * Retrieve bool value of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + bool getValBool(Attr name) const; - /** Retrieve int list attribute */ - const std::vector getValIntList(Attr) const; + /** Access method for attribute values. + * + * Retrieve integer values of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::vector getValIntList(Attr name) const; - /** Retrieve string list attribute */ - const std::vector getValStringList(Attr) const; + /** Access method for attribute values. + * + * Retrieve string values of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::vector getValStringList(Attr name) const; - /** Retrieve tag list attribute */ - const std::vector > getValTagList(Attr) const; + /** Access method for attribute values. + * + * Retrieve user tags values of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::vector > getValTagList(Attr name) const; - /** Retrieve job status list attribute */ - const std::vector getValJobStatusList(Attr) const; + /** Access method for attribute values. + * + * Retrieve status values of named attribute. + * \param[in] name Symbolic name of attribute. + * \returns Value of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::vector getValJobStatusList(Attr name) const; - /** Attribute name */ - const std::string& getAttrName(Attr) const; + /** Get name of attribute. + * + * Retrieve string representation of symbolic name of attribute. + * \param[in] name Symbolic name of attribute. + * \returns Name of attribute. + * \throws LoggingException Invalid attribute name. + */ + const std::string& getAttrName(Attr name) const; - /** List of attributes and types valid for this instance */ + /** List of attributes and their types valid for this + * instance. + * + * Returns the vector of (attribute, attribute type) pairs + * that this instance of JobStatus contains. + * \returns List of attributes. + */ const std::vector >& getAttrs(void) const; + /** Default constructor. + * + * Initializes an empty instance. + */ JobStatus(void); - JobStatus(const JobStatus &); - JobStatus & operator=(const JobStatus &); - JobStatus(const edg_wll_JobStat &); - JobStatus & operator=(const edg_wll_JobStat&); + + /** Copy constructor. + * + * Creates identical copy of the original object. + * The underlying C struct edg_wll_JobStatus is shared using + * the CountRef mechanism. + * \param[in] orig Original. + */ + JobStatus(const JobStatus &orig); + + /** Assignment operator. + * + * Creates identical copy of the original object. + * The underlying C struct edg_wll_JobStatus is shared using + * the CountRef mechanism. + * \param[in] orig Original. + */ + JobStatus & operator=(const JobStatus &orig); + + /** Constructor from the C type. + * + * Encapsulates the given struct. + * \param[in] src C struct that holds the status. + */ + JobStatus(const edg_wll_JobStat &src); + + /** Assignment from the C type. + * + * Encapsulates the given struct. + * \param[in] src C struct that holds the status. + */ + JobStatus & operator=(const edg_wll_JobStat& src); + + /** Destructor. + * + * Releases the encapsulated C struct. + */ virtual ~JobStatus(); protected: diff --git a/org.glite.lb.client-interface/interface/ServerConnection.h b/org.glite.lb.client-interface/interface/ServerConnection.h index 176c5f3..43f6607 100644 --- a/org.glite.lb.client-interface/interface/ServerConnection.h +++ b/org.glite.lb.client-interface/interface/ServerConnection.h @@ -265,90 +265,257 @@ enum AggOp { AGG_MIN=1, AGG_MAX, AGG_COUNT }; /** - * Connection to the L&B server. - * Maintain connection to the server. - * Implement non job-specific API calls + * Class representing a connection to the L&B server. + * + * This class serves as an interface for queries not related to + * particular job. The address of the bookkeeping server to query can + * be set arbitrarily during the lifetime of this object, connection + * to the server is maintained automatically by the underlying C API + * layer. This class can be thought of also as an encapsulation of + * edg_wll_Context from L&B C API. + * + * ServerConnection's methods correlate to the L&B C API functions + * taking edg_wll_Context as their first argument and not having + * edg_wll_JobId as the second argument. + * \see edg_wll_Context */ - class ServerConnection { public: + /** \defgroup query Methods for querying the bookkeeping + * server. + * + * These methods serve for obtaining data from the bookkeeping + * server. The L&B service queries come in two flavors: + * \li conjunctive query, as in (cond1) or (cond2) + * \li conjunction of disjunctive queries, as in ( (cond1) + * or (cond2) ) and ( (cond3) or (cond4) ) + * Methods for both query flavors are provided. + * + * Query methods actually do communicate with the server and + * they are synchronous; their completion can take some time + * not exceeding the query timeout. + */ + + /** \defgroup property Methods for setting and getting + * connection properties. + * + * These methods are used for setting and obtaining various + * parameters of the communication (timeouts, user + * certificates, limits). Both general methods (taking the + * symbolic name of the parameter as an argument) and + * convenience methods (for some parameters) are provided. + * + * The methods are local, no communication takes place. + */ + friend class Job; + /** Default constructor. + * + * Initializes the context to default values. + * \throws OSException Initialization failed. + */ ServerConnection(void); - /* DEPRECATED: do not use - * connections are now handled automagically inside the implementation + /** DEPRECATED. + * + * \throws Exception Always. */ ServerConnection(const std::string &); - /** Open connection to a given server */ + /** DEPRECATED. + * + * \throws Exception Always. + */ void open(const std::string &); - /** Close the current connection */ + /** DEPRECATED. + * + * \throws Exception Always. + */ void close(void); /* END DEPRECATED */ /* set & get parameter methods */ - /* consumer parameter settings */ - void setQueryServer(const std::string&, int); - void setQueryTimeout(int); + /** Set bookkeeping server address. + * \ingroup property + * + * Directs the instance to query the given bookkeping server. + * \param[in] host Hostname of the server. + * \param[in] port Service port. + * \throws LoggingException Setting parameters failed. + */ + void setQueryServer(const std::string& host, int port); + + /** Set query timeout. + * \ingroup property + * + * Sets the time interval to wait for server response. + * \param[in] time Time in seconds before the query expires. + * \throws LoggingException Setting parameters failed. + */ + void setQueryTimeout(int time); + + /** Set user's proxy certificate. + * \ingroup property + * + * Instructs the instance to authenticate to the server using + * user's X509 proxy certificate. + * \param[in] proxy Name of file containing the user's proxy certificate. + * \throws LoggingException Setting paramater failed. + */ + void setX509Proxy(const std::string& proxy); - void setX509Proxy(const std::string&); - void setX509Cert(const std::string&, const std::string&); + /** Set user's certificate. + * \ingroup property + * + * Instructs the instance to authenticate to the server using + * users's full X509 certificate (which is not a good thing). + * \param[in] cert Name of file containing the user's certificate. + * \param[in] key Name of file containing the user's private + * key. + * \throws LoggingException Setting parameters failed. + */ + void setX509Cert(const std::string& cert, const std::string& key); + /** Get address of the bookkeeping server. + * \ingroup property + * + * Returns address of the bookkeeping server this instance is + * bound to. + * \returns Address (hostname,port). + * \throws LoggingException Getting parameter failed. + */ std::pair getQueryServer() const; + + /** Get query timeout. + * \ingroup property + * + * Returns the time interval this instance waits for server + * response. + * \returns Number of seconds to wait. + * \throws LoggingException Getting parameter failed. + */ int getQueryTimeout() const; + /** Get user's proxy. + * \ingroup property + * + * Returns filename of the user's X509 proxy certificate used + * to authenticate to the server. + * \returns Filename of the proxy certificate. + * \throws LoggingException Getting parameter failed. + */ std::string getX509Proxy() const; + + /** Get user's X509 certificate. + * \ingroup property + * + * Returns filenames of the user's full X509 certificate used + * to authenticate to the server. + * \returns Pair of (certificate, key) filenames. + * \throws LoggingException Getting parameter failed. + */ std::pair getX509Cert() const; /* end of set & get */ + /** Destructor. + * + * Closes the connections and frees the context. + */ virtual ~ServerConnection(); /* consumer API */ /** Retrieve the set of single indexed attributes. - * outer vector elements correspond to indices - * inner vector elements correspond to index columns - * if .first of the pair is USERTAG, .second is its name - * if .first is TIME, .second is state name - * otherwise .second is meaningless (empty string anyway) + * \ingroup query + * + * Returns the set of attributes that are indexed on the + * server. Every query must contain at least one indexed + * attribute for performance reason; exception to this rule + * requires setting appropriate paramater on the server and is + * not advised. + * + * In the vector returned, outer elements correspond to indices, + * inner vector elements correspond to index + * columns. + * If .first of the pair is USERTAG, .second is its name; + * if .first is TIME, .second is state name + * otherwise .second is meaningless (empty string anyway). */ std::vector > > getIndexedAttrs(void); - /** Retrieve hard and soft result set size limit */ - std::pair getLimits(void) const; + /* Retrieve hard and soft result set size limit. + * \ingroup property + * + * Returns both the hard and soft limit on the number of + * results returned by the bookkeeping server. + * \returns Pair (hard, soft) of limits. + * \throws + */ + // std::pair getLimits(void) const; + + /** Set the soft result set size limit. + * \ingroup property + * + * Sets the maximum number of results this instance is willing + * to obtain when querying for jobs. + * \param max Maximum number of results. + * \throws LoggingException Setting parameter failed. + */ + void setQueryJobsLimit(int max); - /** Set the soft result set size limit */ - void setQueryJobsLimit(int); - void setQueryEventsLimit(int); + /** Set the soft result set size limit. + * \ingroup property + * + * Sets the maximum number of results this instance is willing + * to obtain when querying for Events. + * \param max Maximum number of results. + * \throws LoggingException Setting parameter failed. + */ + void setQueryEventsLimit(int max); - /** Retrieve all events satisfying the query records - * \param[in] job_cond, event_cond vectors of conditions to be satisfied - * by jobs as a whole or particular events, conditions are ANDed - * @param events vector of returned events + /** Retrieve all events satisfying the query records. + * \ingroup query + * + * Returns all events belonging to the jobs specified by \arg + * job_cond and in addition satisfying the \arg event_cond. + * \param[in] job_cond Conjunctive query on jobs. + * \param[in] event_cond Conjunctive query on events. + * \param[out] events Vector of Event objects representing L&B + * events. + * \throws LoggingException Query failed. */ void queryEvents(const std::vector& job_cond, const std::vector& event_cond, std::vector& events) const; + /** Convenience form of queryEvents. + * + */ const std::vector queryEvents(const std::vector& job_cond, const std::vector& event_cond) const; + /** Another modification of queryEvents. + * + * The same method, but the results are returned as a list + * instead of vector. + */ const std::list queryEventsList(const std::vector& job_cond, const std::vector& event_cond) const; - /** The same as queryEvents but return only an aggregate. - * \param[in] job_cond, event_cond vectors of conditions to be satisfied - * by jobs as a whole or particular events, conditions are ANDed - * \param[in] op aggregate operator to apply - * \param[in] attr attribute to apply the operation to + /** NOT IMPLEMENTED. + * \param[in] job_cond + * \param[in] event_cond Vectors of conditions to be satisfied + * by jobs as a whole or particular events. + * \param[in] op Aggregate operator to apply. + * \param[in] attr Attribute to apply the operation to. */ std::string queryEventsAggregate(const std::vector& job_cond, const std::vector& event_cond, @@ -356,91 +523,204 @@ public: std::string const attr) const; - /** Retrieve all events satisfying the query records - * \param[in] job_cond, event_cond vectors of vectors of job or event conditions, - * respectively. The inner vectors are logically ANDed, the outer are ORed - * (cond1 AND cond2 AND ...) OR (condN AND ...) - * \param[out] eventList vector of returned events + /** Retrieve all events satisfying the conjunctive-disjunctive + * query. + * + * Returns all events belonging to the jobs specified by + * job_cond and satisfying query_cond. The + * conditions are given in conjunctive-disjunctive form + * ((cond1 OR cond2 OR ...) AND ...) + * \param[in] job_cond Vector of conditions on jobs. + * \param[in] event_cond Vector of coditions on events. + * \param[out] eventList Returned Event's. + * \throws LoggingException Query failed. */ void queryEvents(const std::vector >& job_cond, const std::vector >& event_cond, std::vector& eventList) const; + /** Convenience form of queryEvents. + * + * The same as previous, but the resulting vector is passed as + * a return value. + */ const std::vector queryEvents(const std::vector >& job_cond, const std::vector >& event_cond) const; - /** Retrieve jobs satisfying the query records, including their states - * \param[in] query vector of Query records that are ANDed to form the query - * \param[out] jobList vector of returned job id's + /** Retrieve jobs satisfying the query. + * + * Finds all jobs (represented as JobId's) satisfying given + * query. + * \param[in] query Query in conjunctive form. + * \param[out] jobList List of job id's. + * \throws LoggingException Query failed. */ - void queryJobs(const std::vector& query, std::vector& jobList) const; - + + /** Convenience form of queryJobs. + * + * The same as above, but job id's are passed as a return + * value. + */ const std::vector queryJobs(const std::vector& query) const; - /** Retrieve jobs satisfying the query records, including their states - * \param[in] query vector of Query record vectors that are ORed and ANDed to form the query - * \param[out] jobList vector of returned job id's + /** Retrieve jobs satisfying the query. + * + * Finds all jobs satisfying query given in + * conjunctive-disjunctive form. + * \param[in] query Conjunction of disjunctive queries. + * \param[out] jobList Job id's of found jobs. + * \throws LoggingException Query failed. */ - void queryJobs(const std::vector >& query, std::vector& jobList) const; + /** Convenience form of queryJobs. + * + * Same as above, but result is passed as a retutrn value. + */ const std::vector queryJobs(const std::vector >& query) const; - /** Retrieve jobs satisfying the query records, including status information - * \param[in] query vector of Query records that are ANDed to form the query - * \param[in] flags flags - * \param[out] states vector of returned job states + /** Retrieve status of jobs satisfying the given simple query. + * + * Returns states (represented by JobStatus) of all jobs + * satisfying the query in conjunctive form. + * \param[in] query Condition on jobs. + * \param[in] flags The same as Job::status() flags. + * \param[out] states States of jobs satysfying the condition. + * \throws LoggingException Query failed. */ void queryJobStates(const std::vector& query, int flags, std::vector & states) const; + + /** Convenience form of queryJobStates. + * + * Same as above, but the result is passed as a return value. + */ const std::vector queryJobStates(const std::vector& query, int flags) const; + /** Convenience form of queryJobStates. + * + * Same as above, but results are returned as list instead of + * vector. + */ const std::list queryJobStatesList(const std::vector& query, int flags) const; - /** Retrieve jobs satisfying the query records, including status information - * \param[in] query vector of Query records that are anded to form the query - * \param[in] flags flags - * \param[out] states vector of returned job states + /** Retrieve status of jobs satisfying the given + * conjunctive-disjunctive query. + * + * Returns states (represented by JobStatus) of all jobs + * satisfying the query in conjunctive form. + * \param[in] query Condition on jobs. + * \param[in] flags The same as Job::status() flags. + * \param[out] states States of jobs satysfying the condition. + * \throws LoggingException Query failed. */ void queryJobStates(const std::vector >& query, int flags, std::vector & states) const; + + /** Convenience form of queryJobStates. + * + * Same as above, but the result is passed as a return value. + */ const std::vector queryJobStates(const std::vector >& query, int flags) const; - /** States of all user's jobs. - * Convenience wrapper around queryJobs. + /** Return states of all user's jobs. + * + * Convenience wrapper around queryJobStates, returns status of all + * jobs whose owner is the current user (as named in the X509 + * certificate subject). + * \param[out] stateList States of jobs owned by this user. + * \throws LoggingException Query failed. */ void userJobStates(std::vector& stateList) const; const std::vector userJobStates() const; - /** JobId's of all user's jobs. - * Convenience wrapper around queryJobs. + /** Find all user's jobs. + * + * Convenience wrapper around queryJobs, returns id's of all + * jobs whose owner is the current user (as named in the X509 + * certificate subject). + * \param[out] jobs Id's of jobs owned by this user. + * \throws LoggingException Query failed. + */ + void userJobs(std::vector &jobs) const; + + /** Convenience form of userJobs. + * + * Same as above, but results are passed as a return value. */ - void userJobs(std::vector &) const; const std::vector userJobs() const; - /** Manipulate LB parameters, the same as for edg_wll_Context in C */ - void setParam(edg_wll_ContextParam, int); - void setParam(edg_wll_ContextParam, const std::string); - void setParam(edg_wll_ContextParam, const struct timeval &); + /** Set communication parameters of integer type. + * + * Sets the named parameter to the given integer value. + * \param[in] name Symbolic name of the parameter. + * \param[in] value Value. + * \throws LoggingException Setting parameter failed. + * \see edg_wll_SetParam() + */ + void setParam(edg_wll_ContextParam name, int value); + + /** Set communication parameters of string type. + * + * Sets the named parameter to the given string value. + * \param[in] name Symbolic name of the parameter. + * \param[in] value Value. + * \throws LoggingException Setting parameter failed. + * \see edg_wll_SetParam() + */ + void setParam(edg_wll_ContextParam name, const std::string &value); + + /** Set communication parameters of timeval type. + * + * Sets the named parameter to the given timeval value. + * \param[in] name Symbolic name of the parameter. + * \param[in] value Value. + * \throws LoggingException Setting parameter failed. + * \see edg_wll_SetParam() + */ + void setParam(edg_wll_ContextParam name, const struct timeval &value); + + /** Get communication parameters of integer type. + * + * Gets the named parameter of integer type. + * \param[in] name Symbolic name of the parameter. + * \throws LoggingException Getting parameter failed. + * \see edg_wll_GetParam() + */ + int getParamInt(edg_wll_ContextParam name) const; + + /** Get communication parameters of string type. + * + * Gets the named parameter of string type. + * \param[in] name Symbolic name of the parameter. + * \throws LoggingException Getting parameter failed. + * \see edg_wll_GetParam() + */ + std::string getParamString(edg_wll_ContextParam name) const; - int getParamInt(edg_wll_ContextParam) const; - std::string getParamString(edg_wll_ContextParam) const; - struct timeval getParamTime(edg_wll_ContextParam) const; + /** Get communication parameters of timeval type. + * + * Gets the named parameter of timeval type. + * \param[in] name Symbolic name of the parameter. + * \throws LoggingException Getting parameter failed. + * \see edg_wll_GetParam() + */ + struct timeval getParamTime(edg_wll_ContextParam name) const; protected: -- 1.8.2.3