gistoolkit.datasources
Interface DataSource

All Known Subinterfaces:
RasterDatasource
All Known Implementing Classes:
ArcIMSDataSource, ERMapperDatasource, OGCWebServiceDataSource, RasterCatalogDataSource, ReadOnlyOracleDataSource, ReadOnlySpatialExtenderDataSource, SimpleDataSource, TerraserverDataSource

public interface DataSource

The DataSource is responsible for handling inserts, updates, deletes, selects, and projection of data.

There are ReadOnly data sources that do not need to handle inserts updates and deletes. In this case, the data modification methods should do nothing, and the isUpdateable() method should return false.

The DataSource is responsible for projecting the data from the native storage projection, to the projection of the rest of the software. The GISToolkit software assumes all features are in the same projection before operating on them, however as some DataSources can project much more efficiently that the GISToolkit Projection Engine can, the DataSources are responsible for handling these projections. All data coming out or going into a datasource is assumed to be in the projection of the toolkit, not the native projection of the data. The two may be the same, and in that case, the datasource may not need to project.


Method Summary
 void addDataSourceListener(DataSourceListener inDataSourceListener)
          Adds a datasource listener to this datasource.
 void commit()
          Commit all changes since the last commit.
 void delete(Record inRecord)
          Delete this record from the database.
 Envelope getEnvelope()
          Returns the bounding rectangle of all the shapes in the Data Source.
 Filter getFilter()
          Get the filter to use with this datasource.
 Projection getFromProjection()
          Gets the projection to use to convert from the storage media, source projection.
 java.lang.String getName()
          Returns the identifier string for the datasource.
 Node getNode()
          Get the configuration information for this data source
 Style getStyle()
          Get the style to use with this datasource.
 Projection getToProjection()
          Gets the projection to which this datasource is required to project its contents.
 void insert(Record inRecord)
          Inserts the given record into the datasource.
 boolean isUpdateable()
          Determines if this datasource is updateable.
 GISDataset readDataset()
          Reads all the objects from the data source.
 GISDataset readDataset(Envelope inEnvelope)
          Reads only the objects from the data source that intersect these extents.
 void removeDataSourceListener(DataSourceListener inDataSourceListener)
          Removes the datasource lisener from this datasource.
 void rollback()
          Rollback any changes to this datasource since the last commit.
 void setFilter(Filter inFilter)
          Adds a filter to this DataSource.
 void setFromProjection(Projection inProjection)
          Sets the projection to use to convert from the storage media, source projection.
 void setName(java.lang.String inName)
          Sets an identifier string for the datasource.
 void setNode(Node inNode)
          Set the configuration information for this data source
 void setToProjection(Projection inProjection, boolean inCacheProjected)
          Sets the projection to which this datasource is required to project its contents.
 void update(Record inRecord)
          Update the data source with the changed record.
 

Method Detail

getEnvelope

public Envelope getEnvelope()
                     throws java.lang.Exception
Returns the bounding rectangle of all the shapes in the Data Source.

This is used to set the initial context of the view if the datasource alone is selected. In the case that the bounding rectangle of the DataSource can not be found, a value of null should be returned. In this case, the display context must be set either by another data source, or by some other piece of information before the datasource is called.

Throws:
java.lang.Exception

setName

public void setName(java.lang.String inName)
Sets an identifier string for the datasource.


getName

public java.lang.String getName()
Returns the identifier string for the datasource.


insert

public void insert(Record inRecord)
            throws java.lang.Exception
Inserts the given record into the datasource.

This record may or may not have come from this datasource. In the case that it has not come from this datasource, a best attempt is made to insert it into the underlying collection of records. There are many restrictions that may cause a datasource to not accept a given record. In this case, the insert should throw an exception with an explanation of why this is happening. Attributes should be matched by name where available, and datatypes converted from the record to the datasource where possible. Extranious of the record should be ignored, and reasonable defaults should be provided where the record does not contain attributes present in the data source.

Throws:
java.lang.Exception

update

public void update(Record inRecord)
            throws java.lang.Exception
Update the data source with the changed record.

In this case, the record should have come from this DataSource. If it has not, then an exception should be raised indicating this problem. In addition, the DataSource is responsible for determining which record in the data source this Record should be updateing. The Record sent in is almost assuredly a clone() of a record retrieved from this datasource.

Throws:
java.lang.Exception

delete

public void delete(Record inRecord)
            throws java.lang.Exception
Delete this record from the database.

The record sent in should have been selected from this DataSource, if it was not, then an exception should be thrown that indicates that condition. This record is almost assuredly a clone() of the record retrieved from the DataSource, and it is the responsibility of the DataSource to determine which record within its datastore is to be updated with the values present in this record.

Throws:
java.lang.Exception

commit

public void commit()
            throws java.lang.Exception
Commit all changes since the last commit.

The DataSource interface implements a database type of useage system. This method is used in that contect to make changes to the DataSource permanent. The idea is that calling insert, update, or delete will begin a transaction. All calls to these methods will take effect within the data source, but may be reversed by the rollback() method. Calling the commit() method will make the changes permanent.

Throws:
java.lang.Exception

rollback

public void rollback()
              throws java.lang.Exception
Rollback any changes to this datasource since the last commit. The DataSource interface implements a database type of useage system. This method is used in that contect to remove changes to the DataSource. The idea is that calling insert, update, or delete will begin a transaction. All calls to these methods will take effect within the data source, but may be reversed by the rollback() method. Calling the commit() method will make the changes permanent.

Throws:
java.lang.Exception

readDataset

public GISDataset readDataset()
                       throws java.lang.Exception
Reads all the objects from the data source.

Throws:
java.lang.Exception

readDataset

public GISDataset readDataset(Envelope inEnvelope)
                       throws java.lang.Exception
Reads only the objects from the data source that intersect these extents.

The envelope sent in is in the projected coordinate system. The datasource is responsible for projecting the envelope sent in to the coordinate system of the data, and projecting the data features from their native coordinate system to the coordinate system of the rest of the system.

Throws:
java.lang.Exception

isUpdateable

public boolean isUpdateable()
Determines if this datasource is updateable.

In the cases where the data source is ReadOnly, this method should always return false.


addDataSourceListener

public void addDataSourceListener(DataSourceListener inDataSourceListener)
Adds a datasource listener to this datasource.


removeDataSourceListener

public void removeDataSourceListener(DataSourceListener inDataSourceListener)
Removes the datasource lisener from this datasource.


setToProjection

public void setToProjection(Projection inProjection,
                            boolean inCacheProjected)
                     throws java.lang.Exception
Sets the projection to which this datasource is required to project its contents.

The CacheProjected flag indicates to the Data source that the to projection will not be changing often, and it is OK to project once and cache it. Setting this flag to false indicates to the DataSource that the toProjection will be changing often.

Throws:
java.lang.Exception

getToProjection

public Projection getToProjection()
Gets the projection to which this datasource is required to project its contents.


setFromProjection

public void setFromProjection(Projection inProjection)
                       throws java.lang.Exception
Sets the projection to use to convert from the storage media, source projection.

This is only a suggestion to the DataSource. In the case where the DataSource can indipendently determine which projection the underlying data is in, it is expected the DataSource will use that parameter, and not use the one sent in with this method. In cases where it cannot though, this method may be used to indicated to the DataSource which projection to use for the underlying data.

It is expected that this projection will be run in reverse, to reverse project alread projected data, and that it will not change often so it is OK for this to be done just once.

Throws:
java.lang.Exception

getFromProjection

public Projection getFromProjection()
Gets the projection to use to convert from the storage media, source projection. It is expected that this projection will be run in reverse, to reverse project already projected data, and that it will not change often so it is OK for this to be done just once.


getNode

public Node getNode()
Get the configuration information for this data source


setNode

public void setNode(Node inNode)
             throws java.lang.Exception
Set the configuration information for this data source

Throws:
java.lang.Exception

setFilter

public void setFilter(Filter inFilter)
Adds a filter to this DataSource.

The dataset should only return the subset of the data from the filter that match both the attributes and the shape criteria that the filter defines.


getFilter

public Filter getFilter()
Get the filter to use with this datasource.


getStyle

public Style getStyle()
Get the style to use with this datasource.

The datasource may define a default style to use for displaying it. This is just a suggestion to the renderer. As this method provides upward dependencies, It should be removed, however it is usefull.