com.c5corp.c5utm
Class C5UTM

java.lang.Object
  com.c5corp.c5utm.C5UTM

public class C5UTM
extends java.lang.Object

C5UTM contains static methods for accessing the data in a C5 Landscape database installation.

Since:

1.0.3

Author:

Brett Stalbaum Copyright 2002-2006 see LICENSE.txt and UCSD_LICENSE.txt

Constructor Summary

C5UTM()

Method Summary

static java.lang.String	deleteDem(java.lang.String id) boolean deleteDem(String id) This method drops a dem from the database according to its id.
static java.lang.String	deleteDem(java.lang.String id, C5UTMconfs confs) String deleteDem(String id, C5UTMconfs conf) This method drops a dem from the database according to its id.
static DemMetadata	findDem(int zone, int easting, int northing, int easting_meters, int northing_meters, java.sql.Connection connection) Given an area represented by the methods parameters, a DemMetadata object representing a Dem that encloses the given area.
static java.util.Vector	findDemNameContains(java.lang.String str, C5UTMconfs confs, java.sql.Connection connection) Deprecated. since version 2.0
static java.util.Vector	findDemNameContains(java.lang.String str, java.sql.Connection connection) Vector findDemNameContains(String str, C5UTMconfs conf) This method will normally return a Vector with either 0 or more elements of type DemMetadata.
static java.util.Vector	findExactDemNames(java.lang.String str, C5UTMconfs confs, java.sql.Connection connection) Deprecated. since version 2.0
static java.util.Vector	findExactDemNames(java.lang.String str, java.sql.Connection connection) Vector findExactDemNames(String str, C5UTMconfs conf) Finds an exact match for a dem name from the file_info field of DEM_METADATA.
static java.util.Vector<StatisticalPoint>	findSimilarPoints(StatisticalPoint input, double tolerance, java.sql.Connection connection) Given an input point and a connection object, returns a Vector of most similar points.
static java.util.Vector<DemMetadata>	getAllDemMetadata(java.sql.Connection connection) gets all the Dem meta data objects from the database
static UtmCoordinatePairElev[][]	getCoordinatePairElevArray(int zone, int easting, int northing, int easting_meters, int northing_meters, java.sql.Connection connection) This method is similar to the getPoints method in this class, (which returns a more powerful Points object) in that it has the same method signature and performs a similar function, but has some notable differences.
static DemMetadata	getDemMetadata(java.lang.String id, java.sql.Connection connection) Searches the DEM_METADATA.DEM_METADATA_id field for a matching DEM_METADATA_id, returning either a DemMetadata object, or null if there is no such DEM_METADATA_id.
static java.util.Vector	getDemMetadataSearch(java.lang.String queryStr, java.sql.Connection connection) public static Vector getDemMetadataSearch(String query) Strings are searched in the DEM_METADATA.file_info field (case insensitve), and a Vector of DemMetadata objects is returned that match the search; possibly null, if no matches are found.
static java.util.Vector	getGrids(java.sql.Connection connection) Gets DemMetadata from the database and returns it as a Vector of Grid objects with DemMetadata objects.
static Point	getPoint(int zone, int easting, int northing, java.sql.Connection connection) getPoint takes the UTM zone, easting, and northing values of a target site.
static Point	getPointById(java.lang.String id, java.sql.Connection connection) Given the database id (which is the primary key field) of the record, this method returns a Point object for the point, factory method approach.
static Points	getPoints(int zone, int easting, int northing, int easting_meters, int northing_meters, java.sql.Connection connection) returns a Points object - factory method approach Note that some or all requested Points might not be in the database.
static StatisticalPoint	getStatisticalPoint(int zone, int easting, int northing, java.sql.Connection connection) getStatisticalPoint takes the UTM zone, easting, and northing values of a target site.

Methods inherited from class java.lang.Object

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

Constructor Detail

C5UTM

public C5UTM()

Method Detail

getPoint

public static Point getPoint(int zone,
                             int easting,
                             int northing,
                             java.sql.Connection connection)

getPoint takes the UTM zone, easting, and northing values of a target site. (And a connection object.) It returns a Point object describing the point, (factory method approach) Example: C5UTM.getPoint(zone, easting, northing, connection); This version of the function is designed to "snap to grid" finding the closest point that it can. The object returned will contain the actual UTM easting and northing that was found in the database. Returns null if point not found.

Parameters:

zone - the UTM zone

easting - the UTM easting

northing - the UTM northing

connection - the database connection object

Returns:

A Point object representing the result

See Also:

DbHelper, Point

getStatisticalPoint

public static StatisticalPoint getStatisticalPoint(int zone,
                                                   int easting,
                                                   int northing,
                                                   java.sql.Connection connection)

getStatisticalPoint takes the UTM zone, easting, and northing values of a target site. (And a connection object) It returns a StatisticalPoint object describing the point, (factory method approach) Example: C5UTM.getStatisticalPoint(zone, easting, northing, connection); This version of the function is designed to "snap to grid" finding the closest point that it can. The object returned will contain the actual UTM easting and northing that was found in the database. Returns null if the point in not in the UTM_COORD table, *and* if the point does not have a corresponding record (the statistics about the area surrouding the point) in the UTM_POINT_STATS table.

Parameters:

zone - the UTM zone

easting - the UTM easting

northing - the UTM northing

connection - the database connection object

Returns:

A Point object representing the result

Since:

2.0

See Also:

DbHelper, StatisticalPoint

findSimilarPoints

public static java.util.Vector<StatisticalPoint> findSimilarPoints(StatisticalPoint input,
                                                                   double tolerance,
                                                                   java.sql.Connection connection)

Given an input point and a connection object, returns a Vector of most similar points. This algorithm examines three metrics: It identifies points within +/- the tolerance argument of the standard deviation. It also matches the exact elevation percentile and the exact contiguous modality percentage. The points are sorted by the standard deviation value.

Parameters:

input - the input point

tolerance - a +/- range applied to the standard deviation metric

connection - the database connection object

Returns:

A Point object representing the result

Since:

2.0

See Also:

DbHelper, StatisticalPoint

getPointById

public static Point getPointById(java.lang.String id,
                                 java.sql.Connection connection)

Given the database id (which is the primary key field) of the record, this method returns a Point object for the point, factory method approach. Example: C5UTM.getPointById(a_32_character_md5_hash_string, connection);

Parameters:

id - the database id for the desired record

connection - the database connection object

Returns:

the Point

See Also:

DbHelper

getCoordinatePairElevArray

public static UtmCoordinatePairElev[][] getCoordinatePairElevArray(int zone,
                                                                   int easting,
                                                                   int northing,
                                                                   int easting_meters,
                                                                   int northing_meters,
                                                                   java.sql.Connection connection)

This method is similar to the getPoints method in this class, (which returns a more powerful Points object) in that it has the same method signature and performs a similar function, but has some notable differences. As of version 1.2, it is assumed that the DEM files are maintained in addition to the (same) data in the rdbms. DEMs are not very expensive to store, and are faster to process in many circumstances. Although living in the C5UTM class, this method will actually go to the files first for data if the data asked for is contiguous in the file. If not, it will go to the rdmbs for the data. Note that it returns a (two dimensional) array of a com.c5corp.c5dem type (UtmCoordinatePairElev), and not a com.c5corp.c5utm type. The raw dems don't have all of the data that the database does, (for example, an internal array of Point objects that have an id and dem_id field, or various statistical calculations and fields.) So given that this method may go to the file instead of the db, it returns the lowest common denominator type of the two potential return types.

Parameters:

zone - the UTM zone

easting - the UTM easting

northing - the UTM northing

easting_meters - meters east of easting-northing requested

northing_meters - meters north of easting-northing requested

connection - the database connection object

Returns:

an array representing the requested area, or null if the data could not be found.

Since:

1.0.3

See Also:

getPoints(int, int, int, int, int, java.sql.Connection), UtmCoordinatePairElev

findDem

public static DemMetadata findDem(int zone,
                                  int easting,
                                  int northing,
                                  int easting_meters,
                                  int northing_meters,
                                  java.sql.Connection connection)

Given an area represented by the methods parameters, a DemMetadata object representing a Dem that encloses the given area. Returns null if it can not determine that the given area is entirely enclosed by one Dem, indicating that (most likely) the area contains points from one or more Dems.

Parameters:

zone - the UTM zone

easting - the UTM easting

northing - the UTM northing

easting_meters - meters east of easting-northing requested

northing_meters - meters north of easting-northing requested

connection - the database connection object

Returns:

a Dem

Since:

1.0.3

getPoints

public static Points getPoints(int zone,
                               int easting,
                               int northing,
                               int easting_meters,
                               int northing_meters,
                               java.sql.Connection connection)

returns a Points object - factory method approach Note that some or all requested Points might not be in the database. the returned Points object will contain only as many as it could find meeting the criteria. Example: getPoints(zone, easting, northing, east_meters, north_meters, connection);
not implemented: Can't yet get interpolate points from neighboring UTM zones...

Parameters:

zone - the UTM zone

easting - the UTM easting

northing - the UTM northing

easting_meters - meters east of easting-northing requested

northing_meters - meters north of easting-northing requested

connection - the database connection object

Returns:

the Points object representing the area requested

See Also:

DbHelper

getDemMetadataSearch

public static java.util.Vector getDemMetadataSearch(java.lang.String queryStr,
                                                    java.sql.Connection connection)

public static Vector getDemMetadataSearch(String query) Strings are searched in the DEM_METADATA.file_info field (case insensitve), and a Vector of DemMetadata objects is returned that match the search; possibly null, if no matches are found. The search string can contain double quoted literals, otherwise the arguments are split on white space and search withed 'and' logic.

Parameters:

queryStr - the query string

connection - the database connection object

Returns:

a Vector of DemMetadata objects matching the query

See Also:

DbHelper

getAllDemMetadata

public static java.util.Vector<DemMetadata> getAllDemMetadata(java.sql.Connection connection)

gets all the Dem meta data objects from the database

Parameters:

connection - the database connection object

Returns:

a Vector of all DemMetadata records in the database

Since:

1.0.3

getGrids

public static java.util.Vector getGrids(java.sql.Connection connection)

Gets DemMetadata from the database and returns it as a Vector of Grid objects with DemMetadata objects. Each Grid contains contiguous DemMetadata objects.

Parameters:

connection - the database connection object

Returns:

Vector of Grid objects

Since:

2.0

See Also:

Grid

getDemMetadata

public static DemMetadata getDemMetadata(java.lang.String id,
                                         java.sql.Connection connection)

Searches the DEM_METADATA.DEM_METADATA_id field for a matching DEM_METADATA_id, returning either a DemMetadata object, or null if there is no such DEM_METADATA_id. (Point objects contain the DEM_METADATA_id of the dem they lie in...)

Parameters:

id - the query id

connection - the database connection object

Returns:

the DemMetadata matching id

See Also:

DbHelper

findExactDemNames

public static java.util.Vector findExactDemNames(java.lang.String str,
                                                 java.sql.Connection connection)

Vector findExactDemNames(String str, C5UTMconfs conf) Finds an exact match for a dem name from the file_info field of DEM_METADATA. This method will normally return a Vector with either 0 or 1 elements. The objects in the Vector are DemMetadata objects. If it returns more elements, you may wish to investigate that there is not a duplicate map in the database. If you have a confs object available, use this version.

Parameters:

str - the query string

connection - the database connection object

Returns:

the DemMetadata records exactly matching the query

See Also:

DemMetadata, DbHelper

findExactDemNames

public static java.util.Vector findExactDemNames(java.lang.String str,
                                                 C5UTMconfs confs,
                                                 java.sql.Connection connection)

Deprecated. since version 2.0

Vector findExactDemNames(String str) Finds an exact match for a dem name from the file_info field of DEM_METADATA. This method will normally return a Vector with either 0 or 1 element of type DemMetadata. If it returns more elements, you may wish to investigate that there is not a duplicate map in the database. This version was deprecated because the method was retooled to work without a confs object.

Parameters:

str - the query string

confs - the configuration object

connection - the database connection object

Returns:

the DemMetadata records exactly matching the query

See Also:

DemMetadata, C5UTMconfs, DbHelper

findDemNameContains

public static java.util.Vector findDemNameContains(java.lang.String str,
                                                   java.sql.Connection connection)

Vector findDemNameContains(String str, C5UTMconfs conf) This method will normally return a Vector with either 0 or more elements of type DemMetadata. It searches the file_info field of DEM_METADATA for a subsring containing the query string. If you have a confs object available, use this version. It is faster not to make a new C5UTMconfs.

Parameters:

str - the query string

connection - the database connection object

Returns:

Vector containing the records matching the query

See Also:

DemMetadata, C5UTMconfs, DbHelper

findDemNameContains

public static java.util.Vector findDemNameContains(java.lang.String str,
                                                   C5UTMconfs confs,
                                                   java.sql.Connection connection)

Deprecated. since version 2.0

Vector findDemNameContains(String str) This method will normally return a Vector with either 0 or more elements of type DemMetadata. It searches the file_info field of DEM_METADATA for a subsring containing the query string. This version was deprecated because the method was retooled to work without a confs object.

Parameters:

str - the query string

confs - not needed - deprecated function

connection - the database connection object

Returns:

Vector containing the records matching the query

See Also:

DemMetadata, DbHelper

deleteDem

public static java.lang.String deleteDem(java.lang.String id,
                                         C5UTMconfs confs)

String deleteDem(String id, C5UTMconfs conf) This method drops a dem from the database according to its id. The id can be found in the RECEIPT folder. Also deletes the receipt file.

Parameters:

id - the id to delete for

confs - the configuration object

Returns:

status string from MySQL

See Also:

C5UTMconfs, DbHelper

deleteDem

public static java.lang.String deleteDem(java.lang.String id)

boolean deleteDem(String id) This method drops a dem from the database according to its id. The id can be found in the RECEIPT folder. Also deletes the receipt file. If you have a confs object available, use boolean dropDem(int id, C5UTMconfs conf) This overloaded version is slower because it has the overhead of making a new C5UTMconfs.

Parameters:

id - the id of the DEM to delete

Returns:

status string from MySQL

See Also:

DbHelper