Spatial DataBlade
JAVA API v8.21

com.ibm.spatial.srs
Class CoordRefManager

java.lang.Object
  extended by com.ibm.spatial.srs.CoordRefManager

public class CoordRefManager
extends java.lang.Object

This class contains methods to create and handle CoordRef (coordinate reference) objects.

A CoordRefManager is normally associated with a particular database where the IBM Informix Spatial DataBlade module has been registered. In this database, the spatial_references table (created during the DataBlade module registration) stores spatial reference system data. The spatial reference ID (srid) is the unique key for the record in the spatial_references table describing a particular spatial reference system. All spatial reference systems used in this database must have a record in the spatial_references table. Also, all geometries in a spatial column must use the same spatial reference system.

CoordRefManager can retrieve spatial reference systems from the database using their srid. CoordRefManager can also create and store user-defined spatial reference systems into the database.

CoordRefManager creates a local cache of objects that are in use, that is CoordRef objects that are referenced by existing Geometry instances. The following methods operate with the "CoordRef's in use" cache:

Note that the Enumerations returned by the findXXX() methods are not fail-fast in the sense Iterators are used by the java.util package. The Enumerations contain a "snapshot" of the CoordRefmanager and the database at the moment the find method is called, and do not reflect later changes in the cache or database.


Method Summary
 java.util.Enumeration find(CoordRef cr, int flags)
          Retrieves an enumeration of CoordRef objects which have a given combination of srtext, authoritative name / id, extent.
 java.util.Enumeration findByAuth(java.lang.String authName, java.lang.Integer authId)
          Retrieves an enumeration of CoordRef objects with a given authoritative name and id.
 java.util.Enumeration findByDesc(java.lang.String description)
          Retrieves an enumeration of CoordRef objects with a given description.
 java.util.Enumeration findBySrtext(java.lang.String srtext)
          Retrieves an enumeration of CoordRef objects with a given srtext.
 CoordRef get(int srid)
          Retrieves a coordinate reference with a given srid.
 java.util.Enumeration getAll()
          Retrieves an enumeration of the CoordRef objects in use (cached) by this CoordRefManager.
 java.util.Enumeration getAllSrids()
          Retrieves an enumeration of the srid's of the CoordRef objects in use (cached) by this CoordRefManager.
 java.sql.Connection getConnection()
          Returns the current database connection.
static CoordRefManager getInstance()
          Returns an instance of CoordRefManager.
 CoordRef put(CoordRef cr)
          Makes the given CoordRef object attributes permanent, by storing them into the underlying database, and in this object's cache.
 void refresh()
          Refreshes the cached coordinate reference objects with data from the underlying database.
 void remove(int srid)
          Removes the coordinate reference specified by srid from this object's in-use cache and, if the current connection is not null, from the database.
 void removeFromCache(int srid)
          Removes the coordinate reference specified by srid from this object's in-use cache.
 void setConnection(java.sql.Connection conn)
          Setup the connection to the database.
 int size()
          Returns the number of objects in the cache.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

setConnection

public void setConnection(java.sql.Connection conn)
Setup the connection to the database. The connection must be under any user who has access to table SDE.SPATIAL_REFERENCES. The connection is necessary for this object to be able to access spatial reference system data from the database.

Parameters:
conn - The database connection object
See Also:
getConnection()

getConnection

public java.sql.Connection getConnection()
Returns the current database connection.

Returns:
The database connection object
See Also:
setConnection(java.sql.Connection)

getInstance

public static CoordRefManager getInstance()
Returns an instance of CoordRefManager. This implementation always returns the same instance.

Returns:
an instance of CoordRefManager.

get

public CoordRef get(int srid)
             throws SpatialException
Retrieves a coordinate reference with a given srid. The coordinate reference is first searched in the local cache. If it is not found, then the underlying spatial database is queried for the srid. A database connection must be first setup, otherwise this method may throw a SpatialException error.

Parameters:
srid - The spatial reference system id
Returns:
a read-only CoordRef object identified by srid, or null if the coordinate reference is not in the cache or in the database.
Throws:
SpatialException - wrapping a SQLException object, if a database error occurs
See Also:
setConnection(java.sql.Connection)

findByAuth

public java.util.Enumeration findByAuth(java.lang.String authName,
                                        java.lang.Integer authId)
                                 throws SpatialException
Retrieves an enumeration of CoordRef objects with a given authoritative name and id. The local cache is first searched, then the underlying spatial database is queried and the two results are merged into the final result.

A database connection must be first setup, otherwise this method may throw a SpatialException error.

This method internally calls { @link #find(CoordRef, int) find(CoordRef, int) }.

Parameters:
authName - The authoritative name (for example "EPSG"). A null authoritative name corresponds to a NULL value in the auth_name column of the spatial_references table.
authId - The authoritative id (for example 4267). A null authoritative is corresponds to a NULL value in the auth_srid column of the spatial_references table.
Returns:
an enumeration of read-only CoordRef objects identified by the authoritative name and id; the enumeration is empty if no coordinate reference is found in the cache or in the database.
Throws:
SpatialException - wrapping a SQLException object, if a database error occurs
See Also:
find(CoordRef, int)

findBySrtext

public java.util.Enumeration findBySrtext(java.lang.String srtext)
                                   throws SpatialException
Retrieves an enumeration of CoordRef objects with a given srtext. The local cache is first searched, then the underlying spatial database is queried and the two results are merged into the final result.

A database connection must be first setup, otherwise this method may throw a SpatialException error.

This method internally calls { @link #find(CoordRef, int) find(CoordRef, int) }.

Parameters:
srtext - The well known text representation of the coordinate reference system.
Returns:
an enumeration of read-only CoordRef objects identified by the srtext field; the enumeration is empty if no coordinate reference is found in the cache or in the database.
Throws:
SpatialException - wrapping a SQLException object, if a database error occurs
See Also:
find(CoordRef, int)

findByDesc

public java.util.Enumeration findByDesc(java.lang.String description)
                                 throws SpatialException
Retrieves an enumeration of CoordRef objects with a given description. The local cache is first searched, then the underlying spatial database is queried and the two results are merged into the final result.

A database connection must be first setup, otherwise this method may throw a SpatialException error.

This method internally calls { @link #find(CoordRef, int) find(CoordRef, int) }.

Parameters:
description - The coordinate reference description.
Returns:
an enumeration of read-only CoordRef objects identified by the given description; the enumeration is empty if no coordinate reference is found in the cache or in the database.
Throws:
SpatialException - wrapping a SQLException object, if a database error occurs
See Also:
find(com.ibm.spatial.srs.CoordRef, int)

find

public java.util.Enumeration find(CoordRef cr,
                                  int flags)
                           throws SpatialException
Retrieves an enumeration of CoordRef objects which have a given combination of srtext, authoritative name / id, extent. The local cache is first searched, then the underlying spatial database is queried and the two results are merged into the final result.

A database connection must be first setup, otherwise this method may throw a SpatialException error.

Parameters:
cr - A CoordRef object holding the required field values. If null, then the method returns an empty Enumeration.
flags - The search criteria, indicated by a combination of the following values:
  • { @link CoordRef#SRTEXT CoordRef.SRTEXT } - search for objects having the same well known text representation as cr
  • { @link CoordRef#AUTH CoordRef.AUTH } - search for objects having the same authName and authSrid fields as cr
  • { @link CoordRef#DESC CoordRef.DESC } - search for objects having the same description as cr
  • { @link CoordRef#EXTENT CoordRef.EXTENT } - search for objects having equivalent extents as cr
  • .
If none of the flags above is set then all the CoordRef objects in the database are returned.
Returns:
an enumeration of read-only CoordRef objects returned by the search operation
Throws:
SpatialException - wrapping a SQLException object, if a database error occurs
See Also:
CoordRef.sameAs(com.ibm.spatial.srs.CoordRef, int)

getAll

public java.util.Enumeration getAll()
Retrieves an enumeration of the CoordRef objects in use (cached) by this CoordRefManager.

Returns:
an enumeration of the CoordRef objects in use by this object

getAllSrids

public java.util.Enumeration getAllSrids()
Retrieves an enumeration of the srid's of the CoordRef objects in use (cached) by this CoordRefManager.

Returns:
an enumeration of the srid's in use by this object

put

public CoordRef put(CoordRef cr)
             throws SpatialException
Makes the given CoordRef object attributes permanent, by storing them into the underlying database, and in this object's cache.

If the argument's srid has not been set to a specific value, or if CoordRef.unsetSrid has been previously called on the argument, then the following applies:

If the argument's srid has been previously assigned to a specific value, then the following applies:

Users should pass CoordRef objects with "unset" srid's in an attempt to store new coordinate references, and objects whose srid's have been previously set to a specific value in an attempt to modify the coordinate reference identified by the srid.

The method returns the reference of a read-only CoordRef object similar to the one passed as argument, which is stored in this CoordRefManager's cache. Any attempt to modify the returned object using setXXX members will fail and an UnsupportedOperationException will be thrown.

A database connection must be first set, otherwise this method will throw a SpatialException error.

Parameters:
cr - A CoordRef object holding the spatial reference system that will be cached
Returns:
A read-only CoordRef object, stored in cache, similar to the coordinate reference passed as argument.
Throws:
SpatialException - wrapping a SQLException object, if a database error occurs
See Also:
setConnection(java.sql.Connection)

remove

public void remove(int srid)
            throws SpatialException
Removes the coordinate reference specified by srid from this object's in-use cache and, if the current connection is not null, from the database.

After the coordinate reference is removed from both cache and database, geometries holding a reference to this CoordRef object will expose the following behavior:

Parameters:
srid - The id of the coordinate reference to be removed.
Throws:
SpatialException - wrapping a SQLException object, if a database error occurs

removeFromCache

public void removeFromCache(int srid)
                     throws SpatialException
Removes the coordinate reference specified by srid from this object's in-use cache.

After the coordinate reference is removed, newly created geometry objects referring to this srid will internally read the SRS from the database again using CoordRefManager.get().

Parameters:
srid - The srid of the CoordRef object to be removed.
Throws:
SpatialException - wrapping a SQLException, if a database error occurs
See Also:
get(int)

refresh

public void refresh()
             throws SpatialException
Refreshes the cached coordinate reference objects with data from the underlying database. If a cached object is not found in the database, then the object is removed from the cache.

This method may be used for error recovery and

Throws:
SpatialException - wrapping a SQLException object, if a database error occurs

size

public int size()
Returns the number of objects in the cache.

Returns:
the number of objects in the cache

Spatial DataBlade
JAVA API v8.21


Licensed Materials - Property of IBM
Copyright IBM Corp. 2002, 2012 All Rights Reserved.