org.das2.dataset
Class DataSetDescriptor

java.lang.Object
  org.das2.dataset.DataSetDescriptor

All Implemented Interfaces:

Displayable

Direct Known Subclasses:

ConstantDataSetDescriptor, FileStorageModelAvailabilityDataSetDescriptor, MendelbrotDataSetDescriptor, PolynomialDataSetDescriptor, RipplesDataSetDescriptor, SineWaveDataSetDescriptor, StreamDataSetDescriptor

public abstract class DataSetDescriptor
extends java.lang.Object
implements Displayable

DataSetDescriptors are a source from where datasets are produced. These uniquely identify a data set that is parameteric. Typically, the parameter is time, so for example, there might be a DataSetDescriptor for "discharge of the Iowa River measured at Iowa City." Clients of the class get DataSets from the DataSetDescriptor via the getDataSet( Start, End, Resolution ) method. So for example, you might ask what is the discharge from June 1 to August 31st, 2005, at a resolution of 1 day. Presently, it's implicit that this means to give bin averages of the data.

DataSetDescriptors are identified with a URL-like string:

http://www-pw.physics.uiowa.edu/das/das2Server?das2_1/cluster/wbd/r_wbd_dsn_cfd&spacecraft%3Dc1%26antenna%3DEy

The protocol of the string indicates how the DataSetDescriptor is to be constructed, and presently there are:

   http     a das2Server provides the specification of the datasetdescriptor.
   class    refers to a loadable java class that is an instanceof DataSetDescriptor and
            has the method newDataSetDescriptor( Map params ) throws DasException

Field Summary

protected java.util.Map

properties

Constructor Summary

protected	DataSetDescriptor()
protected	DataSetDescriptor(java.lang.String dataSetID)

Method Summary

void	addDataSetUpdateListener(DataSetUpdateListener listener)
static DataSetDescriptor	create(java.lang.String dataSetID) creates a DataSetDescriptor for the given identification string.
protected void	fireDataSetUpdateEvent(DataSetUpdateEvent event)
DataSet	getDataSet(Datum start, Datum end, Datum resolution, ProgressMonitor monitor) Retrieve the dataset for this interval and resolution.
DataSetCache	getDataSetCache()
java.lang.String	getDataSetID()
protected abstract DataSet	getDataSetImpl(Datum start, Datum end, Datum resolution, ProgressMonitor monitor) getDataSetImpl implements the getDataSet for this DataSetDescriptor implementation.
javax.swing.Icon	getListIcon() An icon can be provided that will be shown in a list along with the textual description of the element.
java.lang.String	getListLabel() return a String that will help the user identify this item when choosing from a list.
java.lang.Object	getProperty(java.lang.String name) Returns the value of the property with the specified name
abstract Units	getXUnits()
void	removeDataSetUpdateListener(DataSetUpdateListener listener)
void	requestDataSet(Datum start, Datum end, Datum resolution, ProgressMonitor monitor, java.lang.Object lockObject) Requests that a dataSet be loaded, and that the dataSet be returned via a DataSetUpdate event.
void	requestDataSet(Datum start, Datum end, Datum resolution, ProgressMonitor monitor, java.lang.Object lockObject, DataSetUpdateListener listener) Request the dataset, and the dataset is returned only to the listener.
void	reset() clear any state that's developed, in particular any data caches.
void	setDefaultCaching(boolean value) defaultCaching means that the abstract DataSetDescriptor is allowed to handle repeat getDataSet calls by returning a cached dataset.
protected void	setProperties(java.util.Map properties)

Methods inherited from class java.lang.Object

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

Field Detail

properties

protected java.util.Map properties

Constructor Detail

DataSetDescriptor

protected DataSetDescriptor(java.lang.String dataSetID)

DataSetDescriptor

protected DataSetDescriptor()

Method Detail

getDataSetImpl

protected abstract DataSet getDataSetImpl(Datum start,
                                          Datum end,
                                          Datum resolution,
                                          ProgressMonitor monitor)
                                   throws DasException

getDataSetImpl implements the getDataSet for this DataSetDescriptor implementation. The getDataSet call of the abstract DataSetDescriptor uses this routine to satisfy requests and fill its cache. This caching may be disabled via setDefaultCaching. To satisfy the request, a DataSet should be returned with an x tag range that contains start and end, with a resolution finer than that requested.

Parameters:

start - beginning of range for the request.

end - end of the range for the request.

resolution - the resolution requirement for the reqeust. null may be used to request the finest resolution available or intrinic resolution.

Throws:

DasException

getXUnits

public abstract Units getXUnits()

Returns:

the x units of the DataSetDescriptor that parameterize the data. This is used to identify dataSet requests.

requestDataSet

public void requestDataSet(Datum start,
                           Datum end,
                           Datum resolution,
                           ProgressMonitor monitor,
                           java.lang.Object lockObject)

Requests that a dataSet be loaded, and that the dataSet be returned via a DataSetUpdate event. The @param lockObject is an object that is dependent on the load, for example, the DasCanvas, and will be passed in to the request processor. If the dataSet is available in interactive time, then the dataSetUpdate may be fired on the same thread as the request is made.

requestDataSet

public void requestDataSet(Datum start,
                           Datum end,
                           Datum resolution,
                           ProgressMonitor monitor,
                           java.lang.Object lockObject,
                           DataSetUpdateListener listener)

Request the dataset, and the dataset is returned only to the listener.

Parameters:

lockObject - object that is waiting for the result of this load, used to block other tasks which use that object.

getDataSet

public DataSet getDataSet(Datum start,
                          Datum end,
                          Datum resolution,
                          ProgressMonitor monitor)
                   throws DasException

Retrieve the dataset for this interval and resolution. The contract for this function is that identical start,end,resolution parameters will yield an identical dataSet, except for when an DataSetUpdate has been fired in the meantime. null for the data resolution indicates that the data should be returned at its "intrinsic resolution" if such a resolution exists.

Throws:

DasException

reset

public void reset()

clear any state that's developed, in particular any data caches. Note this currently deletes all cached datasets, regardless of the DataSetDescriptor that produced them.

setDefaultCaching

public void setDefaultCaching(boolean value)

defaultCaching means that the abstract DataSetDescriptor is allowed to handle repeat getDataSet calls by returning a cached dataset. If a dataSetUpdate event is thrown, the defaultCache is reset. Use caution when using this. Note that caching may only be turned off with this call.

addDataSetUpdateListener

public void addDataSetUpdateListener(DataSetUpdateListener listener)

removeDataSetUpdateListener

public void removeDataSetUpdateListener(DataSetUpdateListener listener)

fireDataSetUpdateEvent

protected void fireDataSetUpdateEvent(DataSetUpdateEvent event)

getDataSetID

public java.lang.String getDataSetID()

Returns:

the string that uniquely identifies this dataset.

create

public static DataSetDescriptor create(java.lang.String dataSetID)
                                throws DasException

creates a DataSetDescriptor for the given identification string. The identification string is a URL-like string, for example http://www-pw.physics.uiowa.edu/das/das2Server?das2_1/cluster/wbd/r_wbd_dsn_cfd&spacecraft%3Dc1%26antenna%3DEy The protocol of the string indicates how the DataSetDescriptor is to be constructed, and presently there are:

   http     a das2Server provides the specification of the DataSetDescriptor, and a
            StreamDataSetDescriptor is created.
   class    refers to a loadable java class that is an instanceof DataSetDescriptor and
            has the method newDataSetDescriptor( Map params )

Note that DataSetDescriptors are stateless, the same DataSetDescriptor object may be returned to multiple clients.

Throws:

DasException

setProperties

protected void setProperties(java.util.Map properties)

getProperty

public java.lang.Object getProperty(java.lang.String name)

Returns the value of the property with the specified name

Parameters:

name - The name of the property requested

Returns:

The value of the requested property as an Object

getListIcon

public javax.swing.Icon getListIcon()

Description copied from interface: Displayable

An icon can be provided that will be shown in a list along with the textual description of the element. This method should return null if there is no icon available.

Specified by:

getListIcon in interface Displayable

getListLabel

public java.lang.String getListLabel()

Description copied from interface: Displayable

return a String that will help the user identify this item when choosing from a list.

Specified by:

getListLabel in interface Displayable

getDataSetCache

public DataSetCache getDataSetCache()

Returns:

the DataSetCache object used to store cached copies of the DataSets created by this object.