Isis exception class. More...

#include <IException.h>

Inheritance diagram for Isis::IException:

Collaboration diagram for Isis::IException:

Public Types
enum	ErrorType { Unknown = 1 , User , Programmer , Io }
	Contains a set of exception error types. More...

Public Member Functions
	IException ()
	The default constructor creates an IException instance with no message, previous exceptions, or file info.

	IException (ErrorType type, const char message, const char fileName, int lineNumber)
	This version of the constructor creates an IException instance with the given error type, message, and file info.

	IException (ErrorType type, const std::string &message, const char *fileName, int lineNumber)
	This version of the constructor creates an IException instance with the given error type, message, and file info.

	IException (ErrorType type, const QString &message, const char *fileName, int lineNumber)
	This version of the constructor creates an IException instance with the given error type, message, and file info.

	IException (const IException &caughtException, ErrorType newExceptionType, const char message, const char fileName, int lineNumber)
	This version of the constructor creates an IException instance with the given error type, message, file info.

	IException (const IException &caughtException, ErrorType newExceptionType, const std::string &message, const char *fileName, int lineNumber)
	This version of the constructor creates an IException instance with the given error type, message, file info.

	IException (const IException &caughtException, ErrorType newExceptionType, const QString &message, const char *fileName, int lineNumber)
	This version of the constructor creates an IException instance with the given error type, message, file info.

	IException (const IException &other)
	The copy constructor creates a copy of the given exception.

	~IException () throw ()
	The destructor frees memory allocated for the message, filename, and list of previous exceptions.

const char *	what () const throw ()
	Returns a string representation of this exception in its current state.

void	append (const IException &exceptionSource)
	Appends the given exception (and its list of previous exceptions) to this exception's causational exception list.

ErrorType	errorType () const
	Returns the source of the error for this exception.

void	print () const
	Prints a string representation of this exception to stderr.

void	print (bool printFileInfo) const
	Prints a string representation of this exception to stderr, including file info if specified.

Pvl	toPvl () const
	Returns a PVL object representing the contents of this exception.

QString	toString () const
	Returns a string representation of this exception.

QString	toString (bool printFileInfo) const
	Returns a string representation of this exception, including file info if specified.

void	swap (IException &other)
	Swaps the values of this instance's member data with other.

IException &	operator= (const IException &rhs)
	Assign the values of rhs to this instance.

Static Public Member Functions
static QString	errorTypeToString (ErrorType t)
	Returns the source of the error in string format for the given ErrorType.

Private Member Functions
char *	buildWhat () const
	Returns a C string containing a string representation of this exception.

void	deleteEmptyMemberStrings ()
	This is a helper method for the constructors.

Static Private Member Functions
static IException	createStackTrace ()

static ErrorType	stringToErrorType (const QString &s)
	Given a string, returns the error type associated with it.

Private Attributes
char *	m_what
	This is used to store the return value of what() in a way that guarantees the returned data will not be deleted as long as this instance is unmodified.

ErrorType	m_errorType
	This exception's error source.

QString *	m_message
	The message associated with this exception.

QString *	m_fileName
	The source code file that threw this exception.

int	m_lineNumber
	The line in the source code file that threw this exception.

QList< IException > *	m_previousExceptions
	A list of exceptions that caused this exception.

Detailed Description

Isis exception class.

This class represents a general Isis exception. It contains an enumeration for what type of error the exception represents, and can optionally track what exceptions caused the current exception. This class also provides access to string and PVL representations of the exception.

Instances of this class should be thrown by value and caught be reference. Please see the constructor documentation for code examples on how to create and throw exceptions.

All methods in this class are re-entrant.

Author: ????-??-?? Jeff Anderson

History

2005-05-10 Leah Dahmer - Added class documentation

2005-12-28 Elizabeth Miller - Fixed bug in Pvl error output

2006-06-12 Tracie Sucharski - Change clear method to static

2006-11-02 Jeff Anderson - Fixed bug in Report method for exit status

2007-12-31 Steven Lambright - Added stack trace

2008-05-23 Steven Lambright - Added stack trace

2008-06-18 Stuart Sides - Fixed doc error

2008-07-08 Steven Lambright - Changed memory cleanup; now uses atexit

2008-10-30 Steven Lambright - iException::Message now takes a const char* for the filename, instead of a char*, issue pointed out by "novus0x2a" (Support Board Member)

2008-12-15 Steven Lambright - iException::what no longer returns deleted memory.

2009-07-29 Steven Lambright - Stack trace calculations moved to IsisDebug.h

2011-08-05 Steven Lambright - Hacked to make multi-threaded code which throws exceptions work.

2012-03-07 Jai Rideout and Steven Lambright - Completely refactored how this class works so that it no longer stores messages in static memory. This refactoring was necessary for the upcoming control network suite project to allow this class to work with multi-threading. The ErrorType enum was also shortened to include only four relevant error types, as the other error types were often misused, ambiguous, completely forgotten, and not helpful to users. The code was updated appropriately to follow the current Isis coding standards.

2012-03-13 Steven Lambright - toString() was giving "End" with an empty exception when using Format = Pvl. It should (and must) be an empty string. This is fixed – fixes #755.

2012-07-30 Jeff Anderson - Updated internal documentation to improve backward compatibility

2018-08-06 Kaitlyn Lee - With the new cmake system, we run unit tests from build/untiTest, while in the old make system, we ran unit tests directly from the object's directory. This change caused the c macro FILE to include the full path of unitTest.cpp when it expands. Consequently, we have to strip the path from FILE and put only the name of the file into FILEINFO.

Definition at line 91 of file IException.h.

Member Enumeration Documentation

◆ ErrorType

enum Isis::IException::ErrorType

Contains a set of exception error types.

These types indicate the source of the error. For example, if the error type is User, this indicates that the exception was thrown due to something the user did wrong, such as provide a cube with no SPICE data to an application that needed a spiceinit'd cube as input.

Enumerator
Unknown	A type of error that cannot be classified as any of the other error types. This should be the most common error type. If in doubt, always use this error type.
User	A type of error that could only have occurred due to a mistake on the user's part (e.g. bad input to the application). You must be able to guarantee that the user provided the input in the context that is throwing the error.
Programmer	This error is for when a programmer made an API call that was illegal. This includes: Making an API call with illegal input data that could and should have been checked before the call was made. For example, an out of array bounds exception is a programmer exception because the caller should have checked the size of the array. Making an API call that requires a certain class state. For example, you need to call open before read. These categories have a lot of overlap, but they are what you are looking for. A programmer exception is not appropriate if the caller has no way to validate their inputs to a method ahead of time, or if the caller is not expected to validate their inputs ahead of time.
Io	A type of error that occurred when performing an actual I/O operation. For example, fread/fwrite calls. This also includes files not existing, inter-processes socket communications, and network communications. This does not include a file not having the expected values inside of it (for example, reading a corrupted PVL).

Definition at line 111 of file IException.h.

Constructor & Destructor Documentation

◆ IException() [1/8]

Isis::IException::IException ( )

The default constructor creates an IException instance with no message, previous exceptions, or file info.

The exception error type is Unknown.

This default constructor exists so that IException instances can be stored in Qt containers such as lists. This is also used for cancelling a program run.

throw IException();

Isis::IException::IException

IException()

The default constructor creates an IException instance with no message, previous exceptions,...

Definition IException.cpp:38

Definition at line 38 of file IException.cpp.

References buildWhat(), m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, m_what, and Unknown.

◆ IException() [2/8]

Isis::IException::IException	(	ErrorType	type,
		const char *	message,
		const char *	fileName,
		int	lineNumber )

This version of the constructor creates an IException instance with the given error type, message, and file info.

The IException instance will not have any previous exceptions associated with it initially (i.e. no exception caused this one to be thrown).

throw IException(IException::Unknown,
                 "While doing an important process, we could not do ... "
                 "because the data [" ... "] is invalid",
                 _FILEINFO_);

Parameters

type	the source of the error that this exception represents
message	the string message containing details about the error, which may be displayed to the user
fileName	the filename of the file that this exception was thrown in
lineNumber	the line in the source code file that threw this exception

Definition at line 108 of file IException.cpp.

References buildWhat(), deleteEmptyMemberStrings(), m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, and m_what.

◆ IException() [3/8]

Isis::IException::IException	(	ErrorType	type,
		const std::string &	message,
		const char *	fileName,
		int	lineNumber )

This version of the constructor creates an IException instance with the given error type, message, and file info.

The IException instance will not have any previous exceptions associated with it initially (i.e. no exception caused this one to be thrown). The QString version of this constructor is preferred over this one.

std::string message = "While doing an important process, we could not do .. "
                  "because the data [" ... "] is invalid";
throw IException(IException::Unknown, message, _FILEINFO_);

Parameters

type	the source of the error that this exception represents
message	the string message containing details about the error, which may be displayed to the user
fileName	the filename of the file that this exception was thrown in
lineNumber	the line in the source code file that threw this exception

Definition at line 146 of file IException.cpp.

References buildWhat(), deleteEmptyMemberStrings(), m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, and m_what.

◆ IException() [4/8]

Isis::IException::IException	(	ErrorType	type,
		const QString &	message,
		const char *	fileName,
		int	lineNumber )

This version of the constructor creates an IException instance with the given error type, message, and file info.

The IException instance will not have any previous exceptions associated with it initially (i.e. no exception caused this one to be thrown).

throw IException(IException::Unknown,
                 tr("While doing an important process, we could not do ... "
                    "because the data [%1] is invalid").arg(...),
                 _FILEINFO_);

Parameters

type	the source of the error that this exception represents
message	the string message containing details about the error, which may be displayed to the user
fileName	the filename of the file that this exception was thrown in
lineNumber	the line in the source code file that threw this exception

Definition at line 70 of file IException.cpp.

References buildWhat(), deleteEmptyMemberStrings(), m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, and m_what.

◆ IException() [5/8]

Isis::IException::IException	(	const IException &	caughtException,
		ErrorType	type,
		const char *	message,
		const char *	fileName,
		int	lineNumber )

This version of the constructor creates an IException instance with the given error type, message, file info.

The IException instance will append the given exception to its list of previous exceptions (as well as any previous exceptions associated with the caught exception). Use this constructor when you want to rethrow a new exception after catching an exception and preserve the previous message(s).

try {
  ...
}
catch (IException &e) {
  throw IException(e,
                   IException::Unknown,
                   "While doing an important process, we could not do "
                   "... ",
                   _FILEINFO_);
}

Parameters

caughtException	the previous exception that caused this exception to be thrown
type	the source of the error that this exception represents
message	the string message containing details about the error, which may be displayed to the user
fileName	the filename of the file that this exception was thrown in
lineNumber	the line in the source code file that threw this exception

Definition at line 194 of file IException.cpp.

References append(), deleteEmptyMemberStrings(), m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, and m_what.

◆ IException() [6/8]

Isis::IException::IException	(	const IException &	caughtException,
		ErrorType	type,
		const std::string &	message,
		const char *	fileName,
		int	lineNumber )

This version of the constructor creates an IException instance with the given error type, message, file info.

The IException instance will append the given exception to its list of previous exceptions (as well as any previous exceptions associated with the caught exception). Use this constructor when you want to rethrow a new exception after catching an exception and preserve the previous message(s). The QString version of this constructor is preferred over this one.

try {
  ...
}
catch (IException &e) {
  string message = "While doing an important process, we could not do "
                    "... ";
  throw IException(e, IException::Unknown, message, _FILEINFO_);
}

Parameters

caughtException	the previous exception that caused this exception to be thrown
type	the source of the error that this exception represents
message	the string message containing details about the error, which may be displayed to the user
fileName	the filename of the file that this exception was thrown in
lineNumber	the line in the source code file that threw this exception

Definition at line 242 of file IException.cpp.

References append(), deleteEmptyMemberStrings(), m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, and m_what.

◆ IException() [7/8]

Isis::IException::IException	(	const IException &	caughtException,
		ErrorType	type,
		const QString &	message,
		const char *	fileName,
		int	lineNumber )

This version of the constructor creates an IException instance with the given error type, message, file info.

The IException instance will append the given exception to its list of previous exceptions (as well as any previous exceptions associated with the caught exception). Use this constructor when you want to rethrow a new exception after catching an exception and preserve the previous message(s).

try {
  ...
}
catch (IException &e) {
  QString message = "While doing an important process, we could not do "
                    "... ";
  throw IException(e, IException::Unknown, message, _FILEINFO_);
}

Parameters

caughtException	the previous exception that caused this exception to be thrown
type	the source of the error that this exception represents
message	the string message containing details about the error, which may be displayed to the user
fileName	the filename of the file that this exception was thrown in
lineNumber	the line in the source code file that threw this exception

Definition at line 289 of file IException.cpp.

References append(), deleteEmptyMemberStrings(), m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, and m_what.

◆ IException() [8/8]

Isis::IException::IException ( const IException & other )

The copy constructor creates a copy of the given exception.

Parameters

other the exception to copy from

Definition at line 313 of file IException.cpp.

References m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, and m_what.

◆ ~IException()

Isis::IException::~IException	(		)
throw	(	)

The destructor frees memory allocated for the message, filename, and list of previous exceptions.

Definition at line 347 of file IException.cpp.

References m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, m_what, and Unknown.

Member Function Documentation

◆ append()

void Isis::IException::append ( const IException & exceptionSource )

Appends the given exception (and its list of previous exceptions) to this exception's causational exception list.

The passed in exception is the cause of this exception. Exceptions should be appended in the original order that they were thrown - earlier first.

This method causes the results of what() to be rebuilt, invalidating any previous results.

try {
   ...
}
catch (IException &error1) {
  try {
    ...
  }
  catch (IException &error2) {
    IException finalError(IException::Unknown, "...", _FILEINFO_);
    finalError.append(error1);
    finalError.append(error2);
    throw finalError;
  }
}

Parameters

exceptionSource the exception that should be added to the list of previous exceptions

Definition at line 407 of file IException.cpp.

References buildWhat(), m_previousExceptions, and m_what.

Referenced by Isis::ProjectionFactory::CreateForCube(), Isis::ExportImagesWorkOrder::ProjectImageExportFunctor::errors(), Isis::ImportControlNetWorkOrder::CreateControlsFunctor::errors(), Isis::ImportImagesWorkOrder::OriginalFileToProjectCubeFunctor::errors(), Isis::ImportShapesWorkOrder::OriginalFileToProjectCubeFunctor::errors(), IException(), IException(), IException(), Isis::ProgramLauncher::ProcessIsisMessageFromChild(), Isis::ProjectionFactory::RingsCreateForCube(), Isis::ProjectionFactory::RingsCreateForCube(), and Isis::ProgramLauncher::RunIsisProgram().

◆ buildWhat()

char * Isis::IException::buildWhat ( ) const

private

Returns a C string containing a string representation of this exception.

This method should be called any time the current exception is modified (e.g. appending an exception to the previous exceptions list, etc.) in order to keep m_what synched with the current state of the exception.

Returns: a C string representation of this exception

Definition at line 724 of file IException.cpp.

References toString().

Referenced by append(), IException(), IException(), IException(), and IException().

◆ deleteEmptyMemberStrings()

void Isis::IException::deleteEmptyMemberStrings ( )

private

This is a helper method for the constructors.

When the message or source code file name are empty strings, we want our members to be NULL instead of empty IStrings.

Definition at line 740 of file IException.cpp.

References m_fileName, and m_message.

Referenced by IException(), IException(), IException(), IException(), IException(), and IException().

◆ errorType()

IException::ErrorType Isis::IException::errorType ( ) const

Returns the source of the error for this exception.

Returns: the source of the error (i.e. ErrorType)

Definition at line 428 of file IException.cpp.

References m_errorType.

◆ errorTypeToString()

QString Isis::IException::errorTypeToString ( ErrorType type )

static

Returns the source of the error in string format for the given ErrorType.

Parameters

type	the ErrorType enum to convert to a string

Returns: a string representation of the error type. For example, "USER ERROR" if the error type is User

Definition at line 672 of file IException.cpp.

References Io, Programmer, Unknown, and User.

Referenced by toPvl(), and toString().

◆ operator=()

IException & Isis::IException::operator= ( const IException & rhs )

Assign the values of rhs to this instance.

This is a deep copy and is exception-safe.

Parameters

rhs	the IException on the right-hand side of the equals operator

Returns: *this

Definition at line 657 of file IException.cpp.

References swap().

◆ print() [1/2]

void Isis::IException::print ( ) const

Prints a string representation of this exception to stderr.

File info (i.e. filename and line number) are only printed if the user has that option enabled in their preferences file. The printed exception will be either PVL-formatted or formatted as plain sentences according to the user's preferences file.

This should be the preferred method call in unit tests when testing exceptions thrown by your class.

Definition at line 443 of file IException.cpp.

References toString().

◆ print() [2/2]

void Isis::IException::print ( bool printFileInfo ) const

Prints a string representation of this exception to stderr, including file info if specified.

The printed exception will be either PVL-formatted or formatted as plain sentences according to the user's preferences file.

Parameters

printFileInfo whether or not to include file info in the printed version of this exception. This ignores the option set in the user's preferences file regarding file info.

Definition at line 459 of file IException.cpp.

References toString().

◆ stringToErrorType()

IException::ErrorType Isis::IException::stringToErrorType ( const QString & string )

staticprivate

Given a string, returns the error type associated with it.

Parameters

string the string to convert into the appropriate ErrorType

Returns: The ErrorType enum associated with the given string. For example, if the string reads "USER ERROR", will return type User.

Definition at line 701 of file IException.cpp.

References Io, Programmer, Unknown, and User.

◆ swap()

void Isis::IException::swap ( IException & other )

Swaps the values of this instance's member data with other.

This method is exception-safe.

Parameters

other the exception to swap member data with

Definition at line 640 of file IException.cpp.

References m_errorType, m_fileName, m_lineNumber, m_message, m_previousExceptions, and m_what.

Referenced by operator=().

◆ toPvl()

Pvl Isis::IException::toPvl ( ) const

Returns a PVL object representing the contents of this exception.

File info is included unless there is no filename or line number associated with an exception, regardless of the user's preferences file.

Returns: a PVL object representing this exception

Definition at line 473 of file IException.cpp.

References Isis::PvlObject::addGroup(), Isis::Pvl::append(), errorTypeToString(), m_previousExceptions, Isis::Application::Name(), Isis::toString(), and Unknown.

Referenced by toString().

◆ toString() [1/2]

QString Isis::IException::toString ( ) const

Returns a string representation of this exception.

File info (i.e. filename and line number) are only included if the user has that option enabled in their preferences file. The string representation of the exception will be either PVL-formatted or formatted as plain sentences according to the user's preferences file.

Returns: a string representation of this exception

Definition at line 535 of file IException.cpp.

References toString().

Referenced by buildWhat(), print(), print(), and toString().

◆ toString() [2/2]

QString Isis::IException::toString ( bool includeFileInfo ) const

Returns a string representation of this exception, including file info if specified.

The string representation of the exception will be either PVL-formatted or formatted as plain sentences according to the user's preferences file.

Parameters

includeFileInfo whether or not to include file info in the string representation of this exception. This ignores the option set in the user's preferences file regarding file info.

Returns: a string representation of this exception

Definition at line 562 of file IException.cpp.

References errorTypeToString(), Isis::PvlObject::groups(), m_previousExceptions, toPvl(), Isis::toString(), and Unknown.

◆ what()

const char * Isis::IException::what	(		)	const
throw	(	)

Returns a string representation of this exception in its current state.

The results of this method are guaranteed to be valid until the instance is modified.

Returns: a C string representation of this exception

Definition at line 373 of file IException.cpp.

References m_what.

Member Data Documentation

◆ m_errorType

ErrorType Isis::IException::m_errorType

private

This exception's error source.

If the source cannot be positively identified, then this should be set to Unknown.

Definition at line 219 of file IException.h.

Referenced by errorType(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), swap(), and ~IException().

◆ m_fileName

QString* Isis::IException::m_fileName

private

The source code file that threw this exception.

Definition at line 230 of file IException.h.

Referenced by deleteEmptyMemberStrings(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), swap(), and ~IException().

◆ m_lineNumber

int Isis::IException::m_lineNumber

private

The line in the source code file that threw this exception.

Definition at line 235 of file IException.h.

Referenced by IException(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), swap(), and ~IException().

◆ m_message

QString* Isis::IException::m_message

private

The message associated with this exception.

This will be NULL if the message is empty (or only contained whitespace).

Definition at line 225 of file IException.h.

Referenced by deleteEmptyMemberStrings(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), swap(), and ~IException().

◆ m_previousExceptions

QList<IException>* Isis::IException::m_previousExceptions

private

A list of exceptions that caused this exception.

Definition at line 240 of file IException.h.

Referenced by append(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), swap(), toPvl(), toString(), and ~IException().

◆ m_what

char* Isis::IException::m_what

private

This is used to store the return value of what() in a way that guarantees the returned data will not be deleted as long as this instance is unmodified.

Any changes to the current exception will reallocate this and invalidate old values of what().

Definition at line 213 of file IException.h.

Referenced by append(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), IException(), swap(), what(), and ~IException().

The documentation for this class was generated from the following files:

src/base/objs/IException/IException.h
src/base/objs/IException/IException.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ ErrorType

Constructor & Destructor Documentation

◆ IException() [1/8]

◆ IException() [2/8]

◆ IException() [3/8]

◆ IException() [4/8]

◆ IException() [5/8]

◆ IException() [6/8]

◆ IException() [7/8]

◆ IException() [8/8]

◆ ~IException()

Member Function Documentation

◆ append()

◆ buildWhat()

◆ deleteEmptyMemberStrings()

◆ errorType()

◆ errorTypeToString()

◆ operator=()

◆ print() [1/2]

◆ print() [2/2]

◆ stringToErrorType()

◆ swap()

◆ toPvl()

◆ toString() [1/2]

◆ toString() [2/2]

◆ what()

Member Data Documentation

◆ m_errorType

◆ m_fileName

◆ m_lineNumber

◆ m_message

◆ m_previousExceptions

◆ m_what