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... | |
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 & | uima::operator<< (std::ostream &rclOStream, const ErrorMessage &crclExceptionMessage) |
ErrorMessage output support for streams. | |
std::ostream & | uima::operator<< (std::ostream &rclOStream, const ErrorContext &crclExceptionContext) |
ErrorContext output support for streams. | |
std::ostream & | uima::operator<< (std::ostream &rclOStream, const ErrorInfo &crclErrorInfo) |
ErrorInfo output support for streams. | |
std::ostream & | uima::operator<< (std::ostream &rclOStream, const Exception &crclException) |
Exception output support for streams. | |
uima::UIMA_EXC_CLASSDECLARE (AprFailureException, Exception) | |
The following exception is used to report failures from APR functions. | |
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::UIMA_EXC_CLASSDECLARE (Uima_logic_error, Exception) | |
The following classes reimplement the ANSI standard exception hierarchy from stdexcept.h as exceptions with context and message id support. | |
uima::UIMA_EXC_CLASSDECLARE (Uima_runtime_error, Exception) | |
runtime error | |
uima::UIMA_EXC_CLASSDECLARE (Uima_domain_error, Uima_logic_error) | |
domain error | |
uima::UIMA_EXC_CLASSDECLARE (Uima_invalid_argument, Uima_logic_error) | |
invalid argument | |
uima::UIMA_EXC_CLASSDECLARE (Uima_length_error, Uima_logic_error) | |
length error | |
uima::UIMA_EXC_CLASSDECLARE (Uima_out_of_range, Uima_logic_error) | |
out of range | |
uima::UIMA_EXC_CLASSDECLARE (Uima_range_error, Uima_runtime_error) | |
range error | |
uima::UIMA_EXC_CLASSDECLARE (Uima_overflow_error, Uima_runtime_error) | |
overflow error | |
uima::UIMA_EXC_CLASSDECLARE (Uima_underflow_error, Uima_runtime_error) | |
underflow error | |
uima::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::UIMA_EXC_CLASSDECLARE (ExcDocBuffer, Uima_out_of_range) | |
uima::UIMA_EXC_CLASSDECLARE (ParseHandlerExc, Exception) | |
uima::UIMA_EXC_CLASSDECLARE (ExcIllFormedInputError, Uima_runtime_error) | |
The following classes provide a starting point for an exception hierarchy. | |
uima::UIMA_EXC_CLASSDECLARE (ExcInvalidParameter, Uima_invalid_argument) | |
Invalid Parameter. | |
uima::UIMA_EXC_CLASSDECLARE (ExcIndexOutOfRange, Uima_out_of_range) | |
Index out of Range. | |
uima::UIMA_EXC_CLASSDECLARE (ExcInvalidRequest, Uima_runtime_error) | |
Device Error. | |
uima::UIMA_EXC_CLASSDECLARE (ExcResourceExhausted, Uima_runtime_error) | |
Resource Exhausted. | |
uima::UIMA_EXC_CLASSDECLARE (ExcOutOfMemory, ExcResourceExhausted) | |
Out of Memory. | |
uima::UIMA_EXC_CLASSDECLARE (ExcFileNotFoundError, Uima_runtime_error) | |
Out of System Resource. | |
uima::UIMA_EXC_CLASSDECLARE (ExcWinCException, Uima_runtime_error) | |
uima::UIMA_EXC_CLASSDECLARE (CodePageConversionException, Exception) | |
Used to report code page conversion errors. |
#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).
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)
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)
.
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
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)
.
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)
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)
.
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 ) |
Referenced by uima::util::DirectoryWalk::DirectoryWalk(), uima::util::DllProcLoaderFile::DllProcLoaderFile(), uima::util::EnvironmentVariableQueryOnly::EnvironmentVariableQueryOnly(), uima::util::Location::makeDirectory(), and uima::Annotator::next().
#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 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
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 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
child | The new class name to define | |
parent | The class to derive the new one from |