From 03b589ce68fd45bdf2634c211b02bdc5f3cbdba5 Mon Sep 17 00:00:00 2001 From: Ted Ross Date: Thu, 12 Aug 2010 22:28:09 +0000 Subject: QPID-2792 - QMF Clients in C++ following the ABI-stable pattern of the new messaging API git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@985016 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/cpp/include/qmf/AgentSession.h | 93 +++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 qpid/cpp/include/qmf/AgentSession.h (limited to 'qpid/cpp/include/qmf/AgentSession.h') diff --git a/qpid/cpp/include/qmf/AgentSession.h b/qpid/cpp/include/qmf/AgentSession.h new file mode 100644 index 0000000000..5259aee360 --- /dev/null +++ b/qpid/cpp/include/qmf/AgentSession.h @@ -0,0 +1,93 @@ +#ifndef QMF_AGENT_SESSION_H +#define QMF_AGENT_SESSION_H +/* + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * + */ + +#include +#include "qmf/Handle.h" +#include "qpid/messaging/Duration.h" +#include "qpid/messaging/Connection.h" +#include "qpid/types/Variant.h" +#include + +namespace qmf { + +#ifndef SWIG + template class PrivateImplRef; +#endif + + class AgentSessionImpl; + class AgentEvent; + class Schema; + class Data; + class DataAddr; + + class AgentSession : public qmf::Handle { + public: + QMF_EXTERN AgentSession(AgentSessionImpl* impl = 0); + QMF_EXTERN AgentSession(const AgentSession&); + QMF_EXTERN AgentSession& operator=(const AgentSession&); + QMF_EXTERN ~AgentSession(); + + /** + * + * The options string is of the form "{key:value,key:value}". The following keys are supported: + * + * interval:N - Heartbeat interval in seconds [default: 60] + * external:{True,False} - Use external data storage (queries are pass-through) [default: False] + * allow-queries:{True,False} - If True: automatically allow all queries [default] + * If False: generate an AUTH_QUERY event to allow per-query authorization + * allow-methods:{True,False} - If True: automatically allow all methods [default] + * If False: generate an AUTH_METHOD event to allow per-method authorization + */ + QMF_EXTERN AgentSession(qpid::messaging::Connection&, const std::string& options=""); + QMF_EXTERN void setDomain(const std::string&); + QMF_EXTERN void setVendor(const std::string&); + QMF_EXTERN void setProduct(const std::string&); + QMF_EXTERN void setInstance(const std::string&); + QMF_EXTERN void setAttribute(const std::string&, const qpid::types::Variant&); + QMF_EXTERN const std::string& getName() const; + QMF_EXTERN void open(); + QMF_EXTERN void close(); + QMF_EXTERN bool nextEvent(AgentEvent&, qpid::messaging::Duration timeout=qpid::messaging::Duration::FOREVER); + + QMF_EXTERN void registerSchema(Schema&); + QMF_EXTERN DataAddr addData(Data&, const std::string& name="", bool persistent=false); + QMF_EXTERN void delData(const DataAddr&); + + QMF_EXTERN void authAccept(AgentEvent&); + QMF_EXTERN void authReject(AgentEvent&, const std::string& diag=""); + QMF_EXTERN void raiseException(AgentEvent&, const std::string&); + QMF_EXTERN void raiseException(AgentEvent&, const Data&); + QMF_EXTERN void response(AgentEvent&, const Data&); + QMF_EXTERN void complete(AgentEvent&); + QMF_EXTERN void methodSuccess(AgentEvent&); + QMF_EXTERN void raiseEvent(const Data&); + +#ifndef SWIG + private: + friend class qmf::PrivateImplRef; +#endif + }; + +} + +#endif -- cgit v1.2.1 From 58c7fd662a4d37ff3b387575e0c0d3b80e7e7368 Mon Sep 17 00:00:00 2001 From: Ted Ross Date: Fri, 13 Aug 2010 02:25:28 +0000 Subject: QPID-2793 - Added doxygen text git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@985074 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/cpp/include/qmf/AgentSession.h | 77 +++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) (limited to 'qpid/cpp/include/qmf/AgentSession.h') diff --git a/qpid/cpp/include/qmf/AgentSession.h b/qpid/cpp/include/qmf/AgentSession.h index 5259aee360..4ac2b2f3ed 100644 --- a/qpid/cpp/include/qmf/AgentSession.h +++ b/qpid/cpp/include/qmf/AgentSession.h @@ -48,6 +48,11 @@ namespace qmf { QMF_EXTERN ~AgentSession(); /** + * AgentSession + * A session that runs over an AMQP connection for QMF agent operation. + * + * @param connection - An opened qpid::messaging::Connection + * @param options - An optional string containing options * * The options string is of the form "{key:value,key:value}". The following keys are supported: * @@ -59,20 +64,88 @@ namespace qmf { * If False: generate an AUTH_METHOD event to allow per-method authorization */ QMF_EXTERN AgentSession(qpid::messaging::Connection&, const std::string& options=""); + + /** + * setDomain - Change the QMF domain that this agent will operate in. If this is not called, + * the domain will be "default". Agents in a domain can be seen only by consoles in the same domain. + * This must be called prior to opening the agent session. + */ QMF_EXTERN void setDomain(const std::string&); + + /** + * Set identifying attributes of this agent. + * setVendor - Set the vendor string + * setProduct - Set the product name string + * setInstance - Set the unique instance name (if not set, a UUID will be assigned) + * These must be called prior to opening the agent session. + */ QMF_EXTERN void setVendor(const std::string&); QMF_EXTERN void setProduct(const std::string&); QMF_EXTERN void setInstance(const std::string&); + + /** + * setAttribute - Set an arbitrary attribute for this agent. The attributes are not used + * to uniquely identify the agent but can be used as a search criteria when looking for agents. + * This must be called prior to opening the agent session. + */ QMF_EXTERN void setAttribute(const std::string&, const qpid::types::Variant&); + + /** + * Get the identifying name of the agent. + */ QMF_EXTERN const std::string& getName() const; + + /** + * Open the agent session. After opening the session, the domain, identifying strings, and attributes cannot + * be changed. + */ QMF_EXTERN void open(); + + /** + * Close the session. Once closed, the session no longer communicates on the messaging network. + */ QMF_EXTERN void close(); + + /** + * Get the next event from the agent session. Events represent actions that must be acted upon by the + * agent application. This method blocks for up to the timeout if there are no events to be handled. + * This method will typically be the focus of the agent application's main execution loop. + */ QMF_EXTERN bool nextEvent(AgentEvent&, qpid::messaging::Duration timeout=qpid::messaging::Duration::FOREVER); + /** + * Register a schema to be exposed by this agent. + */ QMF_EXTERN void registerSchema(Schema&); + + /** + * Add data to be managed internally by the agent. If the option external:True is selected, this call + * should not be used. + * + * @param data - The data object being managed by the agent. + * @param name - A name unique to this object to be used to address the object. + * If left default, a unique name will be assigned by the agent. + * @param persistent - Set this to true if the data object is to be considered persistent + * across different sessions. If persistent, it is the agent application's + * responsibility to ensure the name is the same each time it is added. + */ QMF_EXTERN DataAddr addData(Data&, const std::string& name="", bool persistent=false); + + /** + * Delete data from internal agent management. + */ QMF_EXTERN void delData(const DataAddr&); + /** + * The following methods are used to respond to events received in nextEvent. + * + * authAccept - Accept an authorization request. + * authReject - Reject/forbid an authorization request. + * raiseException - indicate failure of an operation (i.e. query or method call). + * response - Provide data in response to a query (only for option: external:True) + * complete - Indicate that the response to a query is complete (external:true only) + * methodSuccess - Indicate the successful completion of a method call. + */ QMF_EXTERN void authAccept(AgentEvent&); QMF_EXTERN void authReject(AgentEvent&, const std::string& diag=""); QMF_EXTERN void raiseException(AgentEvent&, const std::string&); @@ -80,6 +153,10 @@ namespace qmf { QMF_EXTERN void response(AgentEvent&, const Data&); QMF_EXTERN void complete(AgentEvent&); QMF_EXTERN void methodSuccess(AgentEvent&); + + /** + * Raise an event to be sent into the QMF network. + */ QMF_EXTERN void raiseEvent(const Data&); #ifndef SWIG -- cgit v1.2.1 From b1cd22ae277d9a987d37e2538aded2f3521bc362 Mon Sep 17 00:00:00 2001 From: Ted Ross Date: Mon, 10 Jan 2011 14:06:16 +0000 Subject: Updates to the C++ implementation of QMFv2: 1) Consolidated string constants for the protocol into a definition file. 2) Added hooks for subscription handling. 3) Added checks to validate properties and arguments against the schema (if there is a schema). git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1057199 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/cpp/include/qmf/AgentSession.h | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'qpid/cpp/include/qmf/AgentSession.h') diff --git a/qpid/cpp/include/qmf/AgentSession.h b/qpid/cpp/include/qmf/AgentSession.h index 4ac2b2f3ed..090017779f 100644 --- a/qpid/cpp/include/qmf/AgentSession.h +++ b/qpid/cpp/include/qmf/AgentSession.h @@ -57,11 +57,16 @@ namespace qmf { * The options string is of the form "{key:value,key:value}". The following keys are supported: * * interval:N - Heartbeat interval in seconds [default: 60] - * external:{True,False} - Use external data storage (queries are pass-through) [default: False] + * external:{True,False} - Use external data storage (queries and subscriptions are pass-through) [default: False] * allow-queries:{True,False} - If True: automatically allow all queries [default] * If False: generate an AUTH_QUERY event to allow per-query authorization * allow-methods:{True,False} - If True: automatically allow all methods [default] * If False: generate an AUTH_METHOD event to allow per-method authorization + * max-subscriptions:N - Maximum number of concurrent subscription queries permitted [default: 64] + * min-sub-interval:N - Minimum publish interval (in milliseconds) permitted for a subscription [default: 3000] + * sub-lifetime:N - Lifetime (in seconds with no keepalive) for a subscription [default: 300] + * public-events:{True,False} - If True: QMF events are sent to the topic exchange [default] + * If False: QMF events are only sent to authorized subscribers */ QMF_EXTERN AgentSession(qpid::messaging::Connection&, const std::string& options=""); @@ -143,7 +148,7 @@ namespace qmf { * authReject - Reject/forbid an authorization request. * raiseException - indicate failure of an operation (i.e. query or method call). * response - Provide data in response to a query (only for option: external:True) - * complete - Indicate that the response to a query is complete (external:true only) + * complete - Indicate that the response to a query is complete (external:True only) * methodSuccess - Indicate the successful completion of a method call. */ QMF_EXTERN void authAccept(AgentEvent&); -- cgit v1.2.1 From 1e77b7bcf6766afbf161137284edbf2a6a255447 Mon Sep 17 00:00:00 2001 From: Ted Ross Date: Wed, 2 Feb 2011 18:16:57 +0000 Subject: QPID-3032 - Modifications to the QMFv2 implementation: 1) Use the topic exchange as the base for direct and reply-to addresses. 2) Add a strict-security option to the Console and Agent APIs that narrows the messaging patterns used such that they can easily be controlled by broker ACL policy. git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1066562 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/cpp/include/qmf/AgentSession.h | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'qpid/cpp/include/qmf/AgentSession.h') diff --git a/qpid/cpp/include/qmf/AgentSession.h b/qpid/cpp/include/qmf/AgentSession.h index 090017779f..23058c56c6 100644 --- a/qpid/cpp/include/qmf/AgentSession.h +++ b/qpid/cpp/include/qmf/AgentSession.h @@ -67,6 +67,10 @@ namespace qmf { * sub-lifetime:N - Lifetime (in seconds with no keepalive) for a subscription [default: 300] * public-events:{True,False} - If True: QMF events are sent to the topic exchange [default] * If False: QMF events are only sent to authorized subscribers + * listen-on-direct:{True,False} - If True: Listen on legacy direct-exchange address for backward compatibility [default] + * If False: Listen only on the routable direct address + * strict-security:{True,False} - If True: Cooperate with the broker to enforce string access control to the network + * - If False: Operate more flexibly with regard to use of messaging facilities [default] */ QMF_EXTERN AgentSession(qpid::messaging::Connection&, const std::string& options=""); -- cgit v1.2.1 From bc413d94f96b787f1a5f20f15100545a138cf62f Mon Sep 17 00:00:00 2001 From: Ted Ross Date: Thu, 3 Feb 2011 02:46:01 +0000 Subject: Added severity and timestamp fields to raised events. Enhanced the example agent to illustrate the raising of events. git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1066726 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/cpp/include/qmf/AgentSession.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'qpid/cpp/include/qmf/AgentSession.h') diff --git a/qpid/cpp/include/qmf/AgentSession.h b/qpid/cpp/include/qmf/AgentSession.h index 23058c56c6..d6ac5adf83 100644 --- a/qpid/cpp/include/qmf/AgentSession.h +++ b/qpid/cpp/include/qmf/AgentSession.h @@ -165,8 +165,14 @@ namespace qmf { /** * Raise an event to be sent into the QMF network. + * + * @param data - A data object that contains the event contents. + * @param severity - Explicit severity (from qmf/SchemaTypes.h). If omitted, the severity is set to + * the default severity for the data's schema. If the data has no schema, the severity defaults + * to SEV_NOTICE. */ - QMF_EXTERN void raiseEvent(const Data&); + QMF_EXTERN void raiseEvent(const Data& data); + QMF_EXTERN void raiseEvent(const Data& data, int severity); #ifndef SWIG private: -- cgit v1.2.1 From eaa84eeb11e11c41da59844675b13ef1a7aaf198 Mon Sep 17 00:00:00 2001 From: Ted Ross Date: Fri, 4 Feb 2011 05:19:43 +0000 Subject: Fixed typos in the documentation text. Fixed bug in the propagation of exceptions in query-processing. Added user-id to messages sent by the console. git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1067087 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/cpp/include/qmf/AgentSession.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'qpid/cpp/include/qmf/AgentSession.h') diff --git a/qpid/cpp/include/qmf/AgentSession.h b/qpid/cpp/include/qmf/AgentSession.h index d6ac5adf83..9e29d6b54b 100644 --- a/qpid/cpp/include/qmf/AgentSession.h +++ b/qpid/cpp/include/qmf/AgentSession.h @@ -69,7 +69,7 @@ namespace qmf { * If False: QMF events are only sent to authorized subscribers * listen-on-direct:{True,False} - If True: Listen on legacy direct-exchange address for backward compatibility [default] * If False: Listen only on the routable direct address - * strict-security:{True,False} - If True: Cooperate with the broker to enforce string access control to the network + * strict-security:{True,False} - If True: Cooperate with the broker to enforce strict access control to the network * - If False: Operate more flexibly with regard to use of messaging facilities [default] */ QMF_EXTERN AgentSession(qpid::messaging::Connection&, const std::string& options=""); -- cgit v1.2.1 From 5edf77f2c04c8428117a04d1d1a4b4cfc1770072 Mon Sep 17 00:00:00 2001 From: Ted Ross Date: Thu, 3 Mar 2011 13:55:11 +0000 Subject: QPID-3046 - Updates - Additional header comments - Added pendingEvents method to ConsoleSession and AgentSession - Ensure that nextEvent will not block if timeout is IMMEDIATE (ConsoleSession and AgentSession). git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1076625 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/cpp/include/qmf/AgentSession.h | 40 +++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 17 deletions(-) (limited to 'qpid/cpp/include/qmf/AgentSession.h') diff --git a/qpid/cpp/include/qmf/AgentSession.h b/qpid/cpp/include/qmf/AgentSession.h index 9e29d6b54b..39d921a8ec 100644 --- a/qpid/cpp/include/qmf/AgentSession.h +++ b/qpid/cpp/include/qmf/AgentSession.h @@ -72,14 +72,14 @@ namespace qmf { * strict-security:{True,False} - If True: Cooperate with the broker to enforce strict access control to the network * - If False: Operate more flexibly with regard to use of messaging facilities [default] */ - QMF_EXTERN AgentSession(qpid::messaging::Connection&, const std::string& options=""); + QMF_EXTERN AgentSession(qpid::messaging::Connection& conn, const std::string& options=""); /** * setDomain - Change the QMF domain that this agent will operate in. If this is not called, * the domain will be "default". Agents in a domain can be seen only by consoles in the same domain. * This must be called prior to opening the agent session. */ - QMF_EXTERN void setDomain(const std::string&); + QMF_EXTERN void setDomain(const std::string& domain); /** * Set identifying attributes of this agent. @@ -88,16 +88,16 @@ namespace qmf { * setInstance - Set the unique instance name (if not set, a UUID will be assigned) * These must be called prior to opening the agent session. */ - QMF_EXTERN void setVendor(const std::string&); - QMF_EXTERN void setProduct(const std::string&); - QMF_EXTERN void setInstance(const std::string&); + QMF_EXTERN void setVendor(const std::string& vendor); + QMF_EXTERN void setProduct(const std::string& product); + QMF_EXTERN void setInstance(const std::string& instance); /** * setAttribute - Set an arbitrary attribute for this agent. The attributes are not used * to uniquely identify the agent but can be used as a search criteria when looking for agents. * This must be called prior to opening the agent session. */ - QMF_EXTERN void setAttribute(const std::string&, const qpid::types::Variant&); + QMF_EXTERN void setAttribute(const std::string& key, const qpid::types::Variant& value); /** * Get the identifying name of the agent. @@ -119,13 +119,19 @@ namespace qmf { * Get the next event from the agent session. Events represent actions that must be acted upon by the * agent application. This method blocks for up to the timeout if there are no events to be handled. * This method will typically be the focus of the agent application's main execution loop. + * If the timeout is set to Duration::IMMEDIATE, the call will not block. */ - QMF_EXTERN bool nextEvent(AgentEvent&, qpid::messaging::Duration timeout=qpid::messaging::Duration::FOREVER); + QMF_EXTERN bool nextEvent(AgentEvent& outEvent, qpid::messaging::Duration timeout=qpid::messaging::Duration::FOREVER); + + /** + * Return the number of events pending for nextEvent. This method will never block. + */ + QMF_EXTERN int pendingEvents() const; /** * Register a schema to be exposed by this agent. */ - QMF_EXTERN void registerSchema(Schema&); + QMF_EXTERN void registerSchema(Schema& schema); /** * Add data to be managed internally by the agent. If the option external:True is selected, this call @@ -138,12 +144,12 @@ namespace qmf { * across different sessions. If persistent, it is the agent application's * responsibility to ensure the name is the same each time it is added. */ - QMF_EXTERN DataAddr addData(Data&, const std::string& name="", bool persistent=false); + QMF_EXTERN DataAddr addData(Data& data, const std::string& name="", bool persistent=false); /** * Delete data from internal agent management. */ - QMF_EXTERN void delData(const DataAddr&); + QMF_EXTERN void delData(const DataAddr& dataAddr); /** * The following methods are used to respond to events received in nextEvent. @@ -155,13 +161,13 @@ namespace qmf { * complete - Indicate that the response to a query is complete (external:True only) * methodSuccess - Indicate the successful completion of a method call. */ - QMF_EXTERN void authAccept(AgentEvent&); - QMF_EXTERN void authReject(AgentEvent&, const std::string& diag=""); - QMF_EXTERN void raiseException(AgentEvent&, const std::string&); - QMF_EXTERN void raiseException(AgentEvent&, const Data&); - QMF_EXTERN void response(AgentEvent&, const Data&); - QMF_EXTERN void complete(AgentEvent&); - QMF_EXTERN void methodSuccess(AgentEvent&); + QMF_EXTERN void authAccept(AgentEvent& event); + QMF_EXTERN void authReject(AgentEvent& event, const std::string& diag=""); + QMF_EXTERN void raiseException(AgentEvent& event, const std::string& errorText); + QMF_EXTERN void raiseException(AgentEvent& event, const Data& errorData); + QMF_EXTERN void response(AgentEvent& event, const Data& responseData); + QMF_EXTERN void complete(AgentEvent& event); + QMF_EXTERN void methodSuccess(AgentEvent& event); /** * Raise an event to be sent into the QMF network. -- cgit v1.2.1 From 2d0338895a2d3629b674f4a3aabea58c77f76504 Mon Sep 17 00:00:00 2001 From: Ted Ross Date: Tue, 17 May 2011 21:02:34 +0000 Subject: QPID-3186 - Import Export generalization to support a larger set of compilers and run time environments git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1104559 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/cpp/include/qmf/AgentSession.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'qpid/cpp/include/qmf/AgentSession.h') diff --git a/qpid/cpp/include/qmf/AgentSession.h b/qpid/cpp/include/qmf/AgentSession.h index 39d921a8ec..1eeb252143 100644 --- a/qpid/cpp/include/qmf/AgentSession.h +++ b/qpid/cpp/include/qmf/AgentSession.h @@ -40,7 +40,7 @@ namespace qmf { class Data; class DataAddr; - class AgentSession : public qmf::Handle { + class QMF_CLASS_EXTERN AgentSession : public qmf::Handle { public: QMF_EXTERN AgentSession(AgentSessionImpl* impl = 0); QMF_EXTERN AgentSession(const AgentSession&); -- cgit v1.2.1