Class DataAccess

Object
DataAccess
All Implemented Interfaces:
Auto­Closeable
public class DataAccess extends Object implements AutoCloseable
Low-level accesses to the database content. This class provides a SQL Connection to the database, sometime protected by read or write lock (it may depend on which database driver is used). The connection can be used for custom SQL queries or updates. This class also provides helper method for performing queries or updates in the "SPATIAL_REF_SYS" table (the table name may vary depending on the spatial schema used by the database).

Usage

Data­Access instances are created by calls to SQLStore​.new­Data­Access(boolean). The Boolean argument tells whether the caller may perform write operations. That flag determines not only the read-only state of the connection, but also whether to acquire a read lock or a write lock if locking is needed.

This object shall be used in a try ... finally block for ensuring that the connection is closed and the lock (if any) released. Note that the SQL connection does not need to be closed by users, because it will be closed by the close() method of this data access object. Example:

SQLStore store = ...;
try (DataAccess dao = store.newDataAccess(false)) {
    Connection cnx = dao.getConnection();
    try (Statement stmt = cnx.createStatement()) {
        // Perform some SQL queries here.
    }
}

Multi-threading

This class is not thread safe. Each instance should be used by a single thread.
Since:
1.5

  • Field Details

    • store

      protected final SQLStore store
      The data store for which this object is providing data access. The value of this field is specified at construction time.
      See Also:

    • write

      protected final boolean write
      Whether this data access object will allow write operations. This flag also determines whether the lock to acquire (if any) will be a read lock or a write lock. The value of this field is specified at construction time.

  • Constructor Details

    • DataAccess

      protected DataAccess(SQLStore store, boolean write)
      Creates a new data access object for the given SQL store.
      Parameters:
      store - the data store for which this object is providing data access.
      write - whether write operations may be requested.
      See Also:

  • Method Details

    • getDataStore

      public SQLStore getDataStore()
      Returns the SQL store for which this object is providing low-level access.
      Returns:
      the SQL store that provided this data access object.

    • getConnection

      public final Connection getConnection() throws SQLException
      Returns the connection to the database. The connection is established on the first time that this method is invoked, then the same connection is returned until this data access object is closed. If a read or write lock is needed, it will be acquired before the connection is established.
      Returns:
      connection to the database.
      Throws:
      SQLException - if the connection cannot be established.

    • findCRS

      public CoordinateReferenceSystem findCRS(int srid) throws DataStoreException
      Returns the coordinate reference system associated to the given identifier. The spatial reference system identifiers (SRID) are the primary keys of the "SPATIAL_REF_SYS" table (the name of that table may vary depending on which spatial schema standard is used). Those identifiers are specific to each database and are not necessarily related to EPSG codes. They should be considered as opaque identifiers.

      Undefined CRS

      Some standards such as Geopackage define 0 as "undefined geographic CRS" and -1 as "undefined Cartesian CRS". This method returns null for all undefined CRS, regardless their type. No default value is returned because this class cannot guess the datum and units of measurement of an undefined CRS. All SRID equal or less than zero are considered undefined.

      Axis order

      Some standards such as Geopackage mandate (east, north) axis order. SQLStore uses the axis order as defined in the WKT descriptions of the "SPATIAL_REF_SYS" table. No reordering is applied. It is data producer's responsibility to provide definitions with the expected axis order.
      Parameters:
      srid - a primary key value of the "SPATIAL_REF_SYS" table.
      Returns:
      the CRS associated to the given SRID, or null if the given SRID is a code explicitly associated to an undefined CRS.
      Throws:
      No­Such­Data­Exception - if no CRS is associated to the given SRID.
      Data­Store­Referencing­Exception - if the CRS definition cannot be parsed.
      Data­Store­Exception - if the query failed for another reason.

    • findSRID

      public int findSRID(CoordinateReferenceSystem crs) throws DataStoreException
      Returns the SRID associated to the given spatial reference system. This method is the converse of find­CRS(int).

      Potential write operation

      If the write argument given at construction time was true, then this method is allowed to add a new row in the "SPATIAL_REF_SYS" table if the given CRS is not found.
      Parameters:
      crs - the CRS for which to find a SRID, or null.
      Returns:
      SRID for the given CRS, or 0 if the given CRS was null.
      Throws:
      Data­Store­Exception - if an SQL error, parsing error or other error occurred.

    • getLocale

      public Locale getLocale(Locale.Category category)
      Returns the locale for the usages identified by the given category. If the category is DISPLAY, then this method returns Data­Store​.get­Locale(). If the category is FORMAT, then this method returns SQLStore​.content­Locale. Otherwise this method returns null.
      Parameters:
      category - the usage of the desired locale.
      Returns:
      locale for the given usage, or null for the default.

    • close

      public void close() throws SQLException
      Closes the connection and release the read or write lock (if any).
      Specified by:
      close in interface Auto­Closeable
      Throws:
      SQLException - if an error occurred while closing the connection.