diff options
Diffstat (limited to 'qpid/cpp/include/qmf/Agent.h')
| -rw-r--r-- | qpid/cpp/include/qmf/Agent.h | 135 |
1 files changed, 84 insertions, 51 deletions
diff --git a/qpid/cpp/include/qmf/Agent.h b/qpid/cpp/include/qmf/Agent.h index e61cd737d0..d982a05cf5 100644 --- a/qpid/cpp/include/qmf/Agent.h +++ b/qpid/cpp/include/qmf/Agent.h @@ -21,25 +21,29 @@ */ #include "qmf/QmfImportExport.h" +#include "qmf/Notifiable.h" +#include "qpid/sys/Time.h" +#include "qpid/messaging/Connection.h" +#include "qpid/messaging/Variant.h" +#include <string> namespace qmf { class AgentImpl; - class Connection; class ObjectId; class AgentObject; - class Value; class Event; - class SchemaObjectClass; + class SchemaClass; + class Query; /** - * AgentListener is used by agents that select the internalStore=false option (see Agent + * AgentHandler is used by agents that select the internalStore=false option (see Agent * constructor) or by agents that wish to provide access control for queries and methods. * * \ingroup qmfapi */ - class AgentListener { - QMF_EXTERN virtual ~AgentListener(); + class AgentHandler { + QMF_EXTERN virtual ~AgentHandler(); /** * allowQuery is called before a query operation is executed. If true is returned @@ -49,7 +53,7 @@ namespace qmf { * @param q The query being requested. * @param userId The authenticated identity of the user requesting the query. */ - virtual bool allowQuery(const Query& q, const char* userId); + virtual bool allowQuery(const Query& q, const std::string& userId); /** * allowMethod is called before a method call is executed. If true is returned @@ -62,8 +66,11 @@ namespace qmf { * @param cls The Schema describing the object being called. * @param userId The authenticated identity of the requesting user. */ - virtual bool allowMethod(const char* name, const Value& args, const ObjectId& oid, - const SchemaObjectClass& cls, const char* userId); + virtual bool allowMethod(const std::string& name, + const qpid::messaging::Variant::Map& args, + const ObjectId& oid, + const SchemaClass& cls, + const std::string& userId); /** * query is called when the agent receives a query request. The handler must invoke @@ -78,11 +85,11 @@ namespace qmf { * @param q The query requested by the console. * @param userId the authenticated identity of the user requesting the query. */ - virtual void query(uint32_t context, const Query& q, const char* userId); + virtual void query(uint32_t context, const Query& q, const std::string& userId); /** * syncStart is called when a console requests a standing query. This function must - * behave exactly like AgentListener::query (i.e. send zero or more responses followed + * behave exactly like AgentHandler::query (i.e. send zero or more responses followed * by a queryComplete) except it then remembers the context and the query and makes * subsequent queryResponse calls whenever appropriate according the the query. * @@ -96,7 +103,7 @@ namespace qmf { * @param q The query requested by the console. * @param userId the authenticated identity of the user requesting the query. */ - virtual void syncStart(uint32_t context, const Query& q, const char* userId); + virtual void syncStart(uint32_t context, const Query& q, const std::string& userId); /** * syncTouch is called when the console that requested a standing query refreshes its @@ -109,7 +116,7 @@ namespace qmf { * @param context The context supplied in a previous call to syncStart. * @param userId The authenticated identity of the requesting user. */ - virtual void syncTouch(uint32_t context, const char* userId); + virtual void syncTouch(uint32_t context, const std::string& userId); /** * syncStop is called when the console that requested a standing query no longer wishes to @@ -121,7 +128,7 @@ namespace qmf { * @param context The context supplied in a previous call to syncStart. * @param userId The authenticated identity of the requesting user. */ - virtual void syncStop(uint32_t context, const char* userId); + virtual void syncStop(uint32_t context, const std::string& userId); /** * methodCall is called when a console invokes a method on a QMF object. The application @@ -138,8 +145,8 @@ namespace qmf { * @param cls The Schema describing the object being called. * @param userId The authenticated identity of the requesting user. */ - virtual void methodCall(uint32_t context, const char* name, Value& args, - const ObjectId& oid, const SchemaObjectClass& cls, const char* userId); + virtual void methodCall(uint32_t context, const std::string& name, qpid::messaging::Variant::Map& args, + const ObjectId& oid, const SchemaClass& cls, const std::string& userId); }; /** @@ -153,7 +160,16 @@ namespace qmf { /** * Create an instance of the Agent class. * - * @param label An optional string label that can be used to identify the agent. + * @param vendor A string identifying the vendor of the agent application. + * This should follow the reverse-domain-name form (i.e. org.apache). + * + * @param product A string identifying the product provided by the vendor. + * + * @param instance A string that uniquely identifies this instance of the agent. + * If zero, the agent will generate a guid for the instance string. + * + * @param domain A string that defines the QMF domain that this agent should join. + * If zero, the agent will join the default QMF domain. * * @param internalStore If true, objects shall be tracked internally by the agent. * If false, the user of the agent must track the objects. @@ -162,13 +178,19 @@ namespace qmf { * individual operations. If the user is tracking the objects, the user code * must implement queries and syncs (standing queries). * - * @param listener A pointer to a class that implements the AgentListener interface. + * @param handler A pointer to a class that implements the AgentHandler interface. * This must be supplied if any of the following conditions are true: * - The agent model contains methods * - The user wishes to individually authorize query and sync operations. * - internalStore = false + * + * @param notifiable A pointer to a class that implements the Notifiable interface. + * This argument is optional (may be supplied as 0). If it is not supplied, + * notification callbacks will not be invoked. */ - QMF_EXTERN Agent(char* label="qmfa", bool internalStore=true, AgentListener* listener=0); + QMF_EXTERN Agent(const std::string& vendor, const std::string& product, const std::string& instance="", + const std::string& domain="", bool internalStore=true, + AgentHandler* handler=0, Notifiable* notifiable=0); /** * Destroy an instance of the Agent class. @@ -176,20 +198,30 @@ namespace qmf { QMF_EXTERN ~Agent(); /** + * Set an attribute for the agent. Attributes are visible to consoles and can be used to find + * agents. + * + * @param name Name of the attribute to be set (or overwritten) + * + * @param value Value (of any variant type) of the attribute + */ + QMF_EXTERN void setAttribute(const std::string& name, const qpid::messaging::Variant& value); + + /** * Set the persistent store file. This file, if specified, is used to store state information * about the Agent. For example, if object-ids must be persistent across restarts of the Agent * program, this file path must be supplied. * * @param path Full path to a file that is both writable and readable by the Agent program. */ - QMF_EXTERN void setStoreDir(const char* path); + QMF_EXTERN void setStoreDir(const std::string& path); /** * Provide a connection (to a Qpid broker) over which the agent can communicate. * * @param conn Pointer to a Connection object. */ - QMF_EXTERN void setConnection(Connection* conn); + QMF_EXTERN void setConnection(qpid::messaging::Connection& conn); /** * Register a class schema (object or event) with the agent. The agent must have a registered @@ -198,30 +230,29 @@ namespace qmf { * * @param cls Pointer to the schema structure describing the class. */ - QMF_EXTERN void registerClass(SchemaObjectClass* cls); - QMF_EXTERN void registerClass(SchemaEventClass* cls); + QMF_EXTERN void registerClass(SchemaClass* cls); /** - * Add an object to the agent (for internal storage mode only). - * - * @param obj Reference to the object to be managed by the agent. + * Invoke the handler (if supplied in the constructor) with events stored in the Agent's work + * queue. This function call is a way of supplying the Agent with a thread on which to run the + * application's handler (the Agent will never invoke the handler on one of its internal threads). * - * @param persistent Iff true, the object ID assigned to the object shall indicate persistence - * (i.e. the object ID shall be the same across restarts of the agent program). - * - * @param oid 64-bit value for the oid (if zero, the agent will assign the value). + * @param limit The maximum number of handler callbacks to invoke during this call. Zero means + * there will be no limit on the number of invocations. * - * @param oidLo 32-bit value for the lower 32-bits of the oid. + * @param timeout The time this call will block if there are no handler events to process. * - * @param oidHi 32-bit value for the upper 32-bits of the oid. + * @return The number of handler events processed. If the timeout expired, the return value will + * be zero. */ - QMF_EXTERN const ObjectId* addObject(AgentObject& obj, bool persistent=false, uint64_t oid=0); - QMF_EXTERN const ObjectId* addObject(AgentObject& obj, bool persistent, uint32_t oidLo, uint32_t oidHi); + QMF_EXTERN uint32_t invokeHandler(uint32_t limit=0, qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE); /** - * Allocate an object ID for an object (for external storage mode only). + * Add an object to the agent (for internal storage mode only). + * + * @param obj Reference to the object to be managed by the agent. * - * @param persistent Iff true, the object ID allocated shall indicate persistence + * @param persistent Iff true, the object ID assigned to the object shall indicate persistence * (i.e. the object ID shall be the same across restarts of the agent program). * * @param oid 64-bit value for the oid (if zero, the agent will assign the value). @@ -230,8 +261,8 @@ namespace qmf { * * @param oidHi 32-bit value for the upper 32-bits of the oid. */ - QMF_EXTERN const ObjectId* allocObjectId(bool persistent=false, uint64_t oid=0); - QMF_EXTERN const ObjectId* allocObjectId(bool persistent, uint32_t oidLo, uint32_t oidHi); + QMF_EXTERN const ObjectId* addObject(AgentObject& obj, bool persistent=false, uint64_t oid=0); + QMF_EXTERN const ObjectId* addObject(AgentObject& obj, bool persistent, uint32_t oidLo, uint32_t oidHi); /** * Raise a QMF event. @@ -243,42 +274,44 @@ namespace qmf { /** * Provide a response to a query (for external storage mode only). * - * @param context The context value supplied in the query (via the AgentListener interface). + * @param context The context value supplied in the query (via the AgentHandler interface). * * @param object A reference to the agent that matched the query criteria. - * - * @param prop If true, transmit the property attributes of this object. - * - * @param stat If true, transmit the statistic attributes of this object. */ - QMF_EXTERN void queryResponse(uint32_t context, AgentObject& object, bool prop = true, bool stat = true); + QMF_EXTERN void queryResponse(uint32_t context, AgentObject& object); /** * Indicate that a query (or the initial dump of a sync) is complete (for external storage mode only). * - * @param context The context value supplied in the query/sync (via the AgentListener interface). + * @param context The context value supplied in the query/sync (via the AgentHandler interface). */ QMF_EXTERN void queryComplete(uint32_t context); /** * Provide the response to a method call. * - * @param context The context value supplied in the method request (via the AgentListener interface). + * @param context The context value supplied in the method request (via the AgentHandler interface). * * @param args The argument list from the method call. Must include the output arguments (may include * the input arguments). * - * @param status Numerical return status: zero indicates no error, non-zero indicates error. - * - * @param exception Pointer to an exception value. If status is non-zero, the exception value is + * @param exception Pointer to an exception value. If status is non-null, the exception value is * sent to the caller. It is optional (i.e. leave the pointer as 0), or may be * set to any legal value. A string may be supplied, but an unmanaged object of * any schema may also be passed. */ - QMF_EXTERN void methodResponse(uint32_t context, const Value& args, uint32_t status=0, - const Value* exception=0); + QMF_EXTERN void methodResponse(uint32_t context, + const qpid::messaging::Variant::Map& args, + const qpid::messaging::Variant& exception=qpid::messaging::Variant()); private: + /** + * Private copy constructor and assignment operator ensure that objects of this class cannot + * be copied. + */ + Agent(const Agent&); + const Agent& operator=(const Agent&); + AgentImpl* impl; }; |