From b4814041a0897cc4b5978ef0d3d5c9ef1d8fa2c1 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Michal=20Voc=C5=AF?= Date: Fri, 25 Feb 2005 16:30:04 +0000 Subject: [PATCH] * added more documentation --- org.glite.lb.client-interface/interface/Event.h.T | 4 +- org.glite.lb.client-interface/interface/Job.h | 238 +++++++++++++-------- .../interface/LoggingExceptions.h | 144 +++++++++++-- .../interface/ServerConnection.h | 207 +++++++++++++++--- 4 files changed, 467 insertions(+), 126 deletions(-) diff --git a/org.glite.lb.client-interface/interface/Event.h.T b/org.glite.lb.client-interface/interface/Event.h.T index 7a79aee..fa077a0 100644 --- a/org.glite.lb.client-interface/interface/Event.h.T +++ b/org.glite.lb.client-interface/interface/Event.h.T @@ -25,9 +25,9 @@ EWL_BEGIN_NAMESPACE -/** Class representing one event in the LB database. +/** Class representing one event in the L&B database. * - * This class represents a LB event, which is basically list of + * This class represents a L&B event, which is basically list of * attribute -- value pairs. For each particular event type (returned * by name()) there is a list of allowed attributes (returned by * getAttrs()). The Event class provides methods for reading these diff --git a/org.glite.lb.client-interface/interface/Job.h b/org.glite.lb.client-interface/interface/Job.h index 58a8e91..7344bdf 100644 --- a/org.glite.lb.client-interface/interface/Job.h +++ b/org.glite.lb.client-interface/interface/Job.h @@ -17,100 +17,170 @@ EWL_BEGIN_NAMESPACE -/** L&B job. +/** Class encapsulating the job info stored in the L&B database. * - * Implementation of L&B job-specific calls. - * Connection to the server is maintained transparently. + * This class is the primary interface for getting information about + * jobs stored in the L&B database. It is constructed from known job + * id, which uniquely identifies the job as well as the bookkeeping + * server where the job data is stored. The Job class provides methods + * for obtaining the data from the bookkeeping server and for setting + * various parameters of the connection to the bookkeeping server. + * + * All query methods have their counterpart in C functions taking + * taking edg_wll_Context and edg_wll_JobId as their first parameters + * (in fact, those functions are used to do the actual work). */ - class Job { public: - Job(void); - Job(const glite::wmsutils::jobid::JobId &); - ~Job(); - - /** Assign new JobId to an existing instance. - * Connection to server is preserved if possible. - */ + + /** Default constructor. + * + * Initializes the job as empty, not representing anything. + */ + Job(void); + + /** Constructor from job id. + * + * Initializes the job to obtain information for the given job id. + * \param[in] jobid The job id of the job this object will + * represent. + * \throws Exception Could not copy the job id. + */ + Job(const glite::wmsutils::jobid::JobId &); + + + /** Destructor. + * + * All the actual work is done by member destructors, namely ServerConnection. + */ + ~Job(); - Job & operator= (const glite::wmsutils::jobid::JobId &); + /** Assign new job id to an existing instance. + * + * Redirect this instance to obtain information about + * different job; connection to the server is preserved, if + * possible. + * \param[in] jobid New job id. + * \returns Reference to this object. + * \throws Exception Could not copy the job id. + */ + Job & operator= (const glite::wmsutils::jobid::JobId &); -/** - * Status retrieval bitmasks. Used ORed as Job::status() argument, - * determine which status fields are actually retrieved. - */ - static const int STAT_CLASSADS; /**< various job description fields */ - static const int STAT_CHILDREN; /**< list of subjob JobId's */ - static const int STAT_CHILDSTAT; /**< apply the flags recursively to subjobs */ + /* + * Status retrieval bitmasks. Used ORed as Job::status() argument, + * determine which status fields are actually retrieved. + */ + static const int STAT_CLASSADS; /**< Include the job + * description in the + * query result. */ + static const int STAT_CHILDREN; /**< Include the list of + * subjob id's in the + * query result. */ + static const int STAT_CHILDSTAT; /**< Apply the flags + * recursively to + * subjobs. */ - /** Return job status */ - JobStatus status(int) const; + /** Return job status. + * + * Obtain the job status (as JobStatus) from the bookkeeping + * server. + * \param[in] flags Specify details of the query. + * \returns Status of the job. + * \throws Exception Could not query the server. + * \see STAT_CLASSADS, STAT_CHILDREN, STAT_CHILDSTAT + */ + JobStatus status(int) const; - /** Return all events corresponding to this job */ - void log(std::vector &) const; - const std::vector log(void) const; + /** Return all events corresponding to this job + * + * Obtain all events corresponding to the job that are stored + * in the bookkeeping server database. The maximum number of + * returned events can be set by calling setParam(). + * \param[out] events Vector of events (of type Event). + * \throws Exception Could not query the server. + */ + void log(std::vector &) const; + + /** Return all events corresponding to this job + * + * Obtain all events corresponding to the job that are stored + * in the bookkeeping server database. The maximum number of + * returned events can be set by calling setParam(). + * \returns Vector of events (of type Event). + * \throws Exception Could not query the server. + */ + const std::vector log(void) const; - /** Return last known address of a listener associated to the job. - * \param name IN name of the listener - * \return hostname and port number - */ - const std::pair queryListener(const std::string & name) const; + /** Return last known address of a listener associated to the job. + * + * Obtains the information about last listener that has been + * registered for this job in the bookkeeping server database. + * \param[in] name Name of the listener. + * \returns Hostname and port number of the registered + * listener. + * \throws Exception Could not query the server. + */ + const std::pair queryListener(const std::string & name) const; - /** - * Manipulate LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \param val IN value - */ - void setParam(edg_wll_ContextParam ctx, int val); - /** - * Manipulate LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \param val IN value - */ - void setParam(edg_wll_ContextParam ctx, const std::string val); - /** - * Manipulate LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \param val IN value - */ - void setParam(edg_wll_ContextParam ctx, const struct timeval &val); - - /** - * Get LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \return integer value of the parameter - */ - int getParamInt(edg_wll_ContextParam ctx) const; - /** - * Get LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \return string value of the parameter - */ - std::string getParamString(edg_wll_ContextParam ctx) const; - /** - * Get LB parameters. - * - * The same as for edg_wll_Context in C - * - * \param ctx INOUT context to work with - * \return timeval value of the parameter - */ - struct timeval getParamTime(edg_wll_ContextParam ctx) const; + /** + * Manipulate LB parameters. + * + * This method sets integer typed parameters for the server connection. + * + * \param[in] ctx Symbolic name of the parameter to change. + * \param[in] val New value of the parameter. + */ + void setParam(edg_wll_ContextParam ctx, int val); + + /** + * Manipulate LB parameters. + * + * This method sets string typed parameters for the server connection. + * + * \param[in] ctx Symbolic name of the parameter to change. + * \param[in] val New value of the parameter. + */ + void setParam(edg_wll_ContextParam ctx, const std::string val); + + /** + * Manipulate LB parameters. + * + * This method sets timeval typed parameters for the server connection. + * + * \param[in] ctx Symbolic name of the parameter to change. + * \param[in] val New value of the parameter. + */ + void setParam(edg_wll_ContextParam ctx, const struct timeval &val); + + /** + * Get LB parameters. + * + * Obtain value of the named integer parameter. + * + * \param[in] ctx Symbolic name of the paramater to obtain. + * \return Value of the parameter. + */ + int getParamInt(edg_wll_ContextParam ctx) const; + + /** + * Get LB parameters. + * + * Obtain value of the named string parameter. + * + * \param[in] ctx Symbolic name of the paramater to obtain. + * \return Value of the parameter. + */ + std::string getParamString(edg_wll_ContextParam ctx) const; + + /** + * Get LB parameters. + * + * Obtain value of the named timeval parameter. + * + * \param[in] ctx Symbolic name of the paramater to obtain. + * \return Value of the parameter. + */ + struct timeval getParamTime(edg_wll_ContextParam ctx) const; private: ServerConnection server; diff --git a/org.glite.lb.client-interface/interface/LoggingExceptions.h b/org.glite.lb.client-interface/interface/LoggingExceptions.h index 15ce0ab..2e10483 100644 --- a/org.glite.lb.client-interface/interface/LoggingExceptions.h +++ b/org.glite.lb.client-interface/interface/LoggingExceptions.h @@ -13,23 +13,56 @@ EWL_BEGIN_NAMESPACE +/** Base class for all exceptions thrown by the L&B C++ classes. + * + * This class serves as a common base for all exceptions thrown by the + * L&B C++ API classes. In case when the exception is constructed from + * another exception (creating chained exception list), the error + * message is created by concatenating the error message of the + * original exception and the new error message. All the other + * functionality (printing error message, logging it, printing stack + * trace) is inherited from the base class glite::wmsutils::exception::Exception. + */ class Exception: public glite::wmsutils::exception::Exception { public: - /* constructor for mandatory fields */ + /** Constructor for mandatory fields. + * + * Updates all the mandatory fields and names the exception. + * \param [in] source Source filename where the exception was + * raised. + * \param [in] line_number Line in the source that caused the + * exception. + * \param [in] method Name of the method that raised the exception. + * \param [in] code Error code giving the reason for exception. + * \param [in] exception Error message describing the exception. + */ Exception(const std::string& source, int line_number, const std::string& method, int code, const std::string& exception) : glite::wmsutils::exception::Exception(source, - line_number, - method, - code, - "glite::lb::Exception") + line_number, + method, + code, + "glite::lb::Exception") { error_message = exception; }; - /* constructor for mandatory fields AND exception chain */ + /** Constructor for mandatory fields and the exception chain. + * + * Updates all the mandatory fields, names the exception and + * adds the original exception's error message to the current + * one. + * \param [in] source Source filename where the exception was + * raised. + * \param [in] line_number Line in the source that caused the + * exception. + * \param [in] method Name of the method that raised the exception. + * \param [in] code Error code giving the reason for exception. + * \param [in] exception Error message describing the exception. + * \param [in] exc Originally raised exception. + */ Exception(const std::string& source, int line_number, const std::string& method, @@ -37,18 +70,35 @@ public: const std::string& exception, const glite::wmsutils::exception::Exception &exc) : glite::wmsutils::exception::Exception(source, - line_number, - method, - code, - "glite::lb::Exception") + line_number, + method, + code, + "glite::lb::Exception") { error_message = exception + ": " + exc.what(); }; }; +/** Exception encapsulating error states originating in the L&B. + * + * This class is simple child of the base Exception class, adding no + * new functionality. Its purpose is to differentiate the error + * conditions originating in the L&B subsystem from other errors (such + * as system ones). + */ class LoggingException: public Exception { public: - /* constructor for mandatory fields */ + /** Constructor for mandatory fields. + * + * Updates all the mandatory fields and names the exception. + * \param [in] source Source filename where the exception was + * raised. + * \param [in] line_number Line in the source that caused the + * exception. + * \param [in] method Name of the method that raised the exception. + * \param [in] code Error code giving the reason for exception. + * \param [in] exception Error message describing the exception. + */ LoggingException(const std::string& source, int line_number, const std::string& method, @@ -57,7 +107,20 @@ public: : Exception(source, line_number, method, code, exception) {}; - /* constructor for mandatory fields AND exception chain */ + /** Constructor for mandatory fields and the exception chain. + * + * Updates all the mandatory fields, names the exception and + * adds the original exception's error message to the current + * one. + * \param [in] source Source filename where the exception was + * raised. + * \param [in] line_number Line in the source that caused the + * exception. + * \param [in] method Name of the method that raised the exception. + * \param [in] code Error code giving the reason for exception. + * \param [in] exception Error message describing the exception. + * \param [in] exc Originally raised exception. + */ LoggingException(const std::string& source, int line_number, const std::string& method, @@ -69,10 +132,26 @@ public: }; +/** Exceptions caused by system errors. + * + * This class represents error conditions caused by failing system + * calls. The error message is augmented with the system error message + * obtained by calling strerror(). + */ class OSException: public Exception { public: - /* constructor for mandatory fields */ + /** Constructor for mandatory fields. + * + * Updates all the mandatory fields and names the exception. + * \param [in] source Source filename where the exception was + * raised. + * \param [in] line_number Line in the source that caused the + * exception. + * \param [in] method Name of the method that raised the exception. + * \param [in] code Error code giving the reason for exception. + * \param [in] exception Error message describing the exception. + */ OSException(const std::string& source, int line_number, const std::string& method, @@ -85,7 +164,20 @@ public: exception + ": " + strerror(code)) {}; - /* constructor for mandatory fields AND exception chain */ + /** Constructor for mandatory fields and the exception chain. + * + * Updates all the mandatory fields, names the exception and + * adds the original exception's error message to the current + * one. + * \param [in] source Source filename where the exception was + * raised. + * \param [in] line_number Line in the source that caused the + * exception. + * \param [in] method Name of the method that raised the exception. + * \param [in] code Error code giving the reason for exception. + * \param [in] exception Error message describing the exception. + * \param [in] exc Originally raised exception. + */ OSException(const std::string& source, int line_number, const std::string& method, @@ -101,14 +193,31 @@ public: }; +/** Mandatory exception fields. + * + * This defines the mandatory parameters for all exception + * constructors (filename, line, method name). + */ #define EXCEPTION_MANDATORY \ __FILE__, \ __LINE__, \ std::string(CLASS_PREFIX) + __FUNCTION__ +/** Stacking exceptions. + * + * This was originally used for creating the exception chain; now the + * same result is achieved by adding the nested exception to the + * constructor parameter list. + */ #define STACK_ADD -/* note: we can use __LINE__ several times in macro, it is expanded into one row */ +/** Utility macro to throw LoggingException. + * + * This macro is used to obtain the L&B error message and throw the + * appropriate exception. + * Note: we can use __LINE__ several times in macro, it is expanded into + * one row. + */ #define throw_exception(context, exception) \ { STACK_ADD; \ { \ @@ -134,6 +243,11 @@ public: } \ } +/** Utility macro to check result of L&B calls. + * + * Checks return value of L&B calls and throws exception if the code + * failed. + */ #define check_result(code, context, desc) \ if((code)) throw_exception((context), desc) diff --git a/org.glite.lb.client-interface/interface/ServerConnection.h b/org.glite.lb.client-interface/interface/ServerConnection.h index 58a5fc9..8cb4fad 100644 --- a/org.glite.lb.client-interface/interface/ServerConnection.h +++ b/org.glite.lb.client-interface/interface/ServerConnection.h @@ -19,68 +19,225 @@ EWL_BEGIN_NAMESPACE -/** Auxiliary class to hold an atomic query condition. */ +/** Auxiliary class to hold atomic query condition. + * + * This class is used to construct queries to the L&B database. Each + * query is composed of multiple atomic conditions in the form of + * . QueryRecord represents such an + * atomic condition. + */ class QueryRecord { public: friend class ServerConnection; friend edg_wll_QueryRec *convertQueryVector(const std::vector &in); /* IMPORTANT: must match lbapi.h */ + /** Symbolic names of queryable attributes. + * + * The queryable attributes correspond to the table columns in + * the bookkeeping server database, they relate both to the + * event records and job records. + * \see Event::Attr + */ enum Attr { UNDEF=0, /**< Not-defined value, used to terminate lists etc. */ - JOBID, /**< Job Id \see _edg_wll_QueryRec */ - OWNER, /**< Job owner \see _edg_wll_QueryRec */ - STATUS, /**< Current job status */ - LOCATION, /**< Where is the job processed */ - DESTINATION, /**< Destination CE */ - DONECODE, /**< Minor done status (OK,fail,cancel) */ - USERTAG, /**< User tag (not implemented yet) */ - TIME, /**< Timestamp \see _edg_wll_QueryRec */ - LEVEL, /**< Logging level (see "dglog.h") * \see _edg_wll_QueryRec */ - HOST, /**< Where the event was generated */ - SOURCE, /**< Source component */ - INSTANCE, /**< Instance of the source component */ - EVENT_TYPE, /**< Event type \see _edg_wll_QueryRec */ - CHKPT_TAG, /**< Checkpoint tag */ + JOBID, /**< Job id. */ + OWNER, /**< Job owner (certificate subject). */ + STATUS, /**< Current job status code. */ + LOCATION, /**< Where is the job being processed. */ + DESTINATION, /**< Destination CE. */ + DONECODE, /**< Minor done status (OK,fail,cancel). */ + USERTAG, /**< User tag. */ + TIME, /**< Timestamp of the event. */ + LEVEL, /**< Logging level. */ + HOST, /**< Hostname where the event was generated. */ + SOURCE, /**< Source component that sent the event. */ + INSTANCE, /**< Instance of the source component. */ + EVENT_TYPE, /**< Event type. */ + CHKPT_TAG, /**< Checkpoint tag. */ RESUBMITTED, /**< Job was resubmitted */ - PARENT, /**< Job was resubmitted */ - EXITCODE, /**< Unix exit code */ + PARENT, /**< Id of the parent job. */ + EXITCODE, /**< Job system exit code. */ }; + /** Symbolic names of predicates. + * + * These are the predicates used for creating atomic query + * conditions. + */ enum Op { - EQUAL=EDG_WLL_QUERY_OP_EQUAL, - LESS=EDG_WLL_QUERY_OP_LESS, - GREATER=EDG_WLL_QUERY_OP_GREATER, - WITHIN=EDG_WLL_QUERY_OP_WITHIN, - UNEQUAL=EDG_WLL_QUERY_OP_UNEQUAL + EQUAL=EDG_WLL_QUERY_OP_EQUAL, /**< Equal. */ + LESS=EDG_WLL_QUERY_OP_LESS, /**< Less than. */ + GREATER=EDG_WLL_QUERY_OP_GREATER, /**< Greater than. */ + WITHIN=EDG_WLL_QUERY_OP_WITHIN, /**< Within the + range. */ + UNEQUAL=EDG_WLL_QUERY_OP_UNEQUAL /**< Not equal. */ }; + + /** Default constructor. + * + * Initializes empty query condition. + */ QueryRecord(); - /* copy and assignment */ + /** Copy constructor + * + * Initializes an exact copy of the object. + * \param[in] src Original object. + */ QueryRecord(const QueryRecord &); + + /** Assignment operator. + * + * Initializes an exact copy of the object. + * \param[in] src Original object. + * \returns Reference to this object. + */ QueryRecord& operator=(const QueryRecord &); - /* constructors for simple attribute queries */ + /** Constructor for condition on string typed value. + * + * Initializes the object to hold condition on string typed + * attribute value. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ QueryRecord(const Attr, const Op, const std::string &); + + /** Constructor for condition on integer typed value. + * + * Initializes the object to hold condition on integer typed + * attribute value. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ QueryRecord(const Attr, const Op, const int); + + /** Constructor for condition on timeval typed value. + * + * Initializes the object to hold condition on timeval typed + * attribute value. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ QueryRecord(const Attr, const Op, const struct timeval &); + + /** Constructor for condition on JobId typed value. + * + * Initializes the object to hold condition on JobId typed + * attribute value. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ QueryRecord(const Attr, const Op, const glite::wmsutils::jobid::JobId&); + /* this one is for attr==TIME and particular state */ + /** Constructor for condition on timeval typed value. + * + * Initializes the object to hold condition on the time the job + * stays in given state. + * \param[in] name Name of the attribute. + * \param[in] state State of thet job. + * \param[in] op Symbolic name of the predicate. + * \param[in] value Actual value. + * \throw Exception Invalid value type for given attribute. + */ QueryRecord(const Attr, const Op, const int, const struct timeval &); /* constructors for WITHIN operator */ + /** Constructor for condition on string typed interval. + * + * Initializes the object to hold condition on string typed + * attribute interval. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value_min Low interval boundary. + * \param[in] value_max High interval boundary. + * \throw Exception Invalid value type for given attribute. + */ QueryRecord(const Attr, const Op, const std::string &, const std::string &); + + /** Constructor for condition on integer typed interval. + * + * Initializes the object to hold condition on integer typed + * attribute interval. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value_min Low interval boundary. + * \param[in] value_max High interval boundary. + * \throw Exception Invalid value type for given attribute. + */ QueryRecord(const Attr, const Op, const int, const int); + + /** Constructor for condition on timeval typed interval. + * + * Initializes the object to hold condition on timeval typed + * attribute interval. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value_min Low interval boundary. + * \param[in] value_max High interval boundary. + * \throw Exception Invalid value type for given attribute. + */ QueryRecord(const Attr, const Op, const struct timeval &, const struct timeval &); + + /** Constructor for condition on timeval typed interval for + * given state. + * + * Initializes the object to hold condition on the time job + * stayed in given state. + * \param[in] name Name of the attribute. + * \param[in] op Symbolic name of the predicate. + * \param[in] value_min Low interval boundary. + * \param[in] value_max High interval boundary. + * \param[in] state State of thet job. + * \throw Exception Invalid value type for given attribute. + */ QueryRecord(const Attr, const Op, const int, const struct timeval &, const struct timeval &); /* convenience for user tags */ + /** Convenience constructor for condition on user tags. + * + * Initializes the object to hold condition on the value of + * user tag. + * \param[in] tag Name of the tag. + * \param[in] op Symbolic namen of the predicate. + * \param[in] value Value of the tag. + */ QueryRecord(const std::string &, const Op, const std::string &); + + /** Convenience constructor for condition on user tags. + * + * Initializes the object to hold condition on the value of + * user tag. + * \param[in] tag Name of the tag. + * \param[in] op Symbolic namen of the predicate. + * \param[in] value_min Minimal value of the tag. + * \param[in] value_max Maximal value of the tag. + * \throws Exception Predicate is not WITHIN. + */ QueryRecord(const std::string &, const Op, const std::string &, const std::string &); + /** Destructor. + * + * The actual work is done by member destructors. + */ ~QueryRecord(); + /** Return the string representation of symbolic attribute + * name. + * \param[in] attr Symbolic attribute name. + * \returns Printable attribute name. + */ static const std::string AttrName(const Attr) ; protected: @@ -103,7 +260,7 @@ private: }; -/** Supported aggregate operations */ +/** Supported aggregate operations. */ enum AggOp { AGG_MIN=1, AGG_MAX, AGG_COUNT }; -- 1.8.2.3