DJAVA

au.gov.aao.drama
Class DramaException

java.lang.Object
  extended by java.lang.Throwable
      extended by java.lang.Exception
          extended by 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.


DJAVA

Click here for the DRAMA home page and here for the AAO home page.

For more information, contact tjf@aaoepp.aao.gov.au.