au.gov.aao.drama
Class DramaException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          au.gov.aao.drama.DramaException

All Implemented Interfaces:

Serializable

public class DramaException
extends Exception

Objects of this class are thrown when exceptions occur in DRAMA software. The underlying C DRAMA software uses integer status codes throughout, but this is not appropiate for JAVA.

This class allows DRAMA status codes to be incorporated into a the DRAMA Java interface. It also provides some integration with the DRAMA Ers module..

Application code can use methods of this class to examine the underlying DRAMA Status (Using the DramaStatus or DramaStatusInt methods) and hence determine how to respond to an exception.

A number of static methods are provided which help in the interaction of DRAMA with Java. Two static methods - Report(Throwable) and Report(String) allow DRAMA ERS reports to be made. The former allows a JAVA Throwable to be reported to DRAMA, say as part of an action reporting a JAVA Exception. The later allows a string to be reported, without any chance of an Exception being thrown, as might happen if DramaErs.Report() was used. Similary, for Flush() against DramaErs.Flush().

Version:

@(#) $Id: ACMM:DramaJava/DramaException.java,v 3.52 17-Sep-2009 14:08:21+10 tjf $

Author:

Tony Farrell

See Also:

DramaStatus, DramaTask, Serialized Form

Field Summary

static String

RCSID The RCS (ACMM) ID.

Constructor Summary

DramaException(String detailString, DramaStatus status)
Creates a DRAMA Exception object, with the assocaited DRAMA status passed using a DramaStatus object.

DramaException(String detailString, int status)
Creates a DRAMA Exception object, with the assocaited DRAMA status passed as an integer.

Method Summary

DramaStatus	DramaStatus() Return the DRAMA status code associated with an exception.
protected int	DramaStatusInt() Return the DRAMA status code associated with an exception.
static void	Flush() Flush ERS messages without return status to JAVA.
static void	Report(String s) Report a string using ERS.
static void	Report(Throwable e) Report a Java Throwable using ERS.
String	toString() Returns a string representation of a DRAMA Exception.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

RCSID

public static final String RCSID

The RCS (ACMM) ID. This field returns the source code archive ID of this class's source file.

The returned string corresponds to the version string seen above (in the class description comments), but will contain the version details of the compiled class file's actual source file.

(ACMM is the source code archive system used by the AAO. If the string returned by RCSID does not contain the string ACMM, then it is likely the source code has been archived again outside the AAO).

See Also:

Constant Field Values

Constructor Detail

DramaException

public DramaException(String detailString,
                      int status)

Creates a DRAMA Exception object, with the assocaited DRAMA status passed as an integer.

Parameters:

detailString - A string giving context for the error.

status - The DRAMA Status code for the error. If this exception is ever converted back to a DRAMA error report, this code can be fetched and associated with the DRAMA error report.

DramaException

public DramaException(String detailString,
                      DramaStatus status)

Creates a DRAMA Exception object, with the assocaited DRAMA status passed using a DramaStatus object.

Parameters:

detailString - A string giving context for the error.

status - The DRAMA Status code for the error. If this exception is ever converted back to a DRAMA error report, this code can be fetched and associated with the DRAMA error report.

Method Detail

DramaStatus

public DramaStatus DramaStatus()

Return the DRAMA status code associated with an exception.

Returns:

The Drama Status associated with the exception.

DramaStatusInt

protected int DramaStatusInt()

Return the DRAMA status code associated with an exception. This version is used by the C++ routine DramaCheckAndCvt(). It is not intended to be used from Java, but must be protected rather then private to ensure the native code can access it.

Returns:

The Drama Status associated with the exception as an integer.

toString

public String toString()

Returns a string representation of a DRAMA Exception.

Overrides:

toString in class Throwable

Returns:

The exception details as a string.

Report

public static void Report(String s)

Report a string using ERS.

This method reports a string using the DRAMA ERS package, allowing details to be forwarded to other tasks.

Note, as it is a static method, is should be possible to call it for any string.

This method should only be used in cases where you are handling exceptions and don't want to have to handle excpetions whilst sending Ers reports. Otherwise, use DramaErs.Report(). This method will not correctly handle reporting failures from ERS, because otherwise it would have to throw exceptions. But this is unlikely to happen and if it does, it will be reported to stderr.

Parameters:

s - The string to be reported.

Report

public static void Report(Throwable e)

Report a Java Throwable using ERS.

This method reports a Java Throwable using the DRAMA ERS package, allowing details to be forwarded to other tasks.

Note, as it is a static method, is should be possible to call it for any throwable, not just a DramaException type. The only requirement is that it's toString() method returns the appropiate string.

Parameters:

e - The throwable to be reported.

Flush

public static void Flush()

Flush ERS messages without return status to JAVA.

This is intended to be used in exception handlers which have invoked DramaException.Report(). It allows the reported message to be flushed immediately.

The diffeerence between this method and the DramaErs.Flush() method is that the later may itself report an exception whilst this method won't - although it may report an error to stderr.