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.

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 ()
	Returns an IException representing the current stack, excluding this method.

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

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

Definition at line 99 of file IException.h.

Member Enumeration Documentation

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 119 of file IException.h.

Constructor & Destructor Documentation

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();

Definition at line 56 of file IException.cpp.

Referenced by createStackTrace().

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 126 of file IException.cpp.

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 164 of file IException.cpp.

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 88 of file IException.cpp.

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 212 of file IException.cpp.

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 260 of file IException.cpp.

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 307 of file IException.cpp.

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 331 of file IException.cpp.

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

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

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

Definition at line 365 of file IException.cpp.

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

Member Function Documentation

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 425 of file IException.cpp.

References buildWhat(), m_previousExceptions, and m_what.

Referenced by Isis::ProjectionFactory::CreateForCube(), Isis::ExportImagesWorkOrder::ProjectImageExportFunctor::errors(), Isis::ImagePolygon::initCube(), Isis::IssNACamera::IssNACamera(), Isis::Chip::Load(), Isis::ProgramLauncher::ProcessIsisMessageFromChild(), Isis::ProjectionFactory::RingsCreateForCube(), Isis::ProgramLauncher::RunIsisProgram(), and Isis::UniversalGroundMap::UniversalGroundMap().

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 766 of file IException.cpp.

References toString().

Referenced by append().

IException Isis::IException::createStackTrace ( )

staticprivate

Returns an IException representing the current stack, excluding this method.

Returns: an IException representing a current stack trace

Definition at line 689 of file IException.cpp.

References IException(), and Unknown.

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 782 of file IException.cpp.

References m_fileName, and m_message.

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 446 of file IException.cpp.

References m_errorType.

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

staticprivate

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 714 of file IException.cpp.

References Io, Programmer, Unknown, and User.

Referenced by toPvl(), and toString().

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 675 of file IException.cpp.

References swap().

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 461 of file IException.cpp.

References toString().

Referenced by Isis::Application::Application(), Isis::ImagePolygon::Create(), Isis::Image::createFootprint(), Isis::MosaicSceneItem::drawImage(), Isis::CissLabels::Init(), Isis::ImageReader::VariantToImageFunctor::operator()(), Isis::MosaicSceneWidget::reprojectItems(), Isis::Pipeline::Run(), and Isis::VoyagerCamera::VoyagerCamera().

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 477 of file IException.cpp.

References toString().

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 743 of file IException.cpp.

References Io, Programmer, Unknown, and User.

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 658 of file IException.cpp.

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

Referenced by operator=().

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 491 of file IException.cpp.

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

Referenced by Isis::Application::FunctionError(), and toString().

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 553 of file IException.cpp.

References Isis::PvlContainer::hasKeyword().

Referenced by Isis::Gruen::algorithm(), Isis::ExportControlNetWorkOrder::asyncRedo(), Isis::ExportImagesWorkOrder::asyncRedo(), buildWhat(), Isis::ControlPointEdit::ControlPointEdit(), Isis::Gruen::errorAnalysis(), Isis::Application::FunctionError(), Isis::ChipViewport::geomChip(), Isis::Application::GuiReportError(), Isis::ImportImagesWorkOrder::importConfirmedImages(), Isis::ProjectionConfigDialog::loadFromFile(), Isis::MosaicControlNetTool::loadNetwork(), Isis::StereoTool::measureSaved(), Isis::MatchTool::mouseButtonRelease(), Isis::QnetTool::mouseButtonRelease(), Isis::ChipViewport::nogeomChip(), Isis::QnetFileTool::open(), Isis::QnetTool::openGround(), print(), Isis::ControlPointEdit::registerPoint(), Isis::ChipViewport::reloadChip(), Isis::ChipViewport::rotateChip(), Isis::QnetFileTool::saveAs(), Isis::ControlPointEdit::saveMeasure(), Isis::PvlEditDialog::saveTextEdit(), Isis::MatchTool::selectLeftMeasure(), Isis::MatchTool::selectRightMeasure(), Isis::QnetSetAprioriDialog::setApriori(), Isis::StereoTool::setFiles(), Isis::ControlPointEdit::setGeom(), Isis::ControlPointEdit::setRightMeasure(), Isis::ZoomTool::setScale(), Isis::ControlPointEdit::setTemplateFile(), Isis::Gui::StartProcess(), Isis::ControlPointEdit::updateRightGeom(), Isis::StereoTool::viewTemplateFile(), Isis::MatchTool::viewTemplateFile(), Isis::QnetTool::viewTemplateFile(), Isis::MatchTool::writeTemplateFile(), and Isis::QnetTool::writeTemplateFile().

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 580 of file IException.cpp.

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

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 391 of file IException.cpp.

References m_what.

Referenced by Isis::ImagePolygon::Fix360Poly(), Isis::ImageOverlapSet::HandleError(), Isis::QIsisApplication::notify(), Isis::ProjectionConfigDialog::refreshWidgetStates(), Isis::MatchTool::saveAsNet(), Isis::MatchTool::saveNet(), and Isis::PolygonTools::SplitPolygonOn360().

Member Data Documentation

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 227 of file IException.h.

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

QString* Isis::IException::m_fileName

private

The source code file that threw this exception.

Definition at line 238 of file IException.h.

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

int Isis::IException::m_lineNumber

private

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

Definition at line 243 of file IException.h.

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

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 233 of file IException.h.

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

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

private

A list of exceptions that caused this exception.

Definition at line 248 of file IException.h.

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

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 221 of file IException.h.

Referenced by append(), 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

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation