org.iges.anagram
Class Tool

java.lang.Object
  |
  +--org.iges.anagram.AbstractModule
        |
        +--org.iges.anagram.Tool

All Implemented Interfaces:

Module

Direct Known Subclasses:

GradsTool

public abstract class Tool

extends AbstractModule

A tool for accessing and analyzing data.

This class encapsulates all operations that are specific to the particular data format and/or access mechanism being served by the Anagram server. Thus, implementing the Anagram framework simply means implementing this class, plus possibly TempDataHandle (see doAnalysis() and doUpload()).

Field Summary

Fields inherited from class org.iges.anagram.AbstractModule

log, moduleName, parent, server

Constructor Summary

Tool()

Method Summary

abstract TempDataHandle	doAnalysis(java.lang.String name, java.lang.String ae, Privilege privilege) Performs an analysis task.
abstract DataHandle[]	doImport(Setting setting) Creates usable handles for data objects specified by tags in the configuration file.
abstract boolean	doUpdate(DataHandle data) Brings the data handle provided up to date with respect to the data source.
abstract TempDataHandle	doUpload(java.lang.String name, java.io.InputStream input, long size, Privilege privilege) Accepts an uploaded data object.
abstract DAS	getDAS(DataHandle data) Provides an object representation of the DODS Data Attribute Structure for the specified data object.
abstract ServerDDS	getDDS(DataHandle data, java.lang.String ce) Provides an object representation of the DODS Data Descriptor Structure for the specified data object.
abstract void	writeASCIIData(DataHandle data, java.lang.String ce, Privilege privilege, java.io.OutputStream out) Writes a data subset to a stream as a text table.
abstract void	writeBinaryData(DataHandle data, java.lang.String ce, Privilege privilege, java.io.OutputStream out) Writes a subset of the specified data object to the specified stream, in DODS binary format.
void	writeDAS(DataHandle data, java.io.OutputStream out) Writes the DODS Data Attribute Structure for the specified data object to the specified stream.
void	writeDDS(DataHandle data, java.lang.String ce, java.io.OutputStream out) Writes the DODS Data Descriptor Structure for the specified data object to the specified stream.
abstract void	writeWebInfo(DataHandle data, java.io.OutputStream out) Writes a customized summary of the dataset, in the form of an HTML fragment, to the specified stream.

Methods inherited from class org.iges.anagram.AbstractModule

configModule, configure, debug, debug, error, fail, fail, fail, getModuleID, getModuleName, info, init, toString, verbose, verbose

Methods inherited from class java.lang.Object

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

Constructor Detail

Tool

public Tool()

Method Detail

doImport

public abstract DataHandle[] doImport(Setting setting)

Creates usable handles for data objects specified by tags in the configuration file.

If possible, the import method should skip data objects that are already loaded, and whose attributes have not changed.

This method does not need to be threadsafe.

Parameters:

setting - The tag tree specifying the data objects. This will be the tree rooted at the subtag of the tag in the configuration file. The combination of tag names and attributes to be used for specifying data objects is up to the implementor of this method.

doAnalysis

public abstract TempDataHandle doAnalysis(java.lang.String name,
                                          java.lang.String ae,
                                          Privilege privilege)
                                   throws ModuleException

Performs an analysis task.

If analysis is not supported, this method should throw an exception.

This method must be threadsafe.

Parameters:

ae - The analysis expression to be evaluated. The format of this expression is up to the implementor of this method.

Returns:

A handle to the results of the analysis. TempDataHandle is an abstract interface. Thus, this method is responsible for supplying an object which implements TempDataHandle properly.

Throws:

ModuleException - If the analysis fails for any reason

doUpload

public abstract TempDataHandle doUpload(java.lang.String name,
                                        java.io.InputStream input,
                                        long size,
                                        Privilege privilege)
                                 throws ModuleException

Accepts an uploaded data object.

If uploads are not supported, this method should throw an exception.

This method must be threadsafe.

Parameters:

input - The stream of data to be stored

Returns:

A handle to the uploaded data object. TempDataHandle is an abstract interface. Thus, this method is responsible for supplying an object which implements TempDataHandle properly.

Throws:

ModuleException - if the upload fails for any reason

doUpdate

public abstract boolean doUpdate(DataHandle data)
                          throws ModuleException

Brings the data handle provided up to date with respect to the data source.

This method must be threadsafe.

Returns:

True if the data handle was modified.

Throws:

ModuleException - If the data source has become unusable.

getDDS

public abstract ServerDDS getDDS(DataHandle data,
                                 java.lang.String ce)
                          throws ModuleException

Provides an object representation of the DODS Data Descriptor Structure for the specified data object. It is guaranteed that the calling thread will already have a non-exclusive lock on the data parameter before this method is called. Other than that, this method must guarantee its own thread-safety.

Parameters:

data - The data object to be accessed

ce - The DODS constraint to be applied to the DDS. Null indicates that the DDS should not be constrained.

Returns:

an object representing the DDS

Throws:

ModuleException - if the request fails for any reason

See Also:

Handle.getSynch()

getDAS

public abstract DAS getDAS(DataHandle data)
                    throws ModuleException

Provides an object representation of the DODS Data Attribute Structure for the specified data object. It is guaranteed that the calling thread will already have a non-exclusive lock on the data parameter before this method is called. Other than that, this method must guarantee its own thread-safety.

Parameters:

data - The data object to be accessed

Returns:

an object representing the DAS

Throws:

ModuleException - if the request fails for any reason

See Also:

Handle.getSynch()

writeDDS

public void writeDDS(DataHandle data,
                     java.lang.String ce,
                     java.io.OutputStream out)
              throws ModuleException

Writes the DODS Data Descriptor Structure for the specified data object to the specified stream. It is guaranteed that the calling thread will already have a non-exclusive lock on the data parameter before this method is called. Other than that, this method must guarantee its own thread-safety.

This method has a default implementation, which creates a DDS object using getDDS(), and serializes it to the stream. For optimal performance it is recommended to override this default implementation with a faster approach, such as streaming the DDS text directly from a cached disk file.

Parameters:

data - The data object to be accessed

ce - The DODS constraint to be applied to the DDS. Null indicates that the DDS should not be constrained.

out - A stream to which to write the DDS

Throws:

ModuleException - if the request fails for any reason

See Also:

Handle.getSynch()

writeDAS

public void writeDAS(DataHandle data,
                     java.io.OutputStream out)
              throws ModuleException

Writes the DODS Data Attribute Structure for the specified data object to the specified stream. It is guaranteed that the calling thread will already have a non-exclusive lock on the data parameter before this method is called. Other than that, this method must guarantee its own thread-safety.

This method has a default implementation, which creates a DAS object using getDAS(), and serializes it to the stream. For optimal performance it is recommended to override this default implementation with a faster approach, such as streaming the DAS text directly from a cached disk file.

Parameters:

data - The data object to be accessed

out - A stream to which to write the DAS

Throws:

ModuleException - if the request fails for any reason

See Also:

Handle.getSynch()

writeWebInfo

public abstract void writeWebInfo(DataHandle data,
                                  java.io.OutputStream out)
                           throws ModuleException

Writes a customized summary of the dataset, in the form of an HTML fragment, to the specified stream. It is guaranteed that the calling thread will already have a non-exclusive lock on the data parameter before this method is called. Other than that, this method must guarantee its own thread-safety.

Parameters:

data - The data object to be accessed

out - A stream to which to write the DAS

Throws:

ModuleException - if the request fails for any reason

See Also:

Handle.getSynch()

writeBinaryData

public abstract void writeBinaryData(DataHandle data,
                                     java.lang.String ce,
                                     Privilege privilege,
                                     java.io.OutputStream out)
                              throws ModuleException

Writes a subset of the specified data object to the specified stream, in DODS binary format.

It is guaranteed that the calling thread will already have a non-exclusive lock on the data parameter before this method is called. Other than that, this method must guarantee its own thread-safety.

Parameters:

data - The data object to be accessed

ce - The DODS constraint expression specifying the subset to be sent

out - The stream to which to write the subset

Throws:

ModuleException - if the request fails for any reason

See Also:

Handle.getSynch()

writeASCIIData

public abstract void writeASCIIData(DataHandle data,
                                    java.lang.String ce,
                                    Privilege privilege,
                                    java.io.OutputStream out)
                             throws ModuleException

Writes a data subset to a stream as a text table.

It is guaranteed that the calling thread will already have a non-exclusive lock on the data parameter before this method is called. Other than that, this method must guarantee its own thread-safety.

Parameters:

data - The data object to be accessed

ce - The DODS constraint expression specifying the subset to be sent

out - The stream to which to write the subset

Throws:

ModuleException - if the request fails for any reason

See Also:

Handle.getSynch()