au.gov.aao.drama
Class DramaSem

java.lang.Object
  au.gov.aao.drama.DramaSem

public class DramaSem
extends Object

A multiple entry semaphore which is used to protect DRAMA's internal structures from multithread access from JAVA.

This class is used internally by DJAVA and should be used by any class which uses native language DRAMA functions which may be invoked when not within a DRAMA message handler. It should also be used in any case where it is necessary to ensure the DRAMA message processing functions do not run until a sequence is complete (such as a sequence of method invocations from a GUI event which rely on the DRAMA internal context remaining consistent).

The intention of this semaphore is that a single thread should be able to take a semaphore multiple times, as long as it releases it the same number of times.

A static object is used and only static methods are available.

Before calling any native language function which may invoke a DRAMA function, you should invoke DramaSem.Take(). Then after return from the native language function, you must then invoke DramaSem.Release().

A failure to use the semaphore around DRAMA calls may case errors (hopefully) or corruption in the DRAMA task (possibly at random). Failure to release the semaphore after taking it will probably cause a deadlock which can only be broken by killing the program, through there is a default timeout of 30 seconds, which can be set by the application.

When a timeout occurs a SemTimeout (unchecked) exception is thrown. If the thread is interrupted whilst waiting, a SemInterrupt (unchecked) exception is thrown.

You should use a try block "finally" clause to ensure the semaphore is always released, even when an exception occurs. E.g.

 DramaSem.Take();
 try {
     // Code which requires semaphore
     ...
 }
 finally {
    DramaSem.Release();
 }
 

Code that is presuming that the caller has taken the semaphore can check this using the CheckWeHaveIt method. The HaveIt and ItTaken() methods can also be used to inquire about the semaphore status.

Version:

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

Author:

Tony Farrell

See Also:

DramaTask

Nested Class Summary

class	DramaSem.SemInterrupt A class thrown when an interrupt occurs whist waiting for the DRAMA Semaphore.
class	DramaSem.SemTimeout A class thrown when an timeout occurs whist waiting for the DRAMA Semaphore.

Field Summary

static String

RCSID The RCS (ACMM) ID.

Method Summary

static void	CheckWeHaveIt() Throw an exception if the current thread does not have the DRAMA semaphore.
static boolean	HaveIt() Returns true if the DRAMA semaphore is currently taken by this thread.
static boolean	IsTaken() Returns true if the Drama Semaphore has been taken.
static void	Release() Release the DRAMA Semaphore.
static void	SetTimeout(long theTimeout) Set the DRAMA Semaphore timeout.
static void	Take() Take the DRAMA Semaphore or wait until we can get it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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

Method Detail

SetTimeout

public static void SetTimeout(long theTimeout)

Set the DRAMA Semaphore timeout.

To help handle dead-locks, the DRAMA semaphore has a timeout, which defaults to 30 seconds. This method allows this timeout to be changed by the application. If an application times out waiting for the DRAMA semaphore, then the SemTimeout (unchecked) exception is thrown.

Parameters:

theTimeout - The timeout in seconds. A value less then or equal to zero disabled the timeout.

Take

public static void Take()

Take the DRAMA Semaphore or wait until we can get it.

Release

public static void Release()

Release the DRAMA Semaphore.

IsTaken

public static boolean IsTaken()

Returns true if the Drama Semaphore has been taken.

Please note that this method returns the status when it does the check, but if the semahpore status changed after it left the synchronized method, then the return value is incorrect. This method is just provided for debugging assistance and should not be relied upon unless the semaphore has been taken by this thread.

HaveIt

public static boolean HaveIt()

Returns true if the DRAMA semaphore is currently taken by this thread.

CheckWeHaveIt

public static void CheckWeHaveIt()
                          throws DramaException

Throw an exception if the current thread does not have the DRAMA semaphore.

Throws:

DramaException - Thrown if we don't have the semaphore, with DRAMA status code DJAVA__NOSEM.