Isis::IException Class Reference

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.

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

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).

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

References 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

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

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

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

References append().

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

References append().

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

References append().

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

~IException()

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

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

References 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

Referenced by Isis::ProjectionFactory::CreateForCube(), IException(), IException(), IException(), Isis::ProjectionFactory::RingsCreateForCube(), Isis::ProjectionFactory::RingsCreateForCube(), and Isis::ProgramLauncher::RunIsisProgram().

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)

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

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

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.

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.

References toString().

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

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

References Isis::PvlObject::addGroup(), Isis::Pvl::append(), errorTypeToString(), 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

References Isis::Preference::Preferences(), and toString().

Referenced by 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

References errorTypeToString(), Isis::PvlObject::groups(), Isis::Preference::Preferences(), 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

---

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

• /Users/chkim/repos/ISIS3/isis/src/base/objs/IException/IException.h
• /Users/chkim/repos/ISIS3/isis/src/base/objs/IException/IException.cpp