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
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<Event> &) const;
- const std::vector<Event> 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<Event> &) 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<Event> 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<std::string,uint16_t> 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<std::string,uint16_t> 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;
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,
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,
: 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,
};
+/** 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,
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,
};
+/** 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; \
{ \
} \
}
+/** 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)
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
+ * <attribute> <predicate> <value>. QueryRecord represents such an
+ * atomic condition.
+ */
class QueryRecord {
public:
friend class ServerConnection;
friend edg_wll_QueryRec *convertQueryVector(const std::vector<QueryRecord> &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:
};
-/** Supported aggregate operations */
+/** Supported aggregate operations. */
enum AggOp { AGG_MIN=1, AGG_MAX, AGG_COUNT };
git://scientific.zcu.cz / jra1mw.git / commitdiff