Overview   Class List   Class Hierarchy   Class Members   Functions & Constants   Defines   Header Files  
src / framework / uima

exceptions.hpp File Reference

Detailed Description

. This file contains the base class for all exceptions used in UIMACPP.

DESCRIPTION: Declaration of the classes: ErrorMessage ExceptionDescription Exception AccessError AssertionFailure DeviceError InvalidParameter InvalidRequest ResourceExhausted OutOfMemory OutOfSystemResource OutOfWindowResource

This file also contains many of the macros used to implement the library exception handling mechanism. This includes the UIMA_ASSERT, UIMA_EXC_THROW, UIMA_EXC_RETHROW, UIMA_EXC_CONTEXT, UIMA_EXCEPTION_DESCRIPTION, UIMA_EXC_CLASSDECLARE, UIMA_EXC_CLASSIMPLEMENT, macros.

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file 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 KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file contains the base class for all exceptions used in UIMACPP project. The design goal was to allow for an easy way to provide rich context information with the exception without introducing the need to write lots of lines of code every time you use an exception.

The way this is accomplished here is by defining a rich exception class and then providing macros for its everyday use that hide its complexity and automate a lot of processes.

A UIMACPP exception has an error info object as its main informational member. Such an error info object containes a text, which is supposed to be a simple description of the error with out context (e.g. "Could not open file") an error number and an error severity (recoverable or unrecoverable). To this basic information a list of error contexts can be added (a context has a text and a location, see class ErrorContext above). A context specifies what the program was trying to do, when the error occurred (e.g. "Trying to open file XYZ.ABC for reading") since very often not the whole context a user might need to understand the error is locally available the exception can be re-throw after adding a context. At the point where it is caught more context can be added and again it can be re-thrown until finally the exception can be taken care of (examined/displayed).

This process of defining/catching, adding context and then (re)throwing is what is very convenient to do via the macros defined below.


Namespaces

namespace  uima

Classes

class  uima::ErrorMessage
 Class ErrorMessage: this is a helper class for main class ErrorInfo and ErrorContext. More...
class  uima::ErrorContext
 Class ErrorContext: this is a helper class for main class Exception. More...
class  uima::ErrorInfo
 Class ErrorInfo: This is the base class for all error information used in UIMACPP. More...
class  uima::Exception
 Class Exception: This is the base class for all exceptions used in UIMACPP group projects. More...

Predefined Exceptions (beginning of an error hierarchy).

The following predefined exceptions are supposed to structure the use of exceptions, help with avoiding multiple definitions of common exceptions (e.g.

file not found) and provide a start for an exception hierarchy.

 UIMA_EXC_CLASSDECLARE (Uima_logic_error, Exception)
 logic error
 UIMA_EXC_CLASSDECLARE (Uima_runtime_error, Exception)
 runtime error
 UIMA_EXC_CLASSDECLARE (Uima_domain_error, Uima_logic_error)
 domain error
 UIMA_EXC_CLASSDECLARE (Uima_invalid_argument, Uima_logic_error)
 invalid argument
 UIMA_EXC_CLASSDECLARE (Uima_length_error, Uima_logic_error)
 length error
 UIMA_EXC_CLASSDECLARE (Uima_out_of_range, Uima_logic_error)
 out of range
 UIMA_EXC_CLASSDECLARE (Uima_range_error, Uima_runtime_error)
 range error
 UIMA_EXC_CLASSDECLARE (Uima_overflow_error, Uima_runtime_error)
 overflow error
 UIMA_EXC_CLASSDECLARE (Uima_underflow_error, Uima_runtime_error)
 underflow error
 UIMA_EXC_CLASSDECLARE (ConsoleAbortExc, Exception)
 The following exceptions are used by helper test classes that are no longer in the UIMACPP library: CommandLineDriver DocBuffer ParseHandlers.
 UIMA_EXC_CLASSDECLARE (ExcDocBuffer, Uima_out_of_range)
 UIMA_EXC_CLASSDECLARE (ParseHandlerExc, Exception)
 UIMA_EXC_CLASSDECLARE (ExcIllFormedInputError, Uima_runtime_error)
 Ill formed input.
 UIMA_EXC_CLASSDECLARE (ExcInvalidParameter, Uima_invalid_argument)
 Invalid Parameter.
 UIMA_EXC_CLASSDECLARE (ExcIndexOutOfRange, Uima_out_of_range)
 Index out of Range.
 UIMA_EXC_CLASSDECLARE (ExcInvalidRequest, Uima_runtime_error)
 Invalid Request.
 UIMA_EXC_CLASSDECLARE (ExcResourceExhausted, Uima_runtime_error)
 Resource Exhausted.
 UIMA_EXC_CLASSDECLARE (ExcOutOfMemory, ExcResourceExhausted)
 Out of Memory.
 UIMA_EXC_CLASSDECLARE (ExcFileNotFoundError, Uima_runtime_error)
 File not Found.
 UIMA_EXC_CLASSDECLARE (ExcWinCException, Uima_runtime_error)
 UIMA_EXC_CLASSDECLARE (CodePageConversionException, Exception)
 Used to report code page conversion errors.

Defines

#define UIMA_MSG_MAX_STR_LEN   4096
#define UIMA_MSG_REPLACE_CHAR   '%'
#define EXCEPTION_BASE_CLASS   std::exception
 Define for base class of Exception ANSI compliant STL implementations (newer compilers GNU etc.).
#define UIMA_EXC_CONTEXT(cntxt)   uima::ErrorContext((uima::ErrorMessage)(cntxt), __FILE__, 0, __LINE__)
#define UIMA_EXC_ADD_CONTEXT(exc, cntxt)   exc.getErrorInfo().addContext(UIMA_EXC_CONTEXT((ErrorMessage)(cntxt)))
 This macro is intended to be used for adding context to exceptions.
#define UIMA_EXC_THROW(exc, cntxt)
 This macro is intended to be used for throwing exceptions that are already defined.
#define UIMA_EXC_RETHROW(exc, cntxt)
 This macro is intended to be used for re-throwing caught exceptions with added context.
#define UIMA_EXC_THROW_NEW(exType, errorNbr, errorMsg, exContext, recoverable)
 This macro is intended to be used for throwing exceptions that are not yet defined.
#define UIMA_EXC_ASSERT_EXCEPTION(test)
#define CHILD_DESTRUCT_THROW0()   UIMA_THROW0()
#define UIMA_EXC_CLASSDECLARE(child, parent)
 This macro is intended to derive new exceptions from the base class (or an already derived exception class).
#define UIMA_EXC_CLASSIMPLEMENT(child, parent)
 This macro is intended to derive new exceptions from the base class (or an already derived exception class).

Functions

std::ostream & operator<< (std::ostream &rclOStream, const ErrorMessage &crclExceptionMessage)
 ErrorMessage output support for streams.
std::ostream & operator<< (std::ostream &rclOStream, const ErrorContext &crclExceptionContext)
 ErrorContext output support for streams.
std::ostream & operator<< (std::ostream &rclOStream, const ErrorInfo &crclErrorInfo)
 ErrorInfo output support for streams.
std::ostream & operator<< (std::ostream &rclOStream, const Exception &crclException)
 Exception output support for streams.
 UIMA_EXC_CLASSDECLARE (AprFailureException, Exception)
 The following exception is used to report failures from APR functions.

Define Documentation

#define UIMA_MSG_MAX_STR_LEN   4096
 

#define UIMA_MSG_REPLACE_CHAR   '%'
 

#define EXCEPTION_BASE_CLASS   std::exception
 

Define for base class of Exception ANSI compliant STL implementations (newer compilers GNU etc.).

#define UIMA_EXC_CONTEXT (  cntxt   )     uima::ErrorContext((uima::ErrorMessage)(cntxt), __FILE__, 0, __LINE__)
 

#define UIMA_EXC_ADD_CONTEXT (  exc,
cntxt   )     exc.getErrorInfo().addContext(UIMA_EXC_CONTEXT((ErrorMessage)(cntxt)))
 

This macro is intended to be used for adding context to exceptions.

It adds a the contexts cntxt (file name, function name and line number are automatically added in debug mode = unless NDEBUG is defined) The context can be specified as a single message id or as Message id plus parameters. In the first case just write down the id. In the second case write this parameter like this ErrorMessage(utMsgId, cpszParam1). Note that this macro is not needed if you use the UIMA_EXC_THROW, UIMA_EXC_RETHROW or UIMA_EXC_THROW_NEW macros. You only need it to add context without throwing the exception (e.g. just before printing the exception).

Parameters:
exc The exception (as defined in catch())
cntxt The context string to add (string/char*)

#define UIMA_EXC_THROW (  exc,
cntxt   ) 
 

Value:

exc.getErrorInfo().addContext(UIMA_EXC_CONTEXT(cntxt)),\
      exc.logExceptionData(),\
      throw(exc)
This macro is intended to be used for throwing exceptions that are already defined.

It adds a the contexts string cntxt (file name, function name and line number are automatically added in debug mode = unless NDEBUG is defined) The context can be specified as a single message id or as Message id plus parameters. In the first case just write down the id. In the second case write this parameter like this ErrorMessage(utMsgId, cpszParam1).

Parameters:
exc The exception (must already be defined)
cntxt The context message to add

#define UIMA_EXC_RETHROW (  exc,
cntxt   ) 
 

Value:

exc.getErrorInfo().addContext(UIMA_EXC_CONTEXT(cntxt)),\
  exc.logExceptionData(),\
  throw exc
This macro is intended to be used for re-throwing caught exceptions with added context.

It adds a the contexts string cntxt (file name, function name and line number are automatically added in debug mode = unless NDEBUG is defined) The context can be specified as a single message id or as Message id plus parameters. In the first case just write down the id. In the second case write this parameter like this ErrorMessage(utMsgId, cpszParam1).

Parameters:
exc The exception (as defined in catch())
cntxt The context message to add

#define UIMA_EXC_THROW_NEW (  exType,
errorNbr,
errorMsg,
exContext,
recoverable   ) 
 

Value:

exType exc(errorMsg, errorNbr, recoverable); \
   UIMA_EXC_THROW(exc, exContext)
This macro is intended to be used for throwing exceptions that are not yet defined.

It defines an exception of type extype with error number errorNbr, error message errorMsg, context exContext and severity recoverable. (file name, function name and line number are automatically added to the context in debug mode = unless NDEBUG is defined) The context can be specified as a single message id or as Message id plus parameters. In the first case just write down the id. In the second case write this parameter like this ErrorMessage(utMsgId, cpszParam1).

Parameters:
exType The type of the exception (e.g Exception or FileNotFoundError see below)
errorNbr The error number (long)
errorMsg The error message
exContext The context message to add
recoverable The severity (Exception::recoverable or Exception::unrecoverable)

#define UIMA_EXC_ASSERT_EXCEPTION (  test   ) 
 

 
#define CHILD_DESTRUCT_THROW0 (   )     UIMA_THROW0()
 

#define UIMA_EXC_CLASSDECLARE (  child,
parent   ) 
 

Value:

/*lint -save -e1932 -e1901 -e1931 -e754 -e19  */                              \
class UIMA_LINK_IMPORTSPEC child : public parent {                                                 \
public:                                                                       \
  child (                                                                     \
     uima::ErrorMessage          clMessage,                                    \
     uima::TyErrorId             ulErrorId,                                    \
     uima::ErrorInfo::EnSeverity enSeverity = uima::ErrorInfo::unrecoverable    \
  );                                                                          \
  child (                                                                     \
     uima::ErrorInfo             clErrInfo                                     \
  );                                                                          \
  virtual const char* getName() const;                                        \
  virtual ~child() CHILD_DESTRUCT_THROW0();                                   \
  child (const child &);                                                      \
private:                                                                      \
  child &operator = ( const child & );                                        \
}
This macro is intended to derive new exceptions from the base class (or an already derived exception class).

This will typically be used in .h/.hpp files. For each use of UIMA_EXC_CLASSDECLARE in an .h/.hpp file there must be one use of UIMA_EXC_CLASSIMPLEMENT (see below) in the corresponding .c/.cpp file

Parameters:
child The new class name to define
parent The class to derive the new one from

#define UIMA_EXC_CLASSIMPLEMENT (  child,
parent   ) 
 

Value:

/*lint -save -e1901 -e1911 -e1746 -e1917 -e1902 */        \
  child :: child (                                        \
     uima::ErrorMessage             clMessage,             \
     uima::TyErrorId                ulErrorId,             \
     uima::ErrorInfo::EnSeverity    enSeverity             \
   )                                                      \
    : parent (clMessage, ulErrorId, enSeverity)           \
  {;}                                                     \
  child :: child (                                        \
     uima::ErrorInfo                clInfo                 \
   )                                                      \
    : parent (clInfo)                                     \
  {;}                                                     \
  const char* child :: getName() const {                  \
     return ( # child);                                   \
  }                                                       \
  child :: ~ child () CHILD_DESTRUCT_THROW0() {;}         \
  child::child (const child & a) : parent (a) {;}         \
This macro is intended to derive new exceptions from the base class (or an already derived exception class).

This will typically be used in .c/.cpp files. For each use of UIMA_EXC_CLASSIMPLEMENT in an .h/.hpp file there must be one use of UIMA_EXC_CLASSDECLARE (see above) in the corresponding .h/.hpp file

Parameters:
child The new class name to define
parent The class to derive the new one from

Function Documentation

std::ostream& operator<< (  std::ostream &  rclOStream,
const ErrorMessage &  crclExceptionMessage
) 
 

ErrorMessage output support for streams.

Assuming your message is "Trying to load function %s" and the first argument is "begindoc", your output should look like this: 

  Trying to load function begindoc.

std::ostream& operator<< (  std::ostream &  rclOStream,
const ErrorContext &  crclExceptionContext
) 
 

ErrorContext output support for streams.

This will first stream out the message part of the context and then (indented by spaces) the file name, function name and line number info (if present). This means you will typically get a multi-line text!

If NDEBUG is defined your output should look like this: 

  Trying to load function begindoc.

In debug mode it will look like: 

  Trying to load function begindoc.
        File    : extract.cpp
        Function: ExternalAnnotator::tryGetProcAddress(char*)
        Line    : 87

std::ostream& operator<< (  std::ostream &  rclOStream,
const ErrorInfo &  crclErrorInfo
) 
 

ErrorInfo output support for streams.

This will stream out:

  • Name of the error
  • Recoverability info
  • Error number
  • Error message
  • The ErrorContext part of the exception
This will give you a multi line message!

If NDEBUG is defined your output should look like this: 

  Recoverable   : No
  Error number  : -1
  Error         : Cannot find function address in DLL/library
     While      : Trying to load function begindoc
     While      : Trying to load Annotator IXTalent Test
     While      : Trying to initialize UIMACPP.

In debug mode it will look like: 

  Error number  : -1
  Recoverable   : No
  Error         : Cannot find function address in DLL/library
     While      : Trying to load function begindoc
        File    : extract.cpp
        Function: ExternalAnnotator::tryGetProcAddress(char*)
        Line    : 87
     While      : Trying to load Annotator IXTalent Test
        File    : extracts.cpp
        Function: Annotators::init(AnnotatorsConfig&)
        Line    : 116
     While      : Trying to initialize UIMACPP.
        File    : framewrk.cpp
        Function: Framework::init(const IString&)
        Line    : 128

std::ostream& operator<< (  std::ostream &  rclOStream,
const Exception &  crclException
) 
 

Exception output support for streams.

This will stream out:

  • Name of the exception
  • Error number
  • Recoverability info
  • Exception message
  • The ErrorContext part of the exception
This will give you a multi line message!

If NDEBUG is defined your output should look like this: 

  Exception     : AnnotatorException
  Error number  : -1
  Recoverable   : No
  Error         : Cannot find function address in DLL/library
     While      : Trying to load function begindoc
     While      : Trying to load Annotator IXTalent Test
     While      : Trying to initialize UIMACPP.

In debug mode it will look like: 

  Exception     : AnnotatorException
  Error number  : -1
  Recoverable   : No
  Error         : Cannot find function address in DLL/library
     While      : Trying to load function begindoc
        File    : extract.cpp
        Function: ExternalAnnotator::tryGetProcAddress(char*)
        Line    : 87
     While      : Trying to load Annotator IXTalent Test
        File    : extracts.cpp
        Function: Annotators::init(AnnotatorsConfig&)
        Line    : 116
     While      : Trying to initialize UIMACPP.
        File    : framewrk.cpp
        Function: Framework::init(const IString&)
        Line    : 128

UIMA_EXC_CLASSDECLARE (  Uima_logic_error  ,
Exception 
) 
 

logic error

This is the reason why they have the "unconventional" names: Uima_<ansi name>

UIMA_EXC_CLASSDECLARE (  Uima_runtime_error  ,
Exception 
) 
 

runtime error

UIMA_EXC_CLASSDECLARE (  Uima_domain_error  ,
Uima_logic_error 
) 
 

domain error

UIMA_EXC_CLASSDECLARE (  Uima_invalid_argument  ,
Uima_logic_error 
) 
 

invalid argument

UIMA_EXC_CLASSDECLARE (  Uima_length_error  ,
Uima_logic_error 
) 
 

length error

UIMA_EXC_CLASSDECLARE (  Uima_out_of_range  ,
Uima_logic_error 
) 
 

out of range

UIMA_EXC_CLASSDECLARE (  Uima_range_error  ,
Uima_runtime_error 
) 
 

range error

UIMA_EXC_CLASSDECLARE (  Uima_overflow_error  ,
Uima_runtime_error 
) 
 

overflow error

UIMA_EXC_CLASSDECLARE (  Uima_underflow_error  ,
Uima_runtime_error 
) 
 

underflow error

UIMA_EXC_CLASSDECLARE (  ConsoleAbortExc  ,
Exception 
) 
 

The following exceptions are used by helper test classes that are no longer in the UIMACPP library: CommandLineDriver DocBuffer ParseHandlers.

UIMA_EXC_CLASSDECLARE (  ExcDocBuffer  ,
Uima_out_of_range 
) 
 

UIMA_EXC_CLASSDECLARE (  ParseHandlerExc  ,
Exception 
) 
 

UIMA_EXC_CLASSDECLARE (  ExcIllFormedInputError  ,
Uima_runtime_error 
) 
 

Ill formed input.

UIMA_EXC_CLASSDECLARE (  ExcInvalidParameter  ,
Uima_invalid_argument 
) 
 

Invalid Parameter.

UIMA_EXC_CLASSDECLARE (  ExcIndexOutOfRange  ,
Uima_out_of_range 
) 
 

Index out of Range.

UIMA_EXC_CLASSDECLARE (  ExcInvalidRequest  ,
Uima_runtime_error 
) 
 

Invalid Request.

UIMA_EXC_CLASSDECLARE (  ExcResourceExhausted  ,
Uima_runtime_error 
) 
 

Resource Exhausted.

UIMA_EXC_CLASSDECLARE (  ExcOutOfMemory  ,
ExcResourceExhausted 
) 
 

Out of Memory.

UIMA_EXC_CLASSDECLARE (  ExcFileNotFoundError  ,
Uima_runtime_error 
) 
 

File not Found.

UIMA_EXC_CLASSDECLARE (  ExcWinCException  ,
Uima_runtime_error 
) 
 

UIMA_EXC_CLASSDECLARE (  CodePageConversionException  ,
Exception 
) 
 

Used to report code page conversion errors.

UIMA_EXC_CLASSDECLARE (  AprFailureException  ,
Exception 
) 
 

The following exception is used to report failures from APR functions.

Generated on Mon Oct 1 16:04:12 2012 for UIMACPP API by  doxygen 1.3.9.1