From 0ae96a662d846c5aff47e1a76242d3fb67452e2f Mon Sep 17 00:00:00 2001
From: Gordon Sim <gsim@apache.org>
Date: Mon, 5 Sep 2011 19:00:23 +0000
Subject: NO-JIRA: Additional doxygen comments for exceptions

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1165391 13f79535-47bb-0310-9956-ffa450edef68
---
 qpid/cpp/docs/api/doxygen_mainpage.h         | 41 ++++++++++++++++-
 qpid/cpp/include/qpid/messaging/Session.h    | 45 +++++++++++++++++-
 qpid/cpp/include/qpid/messaging/exceptions.h | 68 +++++++++++++++++++++++-----
 3 files changed, 140 insertions(+), 14 deletions(-)

diff --git a/qpid/cpp/docs/api/doxygen_mainpage.h b/qpid/cpp/docs/api/doxygen_mainpage.h
index cb36d7edb0..9acae52da4 100644
--- a/qpid/cpp/docs/api/doxygen_mainpage.h
+++ b/qpid/cpp/docs/api/doxygen_mainpage.h
@@ -266,7 +266,46 @@
  * else 
  *    session.rollback();
  * </pre>
- * 
+ *
+ * <h3>Exceptions</h3>
+ *
+ * All exceptions for the messaging API have MessagingException as
+ * their base class.
+
+ * A common class of exception are those related to processing
+ * addresses used to create senders and/or receivers. These all have
+ * AddressError as their base class.
+ *
+ * Where there is a syntax error in the address itself, a
+ * MalformedAddress will be thrown. Where the address is valid, but
+ * there is an error in interpreting (i.e. resolving) it, a
+ * ResolutionError - or a sub-class of it - will be thrown. If the
+ * address has assertions enabled for a given context and the asserted
+ * node properties are not in fact correct then AssertionFailed will
+ * be thrown. If the node is not found, NotFound will be thrown.
+ *
+ * The loss of the underlying connection (e.g. the TCP connection)
+ * results in TransportFailure being thrown. If automatic reconnect is
+ * enabled, this will be caught be the library which will then try to
+ * reconnect. If reconnection - as configured by the connection
+ * options - fails, then TransportFailure will be thrown. This can
+ * occur on any call to the messaging API.
+ *
+ * Sending a message may also result in an exception
+ * (e.g. TargetCapacityExceeded if a queue to which the message is
+ * delivered cannot enqueue it due to lack of capacity). For
+ * asynchronous send the exception may not be thrown on the send
+ * invocation that actually triggers it, but on a subsequent method
+ * call on the API.
+ *
+ * Certain exceptions may render the session invalid; once these
+ * occur, subsequent calls on the session will throw the same class of
+ * exception. This is not an intrinsic property of the class of
+ * exception, but is a result of the current mapping of the API to the
+ * underlying AMQP 0-10 protocol. You can test whether the session is
+ * valid at any time using the hasError() and/or checkError() methods
+ * on Session.
+ *
  * <h3>Logging</h3>
  * 
  * The Qpidd broker and C++ clients can both use environment variables to
diff --git a/qpid/cpp/include/qpid/messaging/Session.h b/qpid/cpp/include/qpid/messaging/Session.h
index 428f8aa491..e8d6efb35d 100644
--- a/qpid/cpp/include/qpid/messaging/Session.h
+++ b/qpid/cpp/include/qpid/messaging/Session.h
@@ -62,6 +62,12 @@ class QPID_MESSAGING_CLASS_EXTERN Session : public qpid::messaging::Handle<Sessi
      */
     QPID_MESSAGING_EXTERN void close();
 
+    /**
+     * Commits the sessions transaction.
+     *
+     * @exception TransactionAborted if the original session is lost
+     * forcing an automatic rollback.
+     */
     QPID_MESSAGING_EXTERN void commit();
     QPID_MESSAGING_EXTERN void rollback();
 
@@ -139,25 +145,51 @@ class QPID_MESSAGING_CLASS_EXTERN Session : public qpid::messaging::Handle<Sessi
     /**
      * Create a new sender through which messages can be sent to the
      * specified address.
+     *
+     * @exception ResolutionError if there is an error in resolving
+     * the address
      */
     QPID_MESSAGING_EXTERN Sender createSender(const Address& address);
+    /**
+     * Create a new sender through which messages can be sent to the
+     * specified address.
+     *
+     * @exception ResolutionError if there is an error in resolving
+     * the address
+     *
+     * @exception MalformedAddress if the syntax of address is not
+     * valid
+     */
     QPID_MESSAGING_EXTERN Sender createSender(const std::string& address);
 
     /**
      * Create a new receiver through which messages can be received
      * from the specified address.
+     *
+     * @exception ResolutionError if there is an error in resolving
+     * the address
      */
     QPID_MESSAGING_EXTERN Receiver createReceiver(const Address& address);
+    /**
+     * Create a new receiver through which messages can be received
+     * from the specified address.
+     *
+     * @exception ResolutionError if there is an error in resolving
+     * the address
+     *
+     * @exception MalformedAddress if the syntax of address is not
+     * valid
+     */
     QPID_MESSAGING_EXTERN Receiver createReceiver(const std::string& address);
 
     /**
      * Returns the sender with the specified name.
-     *@exception KeyError if there is none for that name.
+     * @exception KeyError if there is none for that name.
      */
     QPID_MESSAGING_EXTERN Sender getSender(const std::string& name) const;
     /**
      * Returns the receiver with the specified name.
-     *@exception KeyError if there is none for that name.
+     * @exception KeyError if there is none for that name.
      */
     QPID_MESSAGING_EXTERN Receiver getReceiver(const std::string& name) const;
     /**
@@ -166,7 +198,16 @@ class QPID_MESSAGING_CLASS_EXTERN Session : public qpid::messaging::Handle<Sessi
      */
     QPID_MESSAGING_EXTERN Connection getConnection() const;
 
+    /**
+     * @returns true if the session has been rendered invalid by some
+     * exception, false if it is valid for use.
+     */
     QPID_MESSAGING_EXTERN bool hasError();
+    /**
+     * If the session has been rendered invalid by some exception,
+     * this method will result in that exception being thrown on
+     * calling this method.
+     */
     QPID_MESSAGING_EXTERN void checkError();
 
 #ifndef SWIG
diff --git a/qpid/cpp/include/qpid/messaging/exceptions.h b/qpid/cpp/include/qpid/messaging/exceptions.h
index 07d1dc414b..31e2488d91 100644
--- a/qpid/cpp/include/qpid/messaging/exceptions.h
+++ b/qpid/cpp/include/qpid/messaging/exceptions.h
@@ -10,9 +10,9 @@
  * 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
@@ -29,23 +29,36 @@
 namespace qpid {
 namespace messaging {
 
-/** \ingroup messaging 
+/** \ingroup messaging
  */
 
-struct QPID_MESSAGING_CLASS_EXTERN MessagingException : public qpid::types::Exception 
+/**
+ * This is the base class for all messaging related exceptions thrown
+ * by this API.
+ */
+struct QPID_MESSAGING_CLASS_EXTERN MessagingException : public qpid::types::Exception
 {
     QPID_MESSAGING_EXTERN MessagingException(const std::string& msg);
     QPID_MESSAGING_EXTERN virtual ~MessagingException() throw();
-    
+
     qpid::types::Variant::Map detail;
     //TODO: override what() to include detail if present
 };
 
-struct QPID_MESSAGING_CLASS_EXTERN InvalidOptionString : public MessagingException 
+/**
+ * Thrown when the syntax of the option string used to configure a
+ * connection in not valid
+ */
+struct QPID_MESSAGING_CLASS_EXTERN InvalidOptionString : public MessagingException
 {
     QPID_MESSAGING_EXTERN InvalidOptionString(const std::string& msg);
 };
 
+/**
+ * Thrown to indicate a failed lookup of some local object. For
+ * example when attempting to retrieve a session, sender or receiver
+ * by name.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN KeyError : public MessagingException
 {
     QPID_MESSAGING_EXTERN KeyError(const std::string&);
@@ -65,25 +78,33 @@ struct QPID_MESSAGING_CLASS_EXTERN AddressError : public LinkError
  * Thrown when a syntactically correct address cannot be resolved or
  * used.
  */
-struct QPID_MESSAGING_CLASS_EXTERN ResolutionError : public AddressError 
+struct QPID_MESSAGING_CLASS_EXTERN ResolutionError : public AddressError
 {
     QPID_MESSAGING_EXTERN ResolutionError(const std::string& msg);
 };
 
-struct QPID_MESSAGING_CLASS_EXTERN AssertionFailed : public ResolutionError 
+/**
+ * Thrown when creating a sender or receiver for an address for which
+ * some asserted property of the node is not matched.
+ */
+struct QPID_MESSAGING_CLASS_EXTERN AssertionFailed : public ResolutionError
 {
     QPID_MESSAGING_EXTERN AssertionFailed(const std::string& msg);
 };
 
-struct QPID_MESSAGING_CLASS_EXTERN NotFound : public ResolutionError 
+/**
+ * Thrown on attempts to create a sender or receiver to a non-existent
+ * node.
+ */
+struct QPID_MESSAGING_CLASS_EXTERN NotFound : public ResolutionError
 {
     QPID_MESSAGING_EXTERN NotFound(const std::string& msg);
 };
 
 /**
- * Thrown when an address string with inalid sytanx is used.
+ * Thrown when an address string with invalid syntax is used.
  */
-struct QPID_MESSAGING_CLASS_EXTERN MalformedAddress : public AddressError 
+struct QPID_MESSAGING_CLASS_EXTERN MalformedAddress : public AddressError
 {
     QPID_MESSAGING_EXTERN MalformedAddress(const std::string& msg);
 };
@@ -98,6 +119,11 @@ struct QPID_MESSAGING_CLASS_EXTERN FetchError : public ReceiverError
     QPID_MESSAGING_EXTERN FetchError(const std::string&);
 };
 
+/**
+ * Thrown by Receiver::fetch(), Receiver::get() and
+ * Session::nextReceiver() to indicate that there no message was
+ * available before the timeout specified.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN NoMessageAvailable : public FetchError
 {
     QPID_MESSAGING_EXTERN NoMessageAvailable();
@@ -113,6 +139,11 @@ struct QPID_MESSAGING_CLASS_EXTERN SendError : public SenderError
     QPID_MESSAGING_EXTERN SendError(const std::string&);
 };
 
+/**
+ * Thrown to indicate that the sender attempted to send a message that
+ * would result in the target node on the peer exceeding a
+ * preconfigured capacity.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN TargetCapacityExceeded : public SendError
 {
     QPID_MESSAGING_EXTERN TargetCapacityExceeded(const std::string&);
@@ -128,11 +159,19 @@ struct QPID_MESSAGING_CLASS_EXTERN TransactionError : public SessionError
     QPID_MESSAGING_EXTERN TransactionError(const std::string&);
 };
 
+/**
+ * Thrown on Session::commit() if reconnection results in the
+ * transaction being automatically aborted.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN TransactionAborted : public TransactionError
 {
     QPID_MESSAGING_EXTERN TransactionAborted(const std::string&);
 };
 
+/**
+ * Thrown to indicate that the application attempted to do something
+ * for which it was not authorised by its peer.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN UnauthorizedAccess : public SessionError
 {
     QPID_MESSAGING_EXTERN UnauthorizedAccess(const std::string&);
@@ -143,6 +182,13 @@ struct QPID_MESSAGING_CLASS_EXTERN ConnectionError : public MessagingException
     QPID_MESSAGING_EXTERN ConnectionError(const std::string&);
 };
 
+/**
+ * Thrown to indicate loss of underlying connection. When
+ * auto-reconnect is used this will be caught by the library and used
+ * to trigger reconnection attempts. If reconnection fails (according
+ * to whatever settings have been configured), then an instnace of
+ * this class will be thrown to signal that.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN TransportFailure : public MessagingException
 {
     QPID_MESSAGING_EXTERN TransportFailure(const std::string&);
-- 
cgit v1.2.1