Contents:
Java Analysis Studio comes with several built-in Data Interface Modules which make common types of data readily usable. It is possible to use almost any type of data by writing your own data interface module (DIM). This chapter describes how to do that.
Data Interface Modules are primarily intended for making data sets available for further analysis by end users. Some types of dataset contain both pre-filled histograms and unbinned data (for example PAW ntuples) so to support these kind of datasets the DIM has provisions for providing access directly to histograms as well as to data. If you are trying to use Java Analysis Studio merely to view existing histograms, and not to allow further data analysis, for example when using JAS as a GUI for viewing histograms from an online monitoring process, then the HistogramServer interface may be more appropriate for your needs than the DIM interface.
Java Analysis Studio supports both local jobs, where the GUI client and the data to be analyzed are on the same machine, and remote jobs, where the data to be analyzed is accessed via a remote Java Data Server. When writing your own DIM there are up to three components that you must provide, depending on whether you need to support local access, remote access or both. These components are::
These three components are discussed below. Finally a simple example DIM is presented.
The following description assumes that you are already familiar with the basic components of programming in Java, such as classes, interfaces etc. If you will be accessing data by calling routines written in some language other than Java, such as C, Fortran or C++ you will also need to be familiar with the Java Native Interface (JNI) used for calling native code from Java.
The event source is the main component of the DIM. Its basic function is to open the data source, and return successive events each time its getNextEvent method is called. An event source class must implement, at a minimum, the hep.analysis.EventSource interface. Normally the EventSource will have a constructor that takes a filename or some other description of the data source to be opened. The constructor is normally public so that users can use the EventSource in standalone mode (i.e. outside of Java Analysis Studio). Most of the methods of the EventSource are self-explanatory, but here are a few notes:
The getNextEvent method should return an object that extends hep.analysis.EventSource. Normally the object that is returned will be a class specific to the format of the data being processed by your particular DIM.Often the object returned is implemented by a private nested class within the EventSource, which itself implements some public interface that the end-user can use to access the data. It is often efficient to actually return the same object each time the getNextEvent method is called, but simply increment some event counter internal to the object. This avoids the overhead of creating a new object each time getNextEvent is called, and is a reasonable thing to do since JAS is designed for analyzing a single event at a time.
The getNextEvent method should throw a hep.analysis.EndOfDataException if there are no more events to be returned.
This should return the Class of the public interface provided by the object that will be returned by the getNextEvent method.
This method is always called before getNextEvent the first time an event is read, or after the user has "rewound" the dataset. It is a convenient place to set the underlying data source back to the first event.
If your data source represents an NTuple-like event source then you may want your EventSource to implement jas.jds.module.AnnotatedEventSource, which extends hep.analysis.EventSource. An AnnotatedEventSource must implement two extra methods, described below.
This method must return an array of jas.util.tree.TreeItem's, with each tree item corresponding to a node to appear in the explorer tree.
When passed a specific item (as returned from getItems) this method should return the Object that corresponds to that item.
Documentation to be supplied
A LocalDIM presents zero or more wizard pages to the user when he/she tries to open a data source whose type corresponds to the DIM. A typical LocalDIM presents at least one wizard page to the user in which he/she gets to choose the dataset they want to open.
To create a Local Data Interface Module (DIM), you must define a class that implements
the jas.jds.module.LocalDIM interface. To implement that interface, you
must define the following methods:
This method should return a wizard page that will appear on the 'New Job Wizard' if the user selects this DIM. Use it to prompt the user for whatever setup parameters are relevant to your DIM. See the documentation on defining wizard pages.
Override the method toString() that LocalDIM inherits from java.lang.Object
and have it return a suitable description of your DIM. The Flat File DIM simply has:
Whatever this method returns will be displayed as a choice in the local DIM registry.
This method will be called after createJob() is called in the
LocalJobBuilder. It must return an EventSource, which the application will use to
access the events in your data set.
LocalJobBuilder is an interface that allows you to interact with the application to create a job. This method is called by the framework to notify the LocalDIM of the LocalJobBuilder it should use. A typical instance of this method stores the reference to the LocalJobBuilder locally, to allow the Wizard returned by the getSetupPage to refer to it. Ultimately the LocalDIM is responsible for calling the LocalJobBuilder's createJob method, typically when the user selects the finish button in the Wizard. The string passed to the createJob method will be subsequently passed to the LocalDIM's openDataSet method.
If the user save a job, the instance of the LocalDIM class used to open the datasets
attached to the job will be saved along with the job. When the job is reopened it is the
LocalDIM's responsibility to reopen the datasets. To achieve this the LocalDIM interface
implements java.io.Serializable. This means that all objects referred
to by member variables of your class will be serialized unless marked transient.
For the convenience of the user LocalDIM's normally save the user's settings between uses. To do this use a UserProperties object which you can get as follows:
To use a local DIM, you must package all the classes that comprise your DIM into a jar file and add it to the JAS extensions directory. You also need to define a class that registers your DIM, and add a JAS-inf/plugins.txt file to the jar file that contains a single line with the full name of your registration class. See the example below for details.
The example below defines a simple EventSource which returns a single random number for each event.
The RandomEvent interface describes the interface that will be implemented by the "events" returned from the RandomEventSource. In this trivial example a single method getValue returns the event's single random number.
The plugins.txt file must contain a single line giving the full class name of the registration class.
Once all the files above are compiled and inserted into a single jar file you must place the jar file into the JAS extensions directory. The jar file below contains the entire example DIM. Note that the plugins.txt file must be inserted into the JAS-inf directory within the jar file.