org.kepler.dataproxy.datasource.opendap

Class OpendapDataSource

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.InstantiableNamedObj

ptolemy.kernel.Entity<T>

ptolemy.kernel.ComponentEntity<T>

ptolemy.actor.AtomicActor<TypedIOPort>

ptolemy.actor.TypedAtomicActor

ptolemy.actor.lib.Source

ptolemy.actor.lib.LimitedFiringSource

org.kepler.dataproxy.datasource.opendap.OpendapDataSource

All Implemented Interfaces:

java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class OpendapDataSource
extends LimitedFiringSource

The OPeNDAP actor reads data from OPeNDAP data sources (i.e. servers).

OPeNDAP Actor Overview

The OPeNDAP actor provides access to data served by any Data Access Protocol (DAP) 2.0 compatible data source. The actor takes as configuration parameters the URL to the data source and an optional constraint expression (CE). Based on the URL and optional CE, the actor configures its output ports to match the variables to be read from the data source.

More information about the OPeNDAP actor

The OPeNDAP actor reads data from a single DAP data server and provides that data as either a vector.matrix or array for processing by downstream elements in a Kepler workflow. Each DAP server provides (serves) many data sources and each of those data sources can be uniquely identified using a URL in a way that's similar to how pages are provided by a web server. For more information on the DAP and on OPeNDAP's software, see www.opendap.org.

Characterization of Data Sources

Data sources accessible using DAP 2.0 are characterized by a URL that references a both a specific data server and a data granule available from that server and a Constraint Expression that describes which variables to read from within the data granule. In addition to reading data from a granule, a DAP 2.0 server can provide two pieces of information about the granule: a description of all of its variables, their names and their data types; and a collection of 'attributes' which are bound to those variables.

Operation of the Actor

The actor must have a valid URL before it can provide any information (just as a file reader actor need to point toward a file to provide data). Given a URL and the optional CE, the OPeNDAP actor will interrogate that data source and configure its output ports.

Data Types Returned by the Actor

There are two broad classes of data types returned by the actor. First there are vectors, matrices and arrays. These correspond to one, two and N (> 2) dimensional arrays. The distinction between the vector and matrix types and the N-dimensional array is that Kepler can operate on the vector and matrix types far more efficiently than the N-dimensional arrays. Many variables present in DAP data sources are of the N-dimensional array class and one way to work with these efficiently is to use the constraint expression to reduce the order of these data to one or two, thus causing the actor to store them in a vector or matrix.

As an example, consider the FNOC1 data source available at test.opendap.org. The full URL for this is http://test.opendap.org/opendap/data/nc/fnoc1.nc. It contains a variable 'u' which has three dimensions. We can constrain 'u' so that it has only two dimensions when read into Kepler using the CE 'u[0][0:16][0:20]' which selects only the first element (index 0) for the first dimension while requesting all of the remaining elements for the second and third dimensions. The www.opendap.org has documentation about the CE syntax.

The second data type returned by the actor is a record. In reality, all DAP data sources are records but the actor automatically 'disassembles' the top most record since we know that's what the vast majority of users will want. However, some data sources contains nested hierarchies of records many levels deep. When dealing with those data sources you will need to use the Kepler record disassembler in your workflow.

Since:

Kepler 1.0RC1

Author:

Nathan Potter

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
static int	EMBEDDED_METADATA
static java.lang.String	globalMetadataPortName
StringParameter	metadataOptionsParameter Controls if and how the DAP2 metadata is incorporated into the Actors output.
static int	NO_METADATA
PortParameter	opendapCEParameter The OPeNDAP Constraint Expression used to sub sample the dataset.
PortParameter	opendapURLParameter The OPeNDAP URL that identifies a (possibly constrained) dataset.
static int	SEPARATE_METADATA_PORT
static java.lang.String	separateMetadataPortName

Fields inherited from class ptolemy.actor.lib.LimitedFiringSource

_firingCountLimit, _iterationCount, firingCountLimit

Fields inherited from class ptolemy.actor.lib.Source

_triggered, output, trigger

Fields inherited from class ptolemy.actor.TypedAtomicActor

_typesValid

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

Constructors

Constructor and Description
OpendapDataSource(CompositeEntity container, java.lang.String name)

Method Summary

Modifier and Type	Method and Description
void	attributeChanged(Attribute attribute) Override the base class to determine which attribute is being specified.
void	fire() Read at most one input token from each channel of the trigger input and discard it.
static java.lang.String	portInfo(TypedIOPort port) Probe a port
void	preinitialize() Create receivers and declare delay dependencies.
static void	squeezeArrays(opendap.dap.DConstructor dds) Eliminates array dimensions whose dimensions are 1 (and thus in practice don't exist)

Methods inherited from class ptolemy.actor.lib.LimitedFiringSource

initialize, postfire

Methods inherited from class ptolemy.actor.lib.Source

_customTypeConstraints, prefire

Methods inherited from class ptolemy.actor.TypedAtomicActor

_containedTypeConstraints, _defaultTypeConstraints, _fireAt, _fireAt, attributeTypeChanged, clone, clone, isBackwardTypeInferenceEnabled, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, _declareDelayDependency, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate, wrapup

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_addPort, _description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

opendapURLParameter

public PortParameter opendapURLParameter

The OPeNDAP URL that identifies a (possibly constrained) dataset.

opendapCEParameter

public PortParameter opendapCEParameter

The OPeNDAP Constraint Expression used to sub sample the dataset.

metadataOptionsParameter

public StringParameter metadataOptionsParameter

Controls if and how the DAP2 metadata is incorporated into the Actors output.

NO_METADATA

public static int NO_METADATA

EMBEDDED_METADATA

public static int EMBEDDED_METADATA

SEPARATE_METADATA_PORT

public static int SEPARATE_METADATA_PORT

separateMetadataPortName

public static java.lang.String separateMetadataPortName

globalMetadataPortName

public static java.lang.String globalMetadataPortName

Constructor Detail

OpendapDataSource

public OpendapDataSource(CompositeEntity container,
                         java.lang.String name)
                  throws NameDuplicationException,
                         IllegalActionException

Throws:

NameDuplicationException

IllegalActionException

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Description copied from class: LimitedFiringSource

Override the base class to determine which attribute is being specified.

Overrides:

attributeChanged in class LimitedFiringSource

Parameters:

attribute - The changed Attribute.

Throws:

IllegalActionException - When bad things happen.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Description copied from class: AtomicActor

Create receivers and declare delay dependencies. Derived classes can override this method to perform additional initialization functions, but they should call this base class methods or create the receivers themselves. This method gets executed exactly once prior to any other action methods. It cannot produce output data since type resolution is typically not yet done. It also gets invoked prior to any static scheduling that might occur in the domain, so it can change scheduling information.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - Not thrown in this base class.

fire

public void fire()
          throws IllegalActionException

Description copied from class: Source

Read at most one input token from each channel of the trigger input and discard it. If the trigger input is not connected or has no actual sources (it might be connected to other inputs, for example, or to an unconnected input port at a higher level in the hierarchy) then this method does nothing. Derived classes should be sure to call super.fire(), or to consume the trigger input tokens themselves, so that they aren't left unconsumed.

Specified by:

fire in interface Executable

Overrides:

fire in class Source

Throws:

IllegalActionException - Not thrown in this base class.

portInfo

public static java.lang.String portInfo(TypedIOPort port)

Probe a port

Parameters:

port - The port to probe.

Returns:

The probe report.

squeezeArrays

public static void squeezeArrays(opendap.dap.DConstructor dds)

Eliminates array dimensions whose dimensions are 1 (and thus in practice don't exist)

Parameters:

dds - The DDS to traverse and squeeze its member arrays.