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

5 files changed, 84 insertions, 26 deletions

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.
diff --git a/qpid/cpp/include/qmf/ConsoleSession.h b/qpid/cpp/include/qmf/ConsoleSession.h
index 0c73e7a6db..896f8ffda7 100644
--- a/qpid/cpp/include/qmf/ConsoleSession.h
+++ b/qpid/cpp/include/qmf/ConsoleSession.h
@@ -62,14 +62,48 @@ 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 ConsoleSession(qpid::messaging::Connection&, const std::string& options="");
-        QMF_EXTERN void setDomain(const std::string&);
-        QMF_EXTERN void setAgentFilter(const std::string&);
+        QMF_EXTERN ConsoleSession(qpid::messaging::Connection& conn, const std::string& options="");
+
+        /**
+         * setDomain - Change the QMF domain that this console 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 console session.
+         */
+        QMF_EXTERN void setDomain(const std::string& domain);
+        QMF_EXTERN void setAgentFilter(const std::string& filter);
+
+        /**
+         * Open the console session.  After opening the session, the domain 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();
-        QMF_EXTERN bool nextEvent(ConsoleEvent&, qpid::messaging::Duration timeout=qpid::messaging::Duration::FOREVER);
+
+        /**
+         * Get the next event from the console session.  Events represent actions that must be acted upon by the
+         * console 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 console application's main execution loop.
+         * If the timeout is set to Duration::IMMEDIATE, the call will not block.
+         */
+        QMF_EXTERN bool nextEvent(ConsoleEvent& 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;
+
+        /**
+         * getAgentCount, getAgent - Retrieve the set of agents that match the console session's agent filter.
+         */
         QMF_EXTERN uint32_t getAgentCount() const;
-        QMF_EXTERN Agent getAgent(uint32_t) const;
+        QMF_EXTERN Agent getAgent(uint32_t agentIndex) const;
+
+        /**
+         * Get the agent for the connected broker (i.e. the agent embedded in the broker to which we have a connection).
+         */
         QMF_EXTERN Agent getConnectedBrokerAgent() const;
 
         /**
@@ -79,8 +113,8 @@ namespace qmf {
          * will involve all known agents.  If agentFilter is non-empty, it will be applied only to the set of known
          * agents.  A subscription cannot be created that involves an agent not known by the session.
          */
-        QMF_EXTERN Subscription subscribe(const Query&,       const std::string& agentFilter = "", const std::string& options = "");
-        QMF_EXTERN Subscription subscribe(const std::string&, const std::string& agentFilter = "", const std::string& options = "");
+        QMF_EXTERN Subscription subscribe(const Query& query,       const std::string& agentFilter = "", const std::string& options = "");
+        QMF_EXTERN Subscription subscribe(const std::string& query, const std::string& agentFilter = "", const std::string& options = "");
 
 #ifndef SWIG
     private:
diff --git a/qpid/cpp/src/qmf/AgentSession.cpp b/qpid/cpp/src/qmf/AgentSession.cpp
index 4c5a72a467..71d369325f 100644
--- a/qpid/cpp/src/qmf/AgentSession.cpp
+++ b/qpid/cpp/src/qmf/AgentSession.cpp
@@ -72,6 +72,7 @@ namespace qmf {
         void open();
         void close();
         bool nextEvent(AgentEvent& e, Duration t);
+        int pendingEvents() const;
 
         void registerSchema(Schema& s);
         DataAddr addData(Data& d, const string& n, bool persist);
@@ -161,6 +162,7 @@ const string& AgentSession::getName() const { return impl->getName(); }
 void AgentSession::open() { impl->open(); }
 void AgentSession::close() { impl->close(); }
 bool AgentSession::nextEvent(AgentEvent& e, Duration t) { return impl->nextEvent(e, t); }
+int AgentSession::pendingEvents() const { return impl->pendingEvents(); }
 void AgentSession::registerSchema(Schema& s) { impl->registerSchema(s); }
 DataAddr AgentSession::addData(Data& d, const string& n, bool p) { return impl->addData(d, n, p); }
 void AgentSession::delData(const DataAddr& a) { impl->delData(a); }
@@ -318,7 +320,7 @@ bool AgentSessionImpl::nextEvent(AgentEvent& event, Duration timeout)
     uint64_t milliseconds = timeout.getMilliseconds();
     qpid::sys::Mutex::ScopedLock l(lock);
 
-    if (eventQueue.empty())
+    if (eventQueue.empty() && milliseconds > 0)
         cond.wait(lock, qpid::sys::AbsTime(qpid::sys::now(),
                                            qpid::sys::Duration(milliseconds * qpid::sys::TIME_MSEC)));
 
@@ -332,6 +334,13 @@ bool AgentSessionImpl::nextEvent(AgentEvent& event, Duration timeout)
 }
 
 
+int AgentSessionImpl::pendingEvents() const
+{
+    qpid::sys::Mutex::ScopedLock l(lock);
+    return eventQueue.size();
+}
+
+
 void AgentSessionImpl::registerSchema(Schema& schema)
 {
     if (!schema.isFinalized())
diff --git a/qpid/cpp/src/qmf/ConsoleSession.cpp b/qpid/cpp/src/qmf/ConsoleSession.cpp
index e12c1152f6..2136a7d449 100644
--- a/qpid/cpp/src/qmf/ConsoleSession.cpp
+++ b/qpid/cpp/src/qmf/ConsoleSession.cpp
@@ -54,6 +54,7 @@ void ConsoleSession::setAgentFilter(const string& f) { impl->setAgentFilter(f);
 void ConsoleSession::open() { impl->open(); }
 void ConsoleSession::close() { impl->close(); }
 bool ConsoleSession::nextEvent(ConsoleEvent& e, Duration t) { return impl->nextEvent(e, t); }
+int ConsoleSession::pendingEvents() const { return impl->pendingEvents(); }
 uint32_t ConsoleSession::getAgentCount() const { return impl->getAgentCount(); }
 Agent ConsoleSession::getAgent(uint32_t i) const { return impl->getAgent(i); }
 Agent ConsoleSession::getConnectedBrokerAgent() const { return impl->getConnectedBrokerAgent(); }
@@ -213,7 +214,7 @@ bool ConsoleSessionImpl::nextEvent(ConsoleEvent& event, Duration timeout)
     uint64_t milliseconds = timeout.getMilliseconds();
     qpid::sys::Mutex::ScopedLock l(lock);
 
-    if (eventQueue.empty())
+    if (eventQueue.empty() && milliseconds > 0)
         cond.wait(lock, qpid::sys::AbsTime(qpid::sys::now(),
                                            qpid::sys::Duration(milliseconds * qpid::sys::TIME_MSEC)));
 
@@ -227,6 +228,13 @@ bool ConsoleSessionImpl::nextEvent(ConsoleEvent& event, Duration timeout)
 }
 
 
+int ConsoleSessionImpl::pendingEvents() const
+{
+    qpid::sys::Mutex::ScopedLock l(lock);
+    return eventQueue.size();
+}
+
+
 uint32_t ConsoleSessionImpl::getAgentCount() const
 {
     qpid::sys::Mutex::ScopedLock l(lock);
diff --git a/qpid/cpp/src/qmf/ConsoleSessionImpl.h b/qpid/cpp/src/qmf/ConsoleSessionImpl.h
index 675c8bcfb5..411b3f016a 100644
--- a/qpid/cpp/src/qmf/ConsoleSessionImpl.h
+++ b/qpid/cpp/src/qmf/ConsoleSessionImpl.h
@@ -58,6 +58,7 @@ namespace qmf {
         void open();
         void close();
         bool nextEvent(ConsoleEvent& e, qpid::messaging::Duration t);
+        int pendingEvents() const;
         uint32_t getAgentCount() const;
         Agent getAgent(uint32_t i) const;
         Agent getConnectedBrokerAgent() const { return connectedBrokerAgent; }