diff options
author | Gordon Sim <gsim@apache.org> | 2011-09-05 19:00:23 +0000 |
---|---|---|
committer | Gordon Sim <gsim@apache.org> | 2011-09-05 19:00:23 +0000 |
commit | 0ae96a662d846c5aff47e1a76242d3fb67452e2f (patch) | |
tree | 7732bc9b3e1d3036f1214e024cff49eca9f5673f | |
parent | 2268ec22cca52841b2a45e2ca6398a727bc1e312 (diff) | |
download | qpid-python-0ae96a662d846c5aff47e1a76242d3fb67452e2f.tar.gz |
NO-JIRA: Additional doxygen comments for exceptions
git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1165391 13f79535-47bb-0310-9956-ffa450edef68
-rw-r--r-- | qpid/cpp/docs/api/doxygen_mainpage.h | 41 | ||||
-rw-r--r-- | qpid/cpp/include/qpid/messaging/Session.h | 45 | ||||
-rw-r--r-- | 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&); |