9 Handling exceptions

The Apache Thrift framework can face a range of error conditions including disk errors, network errors, and security violations. Many of these error conditions can occur completely independent of any coding flaws in user code or Apache Thrift. For example, consider a network client communicating with a server over a wireless connection that goes down. The failed wireless link will cause any attempt at communication between the client and server to cause an unexpected error.

Many programming languages provide a means for processing errors separately from an application’s normal flow of control. Exception processing is often associated with object technology, but is supported by a variety of languages and platforms.

Apache Thrift adopts the exception processing model as its abstract model for managing errors. Languages that don’t support exceptions, for example C and Go, return error values instead.

In previous chapters, our examples have largely ignored possible error conditions. As a rule, the code examples in part II of this book are focused on demonstrating features of Apache Thrift using the smallest amount of code. If you have a problem opening, closing, flushing, reading, or writing in these examples, your application will likely exit abruptly because uncaught exceptions typically result in program termination. To make programs more robust you can add statements to test for interface errors. This translates to trapping exceptions, testing return values or handling error events depending on the language.

In the sections ahead, we’ll look briefly at the conceptual Apache Thrift exception hierarchy and examine practical examples of error processing in the three demonstration languages: C++, Java, and Python. We’ll follow this with a look at user-defined exceptions in IDL and how to use them in code.

9.1      Apache Thrift exceptions

The Apache Thrift exception hierachy follows a similar pattern to that of the overall Apache Thrift framework. A base exception type, usually called TException, provides the abstraction used by all concrete Apache Thrift exceptions. Each layer of the Apache Thrift framework typically has its own exception type derived from TException (see figure 9.1).

Many Apache Thrift language implementations derive TException from the the language’s standard base exception, allowing Apache Thrift exceptions to work naturally within the language’s error processing system. For example, the C++ TException is derived from std::exception, the Java TException is derived from java.lang.Exception and the Python TException is derived from the Python built in Exception class. This allows higher level code, even code unaware of the presence of the Apache Thrift framework, to catch exceptions generated by framework code (see figure 9.2).

TException is typically devoid of attributes and methods and provides a base class for all other Apache Thrift exceptions. The principle benefit of TException is that it can be used in catch blocks to catch any error originating from the Apache Thrift framework or Apache Thrift user-defined services.

Four concrete exception types are used throughout Apache Thrift. Each is typically derived from TException and each is associated with a particular layer of the Apache Thrift framework.

These principal exception types can be further specialized in derived classes. For example, the C++ TFileTransport library class can throw a TEOFException when a read request reaches the end of a file. The TEOFException type is derived from TTransportException. Specialization like this is uncommon and these derived exception types can be caught using their base classes, making it less important for Apache Thrift users to have an exhaustive knowledge of the leaf exception classes.

It’s also important to note that, of all of the exception types, users should only create and/or throw user-defined exceptions. User-defined exceptions are thrown by user-coded service handlers in the face of application specific error conditions and are caught by client side code. All other exception types are thrown by the framework, though users may, and often should, catch them in client code.

9.2      TTransportException

End point transports often deal with hardware, exposing them to numerous types of exceptions. The TTransportException is used by the Apache Thrift transport library classes to report internal errors. It’s also possible for software and system layers below Apache Thrift to raise non-Apache Thrift exceptions. In certain cases, Apache Thrift library and generated code will catch external exceptions and then raise a new TTransportException to throw to clients. In other cases, the low-level exceptions will flow directly to the client application.

The TTransportException class has an exception type that can be retrieved using the getType() method in Java and C++, or by reading the “type” attribute directly in Python. The TTransportException exception types are defined as constants directly or through an enumeration depending on the language. The possible types and their numeric representations aren’t necessarily consistent across languages. Table 9.1 shows the TTransportException types defined in the three demonstration languages.

The numeric divergence doesn’t usually represent an interoperability problem because TTransportExceptions don’t typically cross process boundaries. Many sources of this exception leave the type value set to 0 (UNKNOWN) as well.

To get more insight into TTransportException processing we’ll add exception support to the TSimpleFileTransport example programs from chapter 4.

9.2.1  C++ Exception Processing

The following listing shows the C++ file transport example from chapter 4 with exception processing added. The program also includes command line-driven code to generate exceptions as a means to test the exception processing.

The error handling code in this example is compartmentalized, leaving normal program flow unobstructed. The C++ “exception” header (#1) declares the C++ standard library exception class (std::exception). The “Thrift.h” header provides the TException declaration (#2) and the TTransportException.h header decalres the TTransportException (#3).

This short program consists of a single main() function entirely contained within a try block. The catch clauses at the end of the try block traps exceptions in hierachical order, from the most specialied class to the most abstract (see figure 9.3). Apache Thrift libraries throw TTransportExceptions by value and we catch them here by reference (#5), enabling the catch clauses to perform polymorphically. This is important because C++ will process the first matching catch, so if a base class is listed before a derived class the derived class catch will never execute. Most compilers emit warnings associated with catch blocks that are masked by earlier base class catches.

The TTransportException handler traps transport-specific issues, subsequently the TException catch clause (#6) catches any other Thrift exceptions. The std::exception catch (#7) will trap anything derived from the generic C++ standard library exception, and finally the catch-all (…) (#8) will trap everything else that can be caught. While this is a fairly robust exception processing regimen, it’s important to note that certain errors cannot be caught.

Note that the catch types are const. A const reference can catch a variable but the converse is not true. Best practice in C++ is to throw by value and catch by const reference where possible.

The code in this example has been configured to create an illegal file transport if an argument is supplied on the command line (#4). Because TSimpleFileTransports must be either readable or writable the first branch of the if will throw a TTransportException. Here’s an example run:

The session demonstrates a sucessful run and an unsuccessful run. The failed run throws a TTransportException with a type of 0 and a message which the catch block displays.

9.2.2  Java exception processing

The Java programming language provides an exception specification mechanism fairly unique among its peer group. The Java compiler requires methods to catch or declare any exception that might be raised. This makes the types of exceptions possible when calling a certain method easy to dertermine.

The following listing shows the Java version of the exception processing example.

Java defines a small set of “unchecked exceptions”, which need not be declared or caught; however, the lion’s share of Java exceptions must be declared as thrown or caught within a given method. In the main() method in the previous listing, we provide catch clauses for all of the exceptions in the Java exception hierachy leading up to TTransportException (see figure 9.4). The Java compiler will complain if you provide a redundant or unecessary catch clause. In this case, the TException class fits this category (#3) because the only excpetion thrown by the framework methods used here is TTransportException (#2). Though redundant, TException was left in place here to demonstrate catch clauses for the complete exception hierarchy. 

The Java exception hierachy is rooted with the java.lang.Throwable class. The Throwable class catch in the Java example is equivalent to the C++ (…) catch. All things thrown in Java must be of type Throwable. User-defined Java exceptions should derive from java.lang.Exception, which is derived directly from Throwable. The Apache Thrift Java TException class is derived from java.lang.Exception, linking the Thrift exception hierarchy with the Java language exception hierarchy.

Most of the interesting information associated with exceptions in Java is found in the Throwable super class. The Java exception example uses the Throwable toString() method implicitly (#4) to produce string information when logging errors. The TTransportException “type” value is available through the getType() method and is usually the only additional piece of exception information of interest (#2).

Like your C++ example this program has added a command line option that will cause an exception to be generated (#1). If an argument is supplied on the command line this program will create the read transport with only the write flag set to true, causing the first read attempt to fail.

The following listing shows a sample session with the Java program.

In the example, you call methods which may throw a TTransportException but nothing which could throw an Apache Thrift TException, causing the compiler to generate a warning. The first run of the Java program is clean as expected while the second run throws a TTransportException with a type of 0 and an appropriate error message.

9.2.3  Python exception processing

The following listing shows the Python version of the exception processing example.

The Python exception hierachy is similar to the Java exception hierarchy. Python has an internal BaseException class from which all built in exceptions are derived. User-defined exceptions should be derived from the Exception class which itself is derived from BaseException. The Apache Thrift TException class is derived from Exception and is the base for the transport library TTransportException class (see figure 9.5). In the example Python program, you have except blocks to catch all four of the exception classes in the hierarchy from TTransportException up.

This Python program is similar to the prior examples but also includes a block of code which demonstrates the way the Apache Thrift framework raises exceptions (#1). In Python the exception is constructed with a type and a message then thrown with the raise statement. The Python TFileObjectTransport is a thin wrapper around a Python File object (#2). As such, all the exceptions generated in this example would come from the Python File object directly and therefore wouldn’t be derrived from TException.

The TTransportException except block (#3) displays the TTransportException type and any arguments supplied to the exception object when it was constructed. The type attribute is accessed directly and the exception construction arguments, in this case a string, are output as a result of the object’s __str__() default string conversion method. Python offers a type() operator that will produce the string name of the class for the nested object. The Python type() function is used in the except block for Exception (#4). The Python sys module provides an exc_info() method that returns exception information associated with the current exception. This is useful in a default except block where no identifier is available to reference the current exception (#5).

The Python exception example has been coded to raise one of two exceptions in response to one or more command line arguments. If one command line argument is supplied the program raises a TTransportException directly (#1). If two or more arguments are supplied the code opens the read file in write only mode causing the first read to fail.

Here’s a sample session running the previous Python code.

9.2.4  Error processing without exceptions

Languages such as Go and C don’t provide an exception processing mechanism. In such languages errors are generally passed back with each function result. In many languages of this type each function returns a success/failure code. In certain situations, you make a second call to gather error details. In other languages, a generic error structure or pointer is passed to every function call and populated with error data when the function fails.

To better understand non-exception style error processing, you’ll build a glib-based C example. Glib is a cross platform C library providing various utilities, enabling object-oriented programming in C, among other things. It’s used most heavily in Linux GUI development.

The Apache Thrift c_glib code generator doesn’t emit straight C language code. Rather the c_glib libraries rely on g_lib and the GObject system it provides. Even if you cannot run the example in the following listing on your system, the code will give you an understanding of the way Apache Thrift error processing is handled in procedural languages.

This simple program functions much like the prior exception examples. You create a memory transport (#2), open it (#3), write a trade to it (#4), flush the writes (#5) and then read the trade back (#6). The memory buffer will be sized at 1024 bytes by default; however, if one or more parameters are supplied on the command line the buffer size will be made 5 bytes, causing the trade write to fail (#1).

Each library call must be tested for failure in this environment. Most of the Apache Thrift library functions used in this example accept a pointer to a pointer to a GError object. If the function fails, a GError is allocated and initialized with the error information and passed back using the GError ** supplied by the caller. The caller must then release the GError object when finished with it.

To test the program, we run it normally once and then again with a parameter on the command line to cause an error.

You use the GNU C compiler (GCC) to build the program and also take advantage of the pkg-config command, which emits the necessary include and lib paths for build dependencies described in package files. The pkg-config utility originated on Linux but is available on most *nix systems as well as OS X and Windows. The Apache Thrift make install process prepares a /usr/local/lib/pkgconfig/thrift_c_glib.pc file that the pkg-config command uses to set the necessary include directories and libraries for Apache Thrift glib development.

The first run of the program completes normally. The second run is passed a command line parameter and subsequently allocates a small memory transport causing the write operation to fail. The function returns false and passes back an initialized GError object through the error parameter. We then use the error to report the details of the failure.

9.3      TProtocolException

The Thrift Protocol library throws TProtocolException objects when encountering errors. Most protocol error conditions involve reading rather than writing. For example, if a protocol is given a corrupted file to de-serialize or receives a message from a client using the wrong protocol or possibly a mismatched transport stack, a TProtocolException will likely be raised.

The TProtocolException class is almost identical to the TTransportException class, supporting a message and a type. TProtocolExceptions are typically derived from TException in most languages. TProtocolExceptions have their own protocol specific exception type values. Table 9.2 displays the types defined for TProtocolExceptions in the three demonstration languages.

TProtocolExceptions are raised, caught and processed in the same way as TTransportExceptions. Application code interacting with Apache Thrift protocol classes should be prepared to handle TProtocolExceptions, particularly when reading. TProtocolExceptions may be trapped by catching the TProtocolException type directly or by catching TException, or through a language-specific base class.

9.4      TApplicationException

TTransportExceptions and TProtocolExceptions are generated locally and act much like normal language exceptions, propagating inside the process on the thread in which they occur until caught and if uncaught terminate the application. TApplicationExceptions behave differently from normal exceptions. The principle purpose of the TApplicationException class is to allow RPC layer processing errors to propagate from the server back to the client. As the name implies, these exceptions occur at the application layer. In network terms, the “Application” layer includes the RPC system. User code operates at a higher layer and doesn’t generate TApplicationExceptions, rather making use of user defined exceptions, which we cover next. TApplicationExceptions involve problems such as calling a method that isn’t implemented or failing to provide the necessary arguments to a method.

TApplicationExceptions are typically produced by server Processor library code and service specific Processor code generated by the Apache Thrift Compiler. If an RPC error occurs on the server, a TApplicationException will automatically be sent to the client and then thrown or raised when recovered by the client proxy in the client process.

TApplicationExceptions have a type, a message and are derived from TException, much like the TTransportException and TProtocolException classes. Table 9.3 contains a list of the TApplicationException types for each of the three demonstration languages.

TApplicationExceptions are caught and processed in the same way as the previously described exceptions, using normal language mechanisms. The Apache Thrift server-side code need not trap these exceptions because they are always passed back to the calling client. All Apache Thrift RPC client code should be prepared to handle TApplicationExceptions. As you saw in the previous exception processing examples, TApplicationExceptions may be trapped by catching the TApplicationException type directly or by catching TException, or a language-specific base class.

9.5      User-defined exceptions

In the previous sections, we looked at the exceptions thrown by the Transport, Protocol, and RPC layers of the Apache Thrift framework. This leaves the question: what happens when a user-defined service handler runs into trouble?

When an Apache Thrift service handler experiences an error (for example, not being able to find a customer database record, and so on) the service needs a way to report the problem. Raising a local exception, possibly killing the server process, isn’t the desired approach. Service handlers need a way to report errors back to the calling client. In the RPC context, the client may be running on a separate computer and may be coded in a different language, making this process nontrivial.

Fortunately, the Apache Thrift framework makes propagating exceptions in a service handler back to a client seamless. Apache Thrift users can define custom exception types in IDL. Services defined in the IDL file can flag any method as capable of throwing these user-defined exceptions. The IDL Compiler generates Processor code that automatically catches user-defined exceptions raised by the service handler and passes them back to the client where they’re raised as normal client-side exceptions by the client proxy.

Like TApplicationExceptions, user-defined exceptions are derived from TException. The distinction is that TApplicationExceptions are raised by the Apache Thrift framework and user-defined exceptions are raised by user code.

For example, if a program used by a seafood distributor calls an Apache Thrift fish market server to retrieve the price of Halibut, but Halibut isn’t in the database. The service handler can raise a user-defined BadFish exception. The Apache Thrift framework will then pass the BadFish exception back to the client automatically (see figure 9.6). It’s important to recognize that user-defined exceptions are an integral part of a service’s interface and therefore defined within the IDL.

9.5.1  User-defined exception IDL example

To get a better feel for how user-defined exceptions work, let’s build an exception-enabled RPC application. The TradeHistory service example in the following listing provides a GetLastSale() method returning the going price for fish. However, if an unsupported fish type is requested, such as halibut, an exception will be generated. Here’s the IDL that declares the exception for bad fish requests and then associates it with your GetLastSale() method.

Defining a custom exception in Apache Thrift IDL is exactly like defining a struct but with the exception keyword (#1). In fact, Apache Thrift implements exceptions using structs internally.

The IDL “throws” keyword associates exceptions with the methods that might throw them (#2). Exception types are listed within parenthesis separated by commas. Elements in the throws list are each given a unique positive Id value, like fields in an exception declaration and parameters in an argument list. In the previous example, the GetLastSale() method throws only one exception type, BadFish, with an Id of 1.

9.5.2  C++ user-defined exception client

A client program using the TradeHistory service GetLastSale() method should be prepared to handle the BadFish exception. The following listing shows a sample C++ client listing that calls GetLastSale() and processes the BadFish exception if thrown.

The sample program provides code to trap the user defined exception (#1) as well as any other exceptions that may be raised (#2).

9.5.3  C++ user-defined exception server

User-defined exceptions are raised on the server by using the native language exception mechanism in the service handler. For example, to raise the BadFish exception in the GetLastSale() handler of a C++ TradeHistory implementation, you’d use the C++ throw statement with a BadFish object.

To get a complete picture of the user defined exception process you’ll build a simple RPC server example using your excep.thrift IDL. The session below compiles the excep.thrift IDL, generating C++ RPC stubs used by your C++ client and RPC server.

Compiling the IDL produces the standard *_types files which house your IDL types, including exception types (#1). The IDL Compiler C++ code generator also creates a server skeleton for any services defined in the IDL source (#2). With a few lines of code, we can modify the skeleton for the TradeHistory service so that it throws the BadFish exception when the price of a fish we don’t carry is requested. In the following listing, you throw a user-defined exception for any request other than halibut. It’s a good idea to copy the server skeleton to a new filename before you modify it, because it will be overwritten each time you rerun the IDL Compiler. Here’s an example listing for the modified C++ server skeleton.

Because user-defined exceptions are another kind of user-defined type you must include the IDL *_types.h header to provide exceptions definitions within your code. The exception can then be constructed, initialized, and thrown from the service handler. This is exactly like throwing an exception in a standalone program.

The following session compiles the example client and server then runs the server.

With the server running, you can start the client program in a separate shell to test normal and exceptional RPC responses.

The completed example demonstrates a common scenario, that of a service running in one process detecting an error that needs to be passed back to a client. The Apache Thrift exception mechanism provides an elegant and seamless solution, wherein both the service code and the client code use their native (and potentially different) error processing mechanisms, with Apache Thrift generating the glue necessary to connect the two.

9.5.4  Java user-defined exception client

To illustrate cross-language exceptions you can recreate the C++ exception client in Java.

The following listing shows a sample session building and running the Java client against the C++ server (which must be running in another shell).

This session runs much like the C++ client session. It’s worth appreciating the fact that in this example a C++ exception object was thrown in a C++ service, trapped by the Apache Thrift processor, serialized into a binary stream, transmitted to the Java client proxy, de-serialized into a Java exception object, and thrown in the Java client process. This is a lot of functionality in exchange for a few lines of IDL.

9.5.5  Python user-defined exception client

To round out the examples, the following listing demonstrates the exception client coded in Python.

Here’s a session running the Python client with a normal and an exceptional call against the C++ server in the previous listing.

9.6      Summary

This chapter has examined the exception processing features and components of the Apache Thrift framework. We looked at the predefined library exception classes used by Apache Thrift and also examined the features supporting user-defined exceptions in IDL and RPC services. The key points from this chapter are: