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 | 3660beb798c16800c6fc3ad153acff99790e16ff (patch) | |
tree | 48cfbac46874b59782fbaef8347592280cf20188 /cpp/include/qpid | |
parent | 62b5bbd27131a2a40d228ccc61704b83db374a95 (diff) | |
download | qpid-python-3660beb798c16800c6fc3ad153acff99790e16ff.tar.gz |
NO-JIRA: Additional doxygen comments for exceptions
git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1165391 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'cpp/include/qpid')
-rw-r--r-- | cpp/include/qpid/messaging/Session.h | 45 | ||||
-rw-r--r-- | cpp/include/qpid/messaging/exceptions.h | 68 |
2 files changed, 100 insertions, 13 deletions
diff --git a/cpp/include/qpid/messaging/Session.h b/cpp/include/qpid/messaging/Session.h index 428f8aa491..e8d6efb35d 100644 --- a/cpp/include/qpid/messaging/Session.h +++ b/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/cpp/include/qpid/messaging/exceptions.h b/cpp/include/qpid/messaging/exceptions.h index 07d1dc414b..31e2488d91 100644 --- a/cpp/include/qpid/messaging/exceptions.h +++ b/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&); |