# Class DataAccess

Object
DataAccess

All Implemented Interfaces:
  `AutoCloseable`

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

`DataAccess` instances are created by calls to `SQLStore​.newDataAccess(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 Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final SQLStore`
  `store`
  The data store for which this object is providing data access.
  `protected final boolean`
  `write`
  Whether this data access object will allow write operations.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `DataAccess(SQLStore store, boolean write)`
  Creates a new data access object for the given SQL store.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Closes the connection and release the read or write lock (if any).
  `CoordinateReferenceSystem`
  `findCRS(int srid)`
  Returns the coordinate reference system associated to the given identifier.
  `int`
  `findSRID(CoordinateReferenceSystem crs)`
  Returns the SRID associated to the given spatial reference system.
  `final Connection`
  `getConnection()`
  Returns the connection to the database.
  `SQLStore`
  `getDataStore()`
  Returns the SQL store for which this object is providing low-level access.
  `Locale`
  `getLocale(Locale​.Category category)`
  Returns the locale for the usages identified by the given category.

  ### Methods inherited from class Object

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

- ## 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:
      - `getDataStore()`

  - ### 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:
      - `SQLStore​.newDataAccess(boolean)`

- ## 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:
      `NoSuchDataException` - if no CRS is associated to the given SRID.
      `DataStoreReferencingException` - if the CRS definition cannot be parsed.
      `DataStoreException` - 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 `findCRS(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:
      `DataStoreException` - 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 `DataStore​.getLocale()`. If the category is `FORMAT`, then this method returns `SQLStore​.contentLocale`. 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 `AutoCloseable`
    Throws:
      `SQLException` - if an error occurred while closing the connection.