All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.las.ogdi.OGDIClient

java.lang.Object
   |
   +----com.las.ogdi.OGDIClient

public abstract class OGDIClient

extends Object

An application using the OGDI interface performs the following tasks:
 - requests a connection with a geospatial data source;
 - sends requests to the data source. These requests can be directed to
   specific geospatial data coverages and/or to specific geographic
   subregions;
 - defines storage areas and data formats for the results of these requests;
 - processes the results of the requests (performs spatial analysis or
   visualization);
 - processes errors; and
 - terminates the connection to the data source.

OGDI was developed mainly for GIS software vendors, but can be used in any application where GIS data retrieval is required.

In other words, to interact with a datastore, a simple application 
 goes through the following steps:
 - Establish a connection (i.e.: create a client).
 - Select a geographic region.
 - Select a layer (coverage).
 - Extract objects sequentially or randomly.
 - Process the results.
 - Terminate the connection (disconnect from the client).

The JAVA API is composed of a few functions that perform the following 
 actions:
 - manage and load the geospatial data driver;
 - provide an entry point to OGDI functions for each driver;
 - allocate storage for geometric and attribute data;
 - perform "garbage collection" of previously allocated storage; and
 - provide parameter validation and sequence validation for OGDI calls.

Note that the original OGDI C API used to make all necessary coordinate and cartographic projection transformations at the client level. These operations are now carried out by the gltpd.

Version:

1.1

Author:

Las Inc.

compression

coverageRegion

currentCoverage

currentFamily

currentProjection

currentRegion

server

sourceProjection

url

verbose

OGDIClient()

Creates an instance of OGDI Client and connects it to the requested URL.

addConnectionListener(ConnectionListener)

Adds a listener to the client.

calcDistance(OGDICoordinate, OGDICoordinate)

Calculates a distance between two coordinates.

convertCoordinates(OGDIProjectionDescriptor, OGDIProjectionDescriptor, OGDICoordinate[])

Converts a set of coordinates between two projections.

dispose()

Closes the connection.

finalize()

This function is called by the garbage collector.

getAPIVersion(int)

Gets the API version.

getAttributesFormat()

Gets the list of attribute formats of the selected coverage.

getCurrentCoverage()

Gets the current coverage.

getCurrentCoverageRegion()

Gets the geographic region and base resolution (for raster) of the currently selected coverage.

getCurrentProjection()

Gets the current projection of the client.

getCurrentRegion()

Gets the current region previously set.

getDictionary()

Gets the dictionary of the datasource.

getFeature(String)

Gets the coordinates and attributes of the specified geometric object.

getFeatureIdFromCoord(OGDICoordinate)

Gets the id of the object that is nearest to a set of coordinates in the current layer.

getNextFeature()

Gets the next geometric object in the current coverage.

getRasterInfo()

Gets the raster information of the selected coverage.

getSourceProjection()

Gets the projection of the datasource.

getSourceRegion()

Gets the global region of the datasource.

getUrl()

Gets the Uniform Resource Locator of the client.

isVerbose()

Gets the verbosity status of the client (false by default).

removeConnectionListener(ConnectionListener)

Removes a listener from the client.

setCurrentCoverage(OGDICoverage)

Defines the current coverage by an existing coverage.

setCurrentCoverage(OGDIFamily, String)

Defines the current coverage by a request.

setCurrentProjection(OGDIProjectionDescriptor)

Sets the current projection of the client.

setCurrentRegion(OGDIRegion)

Selects the current geographic region.

setVerbose(boolean)

Sets the verbosity of the client.

toString()

Gets the complete client description.

 protected OGDIUrl url

 protected OGDICoverage currentCoverage

 protected OGDIRegion currentRegion

 protected OGDIRegion coverageRegion

 protected OGDIProjectionDescriptor currentProjection

 protected OGDIProjectionDescriptor sourceProjection

 protected boolean verbose

 protected String compression

 protected Remote server

 protected int currentFamily

 protected OGDIClient() throws OGDIException

Creates an instance of OGDI Client and connects it to the requested URL.

Parameters:

no - parameter

Returns:

no return

Throws: OGDIException

if there is a bad connection

Throws: IllegalArgumentException

if URL is badly formatted

See Also:

OGDIUrl

 public static final String getAPIVersion(int level)

Gets the API version.

Parameters:

level - the level of detail (0 is the least detailed)

Returns:

metadata about the API

Throws: no

exception

 public OGDIUrl getUrl() throws OGDIException

Gets the Uniform Resource Locator of the client.

Parameters:

no - parameter

Returns:

the Url of the client

Throws: OGDIException

if unable to get a valid Url

 public void setCurrentCoverage(OGDIFamily family,
                                String request) throws OGDIException

Defines the current coverage by a request. The selected layer is considered the current coverage by all other coverage-oriented methods until this method is called again with a new request. When geographic objects are retrieved from this coverage, they are retrieved from the region previously selected by setCurrentRegion . If setCurrentRegion was not called, the source default region is used.

Parameters:

family - a family type of geometric objects

request - a request in the layer information structure

Returns:

no return

Throws: IllegalArgumentException

if the coverage is in the wrong format

Throws: OGDIException

if the coverage is irretrievable

See Also:

getNextFeature, getDictionary, setCurrentRegion

 public void setCurrentCoverage(OGDICoverage coverage) throws OGDIException

Defines the current coverage by an existing coverage. The selected layer is considered the current coverage by all other coverage-oriented methods until this method is called again with a new request. When geographic objects are retrieved from this coverage, they are retrieved from the region previously selected by setCurrentRegion . If setCurrentRegion was not called, the source default region is used.

Parameters:

coverage - a coverage in the layer information structure

Returns:

no return

Throws: IllegalArgumentException

if the coverage is in the wrong format

Throws: OGDIException

if the coverage is irretrievable

See Also:

getNextFeature, getDictionary, setCurrentRegion

 public OGDICoverage getCurrentCoverage() throws OGDIException

Gets the current coverage.

Parameters:

no - parameter

Returns:

the current coverage of the client or null

Throws: OGDIException

if unable to get a valid coverage

 public OGDIDictionary getDictionary() throws OGDIException

Gets the dictionary of the datasource.

Parameters:

no - parameter

Returns:

a dictionary describing the content of the datastore

Throws: OGDIException

if unable to fetch a valid dictionary

 public void setCurrentRegion(OGDIRegion region) throws OGDIException

Selects the current geographic region. Until the method is called again, all geographic objects retrieved are contained (partially or totally) within this region. The region is defined with the client's projection.

Parameters:

region - The current geographic region

Returns:

no return

Throws: IllegalArgumentException

if region is invalid

Throws: OGDIException

if unable to set a valid region

 public OGDIRegion getCurrentRegion() throws OGDIException

Gets the current region previously set. All geographic objects retrieved are at least partially contained in it.

Parameters:

no - parameter

Returns:

the north, south, east, west bounding box and resolution

Throws: OGDIException

if unable to get a valid region

 public OGDIRegion getSourceRegion() throws OGDIException

Gets the global region of the datasource.

Parameters:

no - parameter

Returns:

the north, south, east, west bounding box and resolution

Throws: OGDIException

if unable to get a valid region

 public OGDIRegion getCurrentCoverageRegion() throws OGDIException

Gets the geographic region and base resolution (for raster) of the currently selected coverage.

Parameters:

no - parameter

Returns:

the north, south, east, west bounding box and resolution

Throws: OGDIException

if unable to get a valid coverage region

 public abstract void setCurrentProjection(OGDIProjectionDescriptor projection) throws OGDIException

Sets the current projection of the client.

Parameters:

projection - a projection descriptor

Returns:

no return

Throws: IllegalArgumentException

if the projection is invalid

Throws: OGDIException

if unable to set a valid projection

 public OGDIProjectionDescriptor getCurrentProjection() throws OGDIException

Gets the current projection of the client.

Parameters:

no - parameter

Returns:

the projection descriptor

Throws: OGDIException

if unable to get a valid descriptor

 public OGDIProjectionDescriptor getSourceProjection() throws OGDIException

Gets the projection of the datasource.

Parameters:

no - parameter

Returns:

a projection descriptor

Throws: OGDIException

if unable to get a valid descriptor

 public abstract double calcDistance(OGDICoordinate begin,
                                     OGDICoordinate end) throws OGDIException

Calculates a distance between two coordinates.

Parameters:

begin - a beginning coordinate

end - an ending coordinate

Returns:

a geographic distance in the coordinate system of the current projection

Throws: IllegalArgumentException

if beginning/ending coordinate is illegal

Throws: OGDIException

if results are illegal

 public abstract void convertCoordinates(OGDIProjectionDescriptor original,
                                         OGDIProjectionDescriptor target,
                                         OGDICoordinate coordinates[]) throws OGDIException

Converts a set of coordinates between two projections.

Parameters:

original - the projection of the coordinates to convert

target - the projection to which coordinates are converted

coordinates - a table of coordinates in the original projection

Returns:

no return: the coordinates referenced by coordinate are directly changed

Throws: IllegalArgumentException

if original/target projection or coordinates are illegal

Throws: OGDIException

if result coordinates are illegal

 public OGDIFeature getFeature(String id) throws OGDIException

Gets the coordinates and attributes of the specified geometric object. Coordinates are expressed in the coordinate system of the current projection

Parameters:

id - the id of a point as coded in the coverage (generally a number > 0)

Returns:

a geometric object or null if object doesn't exist or no coverage selected

Throws: IllegalArgumentException

if id is null or empty

Throws: OGDIException

if unable to fetch a valid object from the server

 public OGDIFeature getNextFeature() throws OGDIException

Gets the next geometric object in the current coverage.

Parameters:

no - parameter

Returns:

a geometric object or null if no more objects or no coverage selected

Throws: OGDIException

if unable to fetch a valid object from the server

 public String getFeatureIdFromCoord(OGDICoordinate coord) throws OGDIException

Gets the id of the object that is nearest to a set of coordinates in the current layer.

Parameters:

coord - a coordinate in the coordinate system of the current projection

Returns:

an id string or null if no object at coord or no coverage selected

Throws: IllegalArgumentException

if coord is null

Throws: OGDIException

if unable to fetch a valid object from the server

 public void setVerbose(boolean verbose)

Sets the verbosity of the client. If set to true, object information will be loaded

Parameters:

verbose - true if object information is needed, false otherwise

Returns:

no return

Throws: no

exception

 public boolean isVerbose()

Gets the verbosity status of the client (false by default).

Parameters:

no - parameter

Returns:

true if the client loads the object information

Throws: no

exception

 public Enumeration getAttributesFormat() throws OGDIException

Gets the list of attribute formats of the selected coverage. If there is no selected coverage, returns null.

Parameters:

no - parameter

Returns:

an enumeration of zero or more OGDIAttributeFormat

Throws: OGDIException

if unable to fetch a valid format from the server

 public OGDIRasterInfo getRasterInfo() throws OGDIException

Gets the raster information of the selected coverage. If the selected coverage is a raster, null otherwise.

Parameters:

no - parameter

Returns:

a RasterInfo structure

Throws: OGDIException

if unable to fetch a valid info from the server

 public void addConnectionListener(ConnectionListener listener) throws OGDIException

Adds a listener to the client. The listener will be notified when the connection is closed.

Parameters:

listener - the listener instance (for example a display window)

Returns:

no return

Throws: OGDIException

if client is already disposed of

 public void removeConnectionListener(ConnectionListener listener) throws OGDIException

Removes a listener from the client.

Parameters:

listener - the listener instance (for example a display window)

Returns:

no return

Throws: OGDIException

if client is already disposed of

 public synchronized void dispose() throws OGDIException

Closes the connection. All the listeners are notified of the event. After this function has been called, the object should not be used any more.

Parameters:

no - parameter

Returns:

no return

Throws: OGDIException

if unable to disconnect (server will timeout automatically)

See Also:

addListener, removeListener

 public String toString()

Gets the complete client description.

Parameters:

no - parameter

Returns:

the client url as a string

Throws: no

exception

Overrides:

toString in class Object

 protected void finalize() throws Throwable

This function is called by the garbage collector. Users should not call this function. It calls the dispose function in order to close the connection and free the resources.

Parameters:

no - parameter

Returns:

no return

Throws: Throwable

if there is a problem with garbage collection

Overrides:

finalize in class Object

See Also:

dispose

All Packages  Class Hierarchy  This Package  Previous  Next  Index