-
Language:
English
-
Language:
English
Chapter 10. Error handling
Errors in AMQ C++ can be handled in two different ways:
- Catching exceptions
- Overriding virtual functions to handle AMQP protocol or connection errors
Catching exceptions is the most basic, but least granular, way to handle errors. If an error is not handled using an override in a handler routine, an exception is thrown and can be caught and handled.
10.1. Handling exceptions
If an error is not handled using an override in a handler routine, an exception is thrown by the container’s run
method.
All of the exceptions that AMQ C++ throws inherit from the proton::error
class, which in turn inherits from the std::runtime_error
and std::exception
classes.
The following example illustrates how to catch any exception thrown from AMQ C++:
Example: API-Specific exception handling
try { // Something that might throw an exception } catch (proton::error& e) { // Handle Proton-specific problems here } catch (std::exception& e) { // Handle more general problems here }
If you do not require API-specific exception handling, you only need to catch std::exception
, since proton::error
inherits from it.
Example: General exception handling
int main() { try { // Something that might throw an exception } catch (std::exception& e) { std::cerr << "Caught exception: " << e.what() << std::endl; } }
Because all exceptions in a C++ program inherit from std::exception
, you can write a code block to wrap your main
method and display information about any std::exception
errors.
10.2. Handling connection and protocol errors
You can handle protocol-level errors by overriding the following messaging_handler
methods:
-
on_transport_error(proton::transport&)
-
on_connection_error(proton::connection&)
-
on_session_error(proton::session&)
-
on_receiver_error(proton::receiver&)
-
on_sender_error(proton::sender&)
These event handling routines are called whenever there is an error condition with the specific object that is in the event. After calling the error handler, the appropriate close handler is also called.
If not overridden, the default error handler will be called with an indication of the error condition that occurred.
If one of the more specific error handlers is not overridden, the default error handler is called:
-
on_error(proton::error_condition&)
As the close handlers are called in the event of any error, only the error itself needs to be handled within the error handler. Resource clean up can be managed by close handlers. If there is no error handling that is specific to a particular object it is typical to use the general on_error
handler and not have a more specific handler.
10.3. Logging
10.3.1. Enabling protocol logging
The client can log AMQP protocol frames to the console. This data is often critical when diagnosing problems.
To enable protocol logging, set the PN_TRACE_FRM
environment variable to 1
:
Example: Enabling protocol logging
$ export PN_TRACE_FRM=1
$ <your-client-program>
To disable protocol logging, unset the PN_TRACE_FRM
environment variable.