edu.washington.NVisF.dataIO
Class DataReader

java.lang.Object
  |
  +--edu.washington.NVisF.dataIO.DataReader

Direct Known Subclasses:

BinaryDataFileReader

public abstract class DataReader

extends java.lang.Object

The abstract DataReader class defines functions for query-based access to arbitrary sources of physical data. These include opening and closing connections, retrieving meta-data that describe the data, and retrieving data described by a predicate query. This allows disparate data sources such as file systems, databases, and remote systems to be accessed through a single uniform interface. The data are assumed to have an object-oriented format. That is, data is organized into "objects" which have a name and a set of data fields. These data "objects" may or may not represent a true object in the C++ or Java sense. Each data field has a name and a type; the only currently supported data types are scalars (floats) and vectors (arrays of floats), although the system is extensible to other data types. At this time the only queries supported by the "query language" are requests for a given object type, and data for all matching objects is returned. This is expected to change in future versions once a true query language is adopted.

Constructor Summary

DataReader()

Method Summary

abstract void	closeConnection() does whatever work is needed to close the connection
abstract int	getCount(java.lang.String predicate) returns the number of objects that satisfy the given predicate.
float[]	getScalar(java.lang.String predicate, java.lang.String dataField) returns an array of floats containing the specified scalar field element for all data objects that satisfy the given predicate.
abstract TypeInfo	getTypeInfo() retrieves a description of the data available from this source as a TypeInfo object.
float[][]	getVector(java.lang.String predicate, java.lang.String dataField) returns an array of arrays containing the specified vector field element for all data objects that satisfy the given predicate.
abstract void	initConnection(java.lang.String source) initiates a connection to the data source represented by the given String.
abstract void	initConnection(java.net.URL source) initiates a connection to the data source represented by the given URL.
abstract boolean	isConnectionOpen() tests whether an active connection exists
void	loadData(java.lang.String predicate, java.lang.String[] dataFields) instructs this DataReader to gather and store the requested data for later access.

Methods inherited from class java.lang.Object

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

Constructor Detail

DataReader

public DataReader()

Method Detail

isConnectionOpen

public abstract boolean isConnectionOpen()

tests whether an active connection exists

Returns:

true if a connection is active; false otherwise

initConnection

public abstract void initConnection(java.lang.String source)
                             throws OpenConnectionException,
                                    SourceNotFoundException,
                                    DataIOException

initiates a connection to the data source represented by the given String.

Parameters:

source - a string specifying the location of the data source

Throws:

OpenConnectionException - if a connection is already established

SourceNotFoundException - if the specified resource could not be found

DataIOException - if the attempt to open the connection fails

initConnection

public abstract void initConnection(java.net.URL source)
                             throws OpenConnectionException,
                                    SourceNotFoundException,
                                    DataIOException

initiates a connection to the data source represented by the given URL.

Parameters:

source - a URL specifying the location of the data source

Throws:

OpenConnectionException - if a connection is already established

SourceNotFoundException - if the specified resource could not be found

DataIOException - if the attempt to open the connection fails

closeConnection

public abstract void closeConnection()
                              throws NoConnectionException,
                                     DataIOException

does whatever work is needed to close the connection

Throws:

NoConnectionException - if there is no active connection

DataIOException - if the attempt to close the connection fails

getTypeInfo

public abstract TypeInfo getTypeInfo()
                              throws NoConnectionException

retrieves a description of the data available from this source as a TypeInfo object.

Returns:

a TypeInfo object containing meta-data information

Throws:

NoConnectionException - if there is no ative connection

See Also:

TypeInfo

getCount

public abstract int getCount(java.lang.String predicate)
                      throws java.text.ParseException,
                             NoConnectionException,
                             DataIOException

returns the number of objects that satisfy the given predicate. Note that in the current version, the only predicates supported are simply the name of a data object.

Parameters:

predicate - a string in the query language that identifies the desired objects

Returns:

int the number of objects

Throws:

java.text.ParseException - if the predicate cannot be parsed

NoConnectionException - if there is no active connection

DataIOException - if an unexpected error occurs

loadData

public void loadData(java.lang.String predicate,
                     java.lang.String[] dataFields)
              throws java.text.ParseException,
                     NoConnectionException,
                     DataIOException

instructs this DataReader to gather and store the requested data for later access. The first argument identifies what objects to get data for, and the second identifies what fields to retrieve. If the second argument is null, then all fields are retrieved. Using this method may significantly speed up later calls to getData for this predicate. Note that in the current version, the only predicates supported are simply the name of a data object. This method is not guaranteed to be implemented by all subclasses. The default implementation is to do nothing.

Parameters:

predicate - a string in the query language that identifies the desired objects

fields - an array of strings giving the names of the desired fields

Throws:

java.text.ParseException - if the predicate cannot be parsed

NoConnectionException - if there is no active connection

DataIOException - if an unexpected error occurs

See Also:

getScalar(java.lang.String, java.lang.String), getVector(java.lang.String, java.lang.String)

getScalar

public float[] getScalar(java.lang.String predicate,
                         java.lang.String dataField)
                  throws java.text.ParseException,
                         NoConnectionException,
                         DataIOException

returns an array of floats containing the specified scalar field element for all data objects that satisfy the given predicate. The first argument is a string in the query language specifying the desired objects, while the second is a string giving the name of the field to return. Note that in the current version, the only predicates supported are simply the name of a data object, and data for all objects of that type are returned. This method is not guaranteed to be implemented by all subclasses. The default implementation throws a DataIOException identifying the non-implementing class. A null value is returned if the requested data object type does not exist, or if the requested data field is not defined as a scalar field element for that data object type.

Parameters:

predicate - a string in the query language that identifies the desired objects

dataField - a string specifying the scalar field to be returned

Returns:

float[] containing the array of scalars, or null if no matches were found

Throws:

java.text.ParseException - if the predicate cannot be parsed

NoConnectionException - if there is no active connection

DataIOException - if an unexpected error occurs

See Also:

loadData(java.lang.String, java.lang.String[])

getVector

public float[][] getVector(java.lang.String predicate,
                           java.lang.String dataField)
                    throws java.text.ParseException,
                           NoConnectionException,
                           DataIOException

returns an array of arrays containing the specified vector field element for all data objects that satisfy the given predicate. That is, the desired vector is represented as an array of floats (usually 3, for a 3-D system), and the return type is an array of these arrays with length N, where N is the number of matching data objects. The first argument is a string in the query language specifying the desired objects, while the second is a string giving the name of the field to return. Note that in the current version, the only predicates supported are simply the name of a data object, and data for all objects of that type are returned. This method is not guaranteed to be implemented by all subclasses. The default implementation throws a DataIOException identifying the non-implementing class. A null value is returned if the requested data object type does not exist, or if the requested data field is not defined as a vector field element for that data object type.

Parameters:

predicate - a string in the query language that identifies the desired objects

dataField - a string specifying the vector field to be returned

Returns:

float[][] containing the array of vectors, or null if no matches were found

Throws:

java.text.ParseException - if the predicate cannot be parsed

NoConnectionException - if there is no active connection

DataIOException - if an unexpected error occurs

See Also:

loadData(java.lang.String, java.lang.String[])