|
DJAVA | |||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||
See:
Description
| Interface Summary | |
|---|---|
| Arg.StructList | This inteface is used by the
Arg.List() method to print a
single line when listing an SDS structure. |
| DramaPath.DisconnectHandler | This interface is to be used by objects which are specified
with with
DramaPath.SetDisconnect. |
| DramaTask.Action | This interface is be used by objects which implement DRAMA Obey message handlers. |
| DramaTask.ErsHandler | An inteface to be implemented by objects which output ERS messages. |
| DramaTask.KickableAction | This interface is be used by objects which implement DRAMA Obey message handlers. |
| DramaTask.KickHandler | This interface is be used by objects which implement DRAMA Kick message handlers. |
| DramaTask.MsgHandler | An inteface to be implemented by objects which output MsgOut messages. |
| Class Summary | |
|---|---|
| Arg | This class implements an interface to the AAO's
|
| DramaErs | The DramaErs class is used to access the DRAMA ERS library. |
| DramaMonitor | This class implements parameter monitoring in a
|
| DramaMonitor.MonResponse | Used to handle DramaMonitor responses. |
| DramaPath | This class implements an interface to sending
|
| DramaPath.Buffers | A helper class for defining buffer sizes for use with DramaPath objects. |
| DramaPath.RescheduleHandler | A class which handles rescheduling of a DRAMA Action using the DramaPath class to messages to other DRAMA tasks. |
| DramaPath.ResponseHandler | A class which handles responding to DRAMA messages initiated using a DramaPath object. |
| DramaSem | A multiple entry semaphore which is used to protect DRAMA's internal structures from multithread access from JAVA. |
| DramaStatus | The DramaStatus class is used to access DRAMA status codes. |
| DramaTask | This class implements an AAO
|
| DramaTask.ErsMessage | A Class used to represent a DRAMA ERS message report. |
| DramaTask.TaskInfo | A class used with the DramaTask.Tasks() function, to return the details of currently known DRAMA tasks. |
| Sdp | This class implements an interface to the
|
| Sdp.Sds | This class is used to access the value Sdp parameter using SdsID and Arg class methods. |
| SdsID | This class implements an interface to the AAO's
|
| Exception Summary | |
|---|---|
| DramaException | Objects of this class are thrown when exceptions occur in
|
| Error Summary | |
|---|---|
| DramaError | Objects of this class are used to convert a checked
DramaException to an unchecked expection. |
A package which provides a JAVA Interface to the AAO's DRAMA API, allowing DRAMA tasks and GUI's to be implementing in JAVA.
DramaTask class is used
to create and run a DRAMA task. You can
use the
DramaTask.Add(or
this alternative)
method to add DRAMA actions to this task. You create classes
which implement the actions - such action implementation classes must
implement the
DramaTask.Action
or DramaTask.Kickable
Action interfaces.
After adding actions and parameters, setting up a user interface etc, you
should invoke the
DramaTask.RunDrama
method to process DRAMA messages. For
simple DRAMA Java programs without a GUI, this method is normally called
in the main thread of the program. If you are implementing a GUI, then
you will have to call
DramaTask.RunDrama
in a different Java thread from the thread which implements the GUI.
When you wish to shutdown your DRAMA task, you should call
DramaTask.CloseTask, the
return value of which can be passed to
System.exit()
to provide the program exit status.
(Unlike C++'s destructors, Java's rough equivalent, the finialize
method, cannot ensure DRAMA
is shutdown correctly, hence the need for the close call. See
this Sun tip for more information). This should be
done in the same thread as called RunDrama().
DramaTask
also methods equivlant to standard DRAMA C interface operations, such as
PutObeyHandler(),
GetEntReason()
etc.
For example, PutObeyHandler() allows you to specify a different object with
the
DramaTask.Action
interface for the next stage of an action. There are
also methods which allow a GUI to redirect DRAMA'sMsgOut (informational)
and Ers (error) messages such that they may be directed to windows.
Below is a simple example of a simple DRAMA task implemented in Java.
class main {
// Static main - invoked when program starts up.
public static void main(String[] args) throws DramaException {
// Make this program a DRAMA task named "TICKER"
DramaTask task = new DramaTask("TICKER");
// Add a couple of actions to the task.
task.Add("TICK",new MyAction());
task.Add("EXIT",new ExitAction());
// Process DRAMA messages.
task.RunDrama();
// Tidy up.
System.exit(task.CloseTask());
// Should not get here, but ensure we don't try to use this again
task = null;
}
}
// A class which implements a Kickable DRAMA action.
class MyAction implements DramaTask.KickableAction {
// Invoked for Obey messages.
public void Obey(DramaTask t) throws DramaException {
// Output an informational message.
t.MsgOut("Obey routine hit");
// Make action reschedule (does this indefintenly)
t.PutRequestWait(10);
}
// Invoked for kick messages
public void Kick(DramaTask t) throws DramaException {
t.MsgOut("Kick routine hit");
// Make the action end
t.PutRequestEnd();
}
}
// A class which implements a DRAMA action (not kickable)
class ExitAction implements DramaTask.Action {
// Invoked for Obey messages.
public void Obey(DramaTask t) throws DramaException {
t.MsgOut("EXIT action invoked");
// Make the task exit - DramaTask.RunDrama will now return.
t.PutRequestExit();
}
}
target = DramaPath(DramaTask, "TICKER", "aat40.aao.gov.au");You can then use this object to send DRAMA messages, e.g.
target.GetPath()
target.Obey("TICK");
For more details, see the DramaPath
class description.
Having used DramaPath to get
a path to a task, you can use the
DramaMonitor to wrap up
parameter monitoring operations.
The DramaSem class
is used to control access to DRAMA from multiple Java threads (Java uses
threads extensively, particularly in GUI applcations).
This class implements a special semphore scheme. The explict use of this
class is not normally required by DJAVA application programmers (except
in one case, described in the description of the
DramaPath class),
but its use may
be required if you are implementing your own classes which
use the Java Native language Interface (JNI) to access DRAMA from C/C++.
Before any such method is invoked, you should call the
Take()
method of
this class and then call the
Release()
method after you return. This will ensure
that mutliple threads do not attempt to access DRAMA's internal structures
at the same time. Note that you must call the Release() method once
for each call to the Take()
method, otherwise your task will probably hang due to
a deadlock. Take() may be invoked recursively without problems.
To ensure the Release() method is invoked, you should handle
exceptions appropriately, eg.
DramaSem.Take()
try {
// Do real work here which might throw exception
}
finally {
DramaSem.Release();
}
This will prevent a deadlock occuring due to the throwing of
an exception after the semaphore has been taken.
The code between the Take() and Release() calls should
take as little time
as possible as DRAMA is not able to process messages whilst the semaphore
is taken.
import au.gov.aao.drama.dul_err;The error codes are fields within the class. E.g., dul_err.FILEOPENERR is how you access the value of the DUL Error code known in C as DUL__FILEOPENERR.
In summary, in Swing applcations, you must use
SwingUtilities.invokeLater()
to update your GUI from any method which may be invoked in the DRAMA thread.
The following is an example of how to do this
(this was taken from Sun's JAVA web pages and uses an anonymous
class which implements the Runnable interface),
void showHelloThereDialog() throws Exception {
Runnable showModalDialog = new Runnable() {
public void run() {
JOptionPane.showMessageDialog(myMainFrame,
"Hello There");
}
};
SwingUtilities.invokeAndWait(showModalDialog);
}
You should consider using this approach in a Swing and DRAMA application for
any method implementing the standard DRAMA callbacks. E.g, the appropiate
methods in classes which implement the following interfaces
setenv CLASSPATH ".:/System/Library/Java'Assuming DJAVA has been installed as part of DRAMA (see below), then you then need to execute your start DRAMA startup sequence (the dramastart command). The dramastart command will automatically add the correct DJAVA directories to the LD_LIBRARY_PATH and CLASSPATH environment variables. You should now be able to build DJAVA programs, for example, to build ticker.java, enter javac ticker. You run JAVA programs with the java command. But to run your programs, you (may) need to ensure the directory where you built you class is part of the classpath either by putting it in the CLASSPATH environment variable value or by specifying it on the command line. For example, if ticker.class is in my default directroy, the following should work
java -classpath .:$CLASSPATH tickerThe classpath has been a point of much confusion with JAVA and I admit to being unsure if I have specified the above details completely correctly (through the above does work). Creation of proper packages etc. for release are outside the scope of this document, but the DJAVA source structure and DRAMA's dmakefile may help you here.
#undef HasJava #define HasJava YES #undef JavaBase #define JavaBase /usr/javaBy default, DJAVA will be built for Solaris and Mac OS X. In both cases Java is presumed to be in the standard location. You can change the verson of Java used by changing the defintion of JavaBase (from DRAMA version 1.5.1. In older versions you must edit drama_source/djava/dmakefile to make this change). You can obtain DRAMA from our FTP site. See Installing and building DRAMA for details on building DRAMA. But, you must have a C++ compiler and tell DRAMA you have it. The later is done by adding the following lines to your ~drama/local/drama_local.cf file.
#undef HasCPlusPlus #define HasCPlusPlus YES(This is not required for Mac Os X and Linux where the presence of GNU C++ is presumed). The GNU C++ compiler is quite sufficent and is all I have tested at this stage. If you are selected GCC as your C compiler when building DRAMA then adding the above lines will enable GNU C++. If you are using a different C compiler, then you may or may not find that the above is all you need to do. Please see the DRAMA installation pages for more information
|
DJAVA | |||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||
Click here for the DRAMA home page and here for the AAO home page.
For more information, contact tjf@aaoepp.aao.gov.au.