alma::acs::exceptions::AcsJException Class Reference

Inheritance diagram for alma::acs::exceptions::AcsJException:

Collaboration diagram for alma::acs::exceptions::AcsJException:

Public Member Functions
	AcsJException ()
	AcsJException (String message)
	AcsJException (String message, Throwable cause)
	AcsJException (ErrorTrace etCause)
	AcsJException (String message, ErrorTrace etCause)
String	toString ()
String	getShortDescription ()
abstract UserException	toCorbaException ()
void	setSeverity ()
Severity	getSeverity ()
Object	setProperty (String key, String value)
String	getProperty (String key)
NameValue[]	getNameValueArray ()
long	getTimestampMillis ()
ErrorTrace	getErrorTrace ()
ACSException	getACSException ()
void	log (Logger logger)
int	getTraceDepth ()
String	getFile ()
String	getHost ()
int	getLine ()
String	getMethod ()
String	getProcess ()
String	getThreadName ()
String	getSourceObject ()
Static Public Member Functions
static void	setProcessName (String name)
static ErrorTrace	createSingleErrorTrace (Throwable thr, long defaultTimeMilli)
Protected Member Functions
abstract int	getErrorType ()
abstract int	getErrorCode ()
Protected Attributes
String	m_host
String	m_process
int	m_line
String	m_method
String	m_file
String	m_sourceObject
String	m_threadName
Severity	m_severity
Properties	m_properties
long	m_timeMilli
Package Functions
LogRecord	createSingleErrorTraceLogRecord (ErrorTrace et, String stackID, int stackLevel)
Private Member Functions
void	init ()
ErrorTrace	createSingleErrorTrace ()
Static Private Member Functions
static ErrorTrace	recursiveGetErrorTrace (Throwable thr, long defaultTimeMilli)
static void	addExceptionProperties (Throwable thr, ErrorTrace et)
Private Attributes
boolean	m_initialized = false
Static Private Attributes
static String	s_thisHost
static String	s_thisProcess

Detailed Description

Base class for any checked exceptions defined in ALMA Java code. Allows these Java exceptions to be interoperable with the ACS error system, i.e. that they can be converted to and from ErrorTrace or ACSException objects. See AcsJException(ErrorTrace), getErrorTrace, getACSException.

Not to be confused with alma.ACSErr.ACSException, which is a CORBA user exception with an alma.ACSErr.ErrorTrace inside. ACSException is declared as final, so that it's not an option to make our AcsJException a subclass of it. (todo check if that's due to OMG spec or JacORB).

For the conversion to and from the CORBA exception types, two ErrorTrace properties (i.e. NameValue objects referenced from ErrorTrace#data) are added:

javaex.class to store the exception class for later reconstruction
javaex.msg to store the message text provided in the various constructors of Throwable and subclasses.
TODO check why there is no such field available already in ErrorTrace, is there really no unique way of transporting text messages in addition to error types and codes??

Author:: hsommer Jun 18, 2003 1:07:38 PM

Constructor & Destructor Documentation

alma::acs::exceptions::AcsJException::AcsJException ( ) [inline]

References init().

alma::acs::exceptions::AcsJException::AcsJException ( String message ) [inline]

References init().

alma::acs::exceptions::AcsJException::AcsJException	(	String	message,
		Throwable	cause
	)			`[inline]`

Constructor from another exception, with a message.

If cause is a CORBA exception generated by the ACS error system, then its ErrorTrace is automatically converted to a chain of AcsJ-style exceptions.

Parameters:

cause

the causing exception

See also:: CorbaExceptionConverter::convertHiddenErrorTrace(Throwable)

References init().

alma::acs::exceptions::AcsJException::AcsJException ( ErrorTrace etCause ) [inline]

Constructor from another exception.

If cause is a CORBA exception generated by the ACS error system, then its ErrorTrace is automatically converted to a chain of AcsJ-style exceptions.

Parameters:

cause

the causing exception

See also:: CorbaExceptionConverter::convertHiddenErrorTrace(Throwable)

References init().

alma::acs::exceptions::AcsJException::AcsJException	(	String	message,
		ErrorTrace	etCause
	)			`[inline]`

Creates a new exception, with the chain of causing exceptions derived from etCause.

Parameters:

	message
	etCause

References init().

Member Function Documentation

static void alma::acs::exceptions::AcsJException::addExceptionProperties	(	Throwable	thr,
		ErrorTrace	et
	)			`[inline, static, private]`

Referenced by createSingleErrorTrace().

static ErrorTrace alma::acs::exceptions::AcsJException::createSingleErrorTrace	(	Throwable	thr,
		long	defaultTimeMilli
	)			`[inline, static]`

Converts a Throwable that may not be an AcsJException to an ErrorTrace.

For example, thr could be a NullPointerException thrown in the same process and thus not yet converted to DefaultAcsJException, but wrapped by some subclass of AcsJException which contains the NPE as its cause.

Parameters:

defaultTimeMilli

Java-time (1970-based) used to estimate a time stamp if none is available, in order to avoid something from October 1582 in the new ErrorTrace. Typically the timestamp from the wrapping AcsJException.

See also:: createSingleErrorTrace()

ErrorTrace alma::acs::exceptions::AcsJException::createSingleErrorTrace ( ) [inline, private]

Creates an ErrorTrace object that represents this exception. Linked exceptions are not considered, so the returned ErrorTrace.previousError is left as null.

Referenced by log(), and recursiveGetErrorTrace().

LogRecord alma::acs::exceptions::AcsJException::createSingleErrorTraceLogRecord	(	ErrorTrace	et,
		String	stackID,
		int	stackLevel
	)			`[inline, package]`

Creates a LogRecord with the data from the given ErrorTrace object. Some data such as thread name, line of code, user-defined properties etc which do not correspond to any field of LogRecord are stored inside a Map that is set as a parameter of the LogRecord. Later when the ACS logging system will process this LogRecord, it will recognize the special data and turn them into the XML attributes of elements like <Debug>

Parameters:

	et	the ErrorTrace input object
	stackID	the stackID that must be the same for all linked `ErrorTrace` objects.
	stackLevel	0-based index for LogRecords from an ErrorTrace chain.

Returns:: the LogRecord that contains the data from the input parameters.

References alma::ACSErr::ErrorTrace::errorCode, alma::ACSErr::ErrorTrace::errorType, alma::ACSErr::ErrorTrace::file, alma::ACSErr::ErrorTrace::host, alma::ACSErr::ErrorTrace::lineNum, alma::ACSErr::ErrorTrace::routine, alma::ACSErr::ErrorTrace::severity, alma::ACSErr::ErrorTrace::shortDescription, alma::ACSErr::ErrorTrace::sourceObject, alma::ACSErr::ErrorTrace::thread, and alma::ACSErr::ErrorTrace::timeStamp.

Referenced by log().

ACSException alma::acs::exceptions::AcsJException::getACSException ( ) [inline]

Creates an ACSException. Typically to be called from a top-level catch block that must convert any of the Java exceptions used internally by the Java program to an IDL type exception that can be thrown on over CORBA.

Returns:: ACSException

Deprecated:: ACSException should no longer be used since the new error framework generates type-safe corba exceptions with an ErrorTrace inside.

References getErrorTrace().

Referenced by alma::demo::LampCallbackImpl::LampCallbackImpl::acsExceptionMethodVoid(), and alma::acs::exceptions::DefaultAcsJException::toCorbaException().

abstract int alma::acs::exceptions::AcsJException::getErrorCode ( ) [protected, pure virtual]

Forces a subclass to choose an ACS error code.

Returns:: the error code

Referenced by createSingleErrorTrace(), and alma::acs::exceptions::AcsJCompletion::init().

ErrorTrace alma::acs::exceptions::AcsJException::getErrorTrace ( ) [inline]

Converts this exception (and all "caused-by" throwables it might have) to an ErrorTrace that links to its caused-by ErrorTrace objects.

To be used whenever the Corba wall is hit and the Java exception must be converted to an ACS-Corba-exception.

References m_initialized, m_timeMilli, and recursiveGetErrorTrace().

abstract int alma::acs::exceptions::AcsJException::getErrorType ( ) [protected, pure virtual]

Forces a subclass to choose an ACS error type.

Returns:: the error type

Implemented in alma::acs::callbacks::Objects::MyAcsJException, alma::acs::exceptions::DefaultAcsJException, alma::ACSBulkDataError::wrappers::AcsJACSBulkDataErrorEx, alma::ACSBulkDataStatus::wrappers::AcsJACSBulkDataStatusEx, alma::acsdaemonErrType::wrappers::AcsJacsdaemonErrTypeEx, alma::ACSErrTICS::wrappers::AcsJACSErrTICSEx, alma::ACSErrTicsTCorr::wrappers::AcsJACSErrTicsTCorrEx, alma::acsErrTypeAlarmSourceFactory::wrappers::AcsJacsErrTypeAlarmSourceFactoryEx, alma::ACSErrTypeCommon::wrappers::AcsJACSErrTypeCommonEx, alma::acsErrTypeComponent::wrappers::AcsJacsErrTypeComponentEx, alma::acsErrTypeContainerServices::wrappers::AcsJacsErrTypeContainerServicesEx, alma::ACSErrTypeCORBA::wrappers::AcsJACSErrTypeCORBAEx, alma::ACSErrTypeCppNative::wrappers::AcsJACSErrTypeCppNativeEx, alma::ACSErrTypeDevIO::wrappers::AcsJACSErrTypeDevIOEx, alma::ACSErrTypeJavaNative::wrappers::AcsJACSErrTypeJavaNativeEx, alma::acsErrTypeLifeCycle::wrappers::AcsJacsErrTypeLifeCycleEx, alma::ACSErrTypeMonitor::wrappers::AcsJACSErrTypeMonitorEx, alma::ACSErrTypePythonNative::wrappers::AcsJACSErrTypePythonNativeEx, alma::acsncErrType::wrappers::AcsJacsncErrTypeEx, alma::acsQoSErrType::wrappers::AcsJacsQoSErrTypeEx, alma::ACSTimeError::wrappers::AcsJACSTimeErrorEx, alma::ArchiveIdentifierError::wrappers::AcsJArchiveIdentifierErrorEx, alma::baciErrTypeDevIO::wrappers::AcsJbaciErrTypeDevIOEx, alma::baciErrTypeProperty::wrappers::AcsJbaciErrTypePropertyEx, alma::cdbErrType::wrappers::AcsJcdbErrTypeEx, alma::ErrorSystemExample::wrappers::AcsJErrorSystemExampleEx, alma::JavaContainerError::wrappers::AcsJJavaContainerErrorEx, alma::JContExmplErrTypeTest::wrappers::AcsJJContExmplErrTypeTestEx, alma::jmanagerErrType::wrappers::AcsJjmanagerErrTypeEx, alma::maciErrType::wrappers::AcsJmaciErrTypeEx, and alma::taskErrType::wrappers::AcsJtaskErrTypeEx.

Referenced by createSingleErrorTrace(), and alma::acs::exceptions::AcsJCompletion::init().

String alma::acs::exceptions::AcsJException::getFile ( ) [inline]

Returns:: Returns the m_file.

References m_file.

Referenced by alma::acs::exceptions::AcsJExceptionTest::checkWrapperAcsJEx().

String alma::acs::exceptions::AcsJException::getHost ( ) [inline]

Returns:: Returns the m_host.

References m_host.

Referenced by alma::acs::exceptions::AcsJExceptionTest::checkWrapperAcsJEx().

int alma::acs::exceptions::AcsJException::getLine ( ) [inline]

Returns:: Returns the m_line.

References m_line.

Referenced by alma::acs::exceptions::AcsJExceptionTest::checkWrapperAcsJEx().

String alma::acs::exceptions::AcsJException::getMethod ( ) [inline]

Returns:: Returns the m_method.

References m_method.

Referenced by alma::acs::exceptions::AcsJExceptionTest::checkWrapperAcsJEx().

NameValue [] alma::acs::exceptions::AcsJException::getNameValueArray ( ) [inline]

To be used by getErrorTrace() or whoever else cares about a NameValue[].

References m_properties.

Referenced by createSingleErrorTrace().

String alma::acs::exceptions::AcsJException::getProcess ( ) [inline]

Returns:: Returns the m_process.

References m_process.

String alma::acs::exceptions::AcsJException::getProperty ( String key ) [inline]

See also:: setProperty

References m_properties.

Severity alma::acs::exceptions::AcsJException::getSeverity ( ) [inline]

Returns the Severity level currently associated with this exception instance.

Returns:: Severity

References m_severity.

Referenced by alma::acs::exceptions::AcsJExceptionTest::checkWrapperAcsJEx(), and createSingleErrorTrace().

String alma::acs::exceptions::AcsJException::getShortDescription ( ) [inline]

Returns the short description which is a hardcoded text particular for a (type, code) combination. The subclass that represents the exception code will have to override this method. This method is not abstract because the exception class that corresponds to an error type (but not an error code) would otherwise have to overload it with returning an empty string.

Returns:: an empty string, unless overloaded for an error code.

Referenced by createSingleErrorTrace().

String alma::acs::exceptions::AcsJException::getSourceObject ( ) [inline]

Returns:: Returns the m_sourceObject.

References m_sourceObject.

String alma::acs::exceptions::AcsJException::getThreadName ( ) [inline]

Returns:: Returns the m_threadName.

References m_threadName.

Referenced by alma::acs::exceptions::AcsJExceptionTest::checkWrapperAcsJEx().

long alma::acs::exceptions::AcsJException::getTimestampMillis ( ) [inline]

Gets the timestamp when this exception was created.

Returns:: timestamp in milliseconds (Java-UTC time, 1970)

References m_timeMilli.

Referenced by alma::acs::exceptions::AcsJExceptionTest::checkWrapperAcsJEx(), and alma::acs::exceptions::AcsJCompletion::init().

int alma::acs::exceptions::AcsJException::getTraceDepth ( ) [inline]

Gets the total number of linked ("caused-by") exceptions including this one.

Not to be confused with the length of Throwable#getStackTrace(), which refers to the call stack for the current exception, and not to linked causing exception.

Referenced by alma::acs::exceptions::AcsJExceptionTest::checkWrapperAcsJEx(), log(), and alma::acs::exceptions::AcsJExceptionTest::testErrorTraceToAcsJExConversion().

void alma::acs::exceptions::AcsJException::init ( ) [inline, private]

Initializes both static (if null) and non-static member variables. Only to be called once by all of the ctors.

todo: for caused-by exceptions that are constructed from their ErrorTrace representation, this method does not really need to be called; perhaps a new package-private ctor should be added which does not call init()

References m_file, m_host, m_initialized, m_line, m_method, m_process, m_properties, m_sourceObject, m_threadName, m_timeMilli, s_thisHost, s_thisProcess, and setSeverity().

Referenced by AcsJException().

void alma::acs::exceptions::AcsJException::log ( Logger logger ) [inline]

Logs this exception and all causing exceptions. For each such exception, a separate log entry is created, in accordance with the ACS error logging specification.

Parameters:

logger

the JDK logger to be used for logging this exception.

References createSingleErrorTrace(), createSingleErrorTraceLogRecord(), getTraceDepth(), and m_timeMilli.

Referenced by com::cosylab::cdb::jdal::WDALImpl::add_node(), alma::demo::XmlComponentImpl::XmlComponentImpl::exceptionMethod(), com::cosylab::cdb::DALRead::main(), com::cosylab::cdb::CDBChangeDeployment::main(), alma::nctest::EventSupplierSpr2005067Impl::EventSupplierSpr2005067Impl::sendEvents(), alma::acsexmpl::clients::ErrorComponentTest::testBadMethod(), alma::acsexmpl::clients::ErrorComponentTest::testCompletionFromCompletion(), alma::acsexmpl::clients::ErrorComponentTest::testCompletionFromException(), alma::demo::client::XmlComponentClient::testException(), alma::acsexmpl::clients::ErrorComponentTest::testOutCompletion(), and alma::acsexmpl::clients::ErrorComponentTest::testReceiveCorbaSystemException().

static ErrorTrace alma::acs::exceptions::AcsJException::recursiveGetErrorTrace	(	Throwable	thr,
		long	defaultTimeMilli
	)			`[inline, static, private]`

Translates a Throwable to an ErrorTrace.

If thr is a subclass of AcsJException, then the various data fields of the ErrorTrace object are properly filled. Otherwise defaults are used.

If thr has other Throwables chained up (see Throwable#getCause) then these will also be translated, and the resulting ErrorTrace objects will be linked together.

Parameters:

thr

Returns:: ErrorTrace

References createSingleErrorTrace(), and alma::ACSErr::ErrorTrace::previousError.

Referenced by getErrorTrace().

static void alma::acs::exceptions::AcsJException::setProcessName ( String name ) [inline, static]

If we have some better name than "java", for example the unique name of the java container.

Parameters:

name

References s_thisProcess.

Object alma::acs::exceptions::AcsJException::setProperty	(	String	key,
		String	value
	)			`[inline]`

Allows extra information to be attached to the exception.

Returns:: the previous value of the specified key in this property list, or null if it did not have one.

References m_properties.

void alma::acs::exceptions::AcsJException::setSeverity ( ) [inline]

Sets the default severity level to Severity#Error. May be overridden by a subclass to set the default severity for that exception, or may be called from application code to set it for a specific exception instance.

References alma::ACSErr::Severity::Error, and m_severity.

Referenced by init().

abstract UserException alma::acs::exceptions::AcsJException::toCorbaException ( ) [pure virtual]

Creates a CORBA UserException from this exception.

Subclasses must return their associated UserException with an ErrorTrace member.

By convention, subclasses must also implement another method that returns the correct subtype of UserException. No problem with a code generator of course...