Class AuthorityCodes

java.lang.Object
org.apache.sis.internal.util.AbstractMap<String,String>
org.apache.sis.referencing.factory.sql.AuthorityCodes
All Implemented Interfaces:
Serializable, Map<String,String>

final class AuthorityCodes extends AbstractMap<String,String> implements Serializable
A map of EPSG authority codes as keys and object names as values. This map requires a living connection to the EPSG database.

Serialization

Serialization of this class stores a copy of all authority codes. The serialization does not preserve any connection to the database.

Garbage collection

This method does not implement AutoCloseable because the same instance may be shared by many users, since EPSGDataAccess.getAuthorityCodes(Class) caches AuthorityCodes instances. Furthermore, we can not rely on the users closing AuthorityCodes themselves because this is not part of the usual contract for Java collection classes (we could document that recommendation in method Javadoc, but not every developers read Javadoc). Relying on the garbage collector for disposing this resource is far from ideal, but alternatives are not very convincing either (load the same codes many time, have the risk that users do not dispose resources, have the risk to return to user an already closed AuthorityCodes instance).
Since:
0.7
Version:
1.2
See Also:
  • Field Details

    • MAX_CODE

      private static final int MAX_CODE
      Highest code value (inclusive) that this AuthorityCodes support during iterations. This is based on the upper value of the highest range of codes once used by EPSG.
      See Also:
    • ALL

      private static final int ALL
      Index in the sql and statements arrays.
      See Also:
    • ONE

      private static final int ONE
      Index in the sql and statements arrays.
      See Also:
    • factory

      private final transient EPSGDataAccess factory
      The factory which is the owner of this map. One purpose of this field is to prevent garbage collection of that factory as long as this map is in use. This is required because CloseableReference.dispose() closes the JDBC connections.
    • type

      final Class<?> type
      The interface of referencing objects for which this map contains the code. May be a super-interface of the type specified to the constructor.
    • isProjection

      private final transient boolean isProjection
      true if type is assignable to Projection.
    • sql

      private final transient String[] sql
      The SQL commands that this AuthorityCodes may need to execute. In this array:
      • sql[ALL] is a statement for querying all codes.
      • sql[ONE] is a statement for querying a single code. This statement is similar to sql[ALL] with the addition of a WHERE clause.
    • statements

      private final transient Statement[] statements
      The JDBC statements for the SQL commands in the sql array, created when first needed. All usages of those statements shall be synchronized on the factory. This array will also be stored in CloseableReference for closing the statements when the garbage collector detected that AuthorityCodes is no longer in use.
    • results

      private transient ResultSet results
      The result of statements[ALL], created only if requested. The codes will be queried at most once and cached in the codes list.

      Note that if this result set is not closed explicitly, it will be closed implicitly when statements[ALL] will be closed. This is because JDBC specification said that closing a statement also close its result set.

    • codes

      private transient IntegerList codes
      A cache of integer codes. Created only if the user wants to iterate over all codes or asked for the map size.
  • Constructor Details

    • AuthorityCodes

      AuthorityCodes(Connection connection, TableInfo table, Class<?> type, EPSGDataAccess factory) throws SQLException
      Creates a new map of authority codes for the specified type.
      Parameters:
      connection - the connection to the EPSG database.
      table - the table to query.
      type - the type to query.
      factory - the factory originator.
      Throws:
      SQLException
  • Method Details

    • createReference

      final CloseableReference createReference()
      Creates a weak reference to this map. That reference will also be in charge of closing the JDBC statements when the garbage collector determined that this AuthorityCodes instance is no longer in use. See class Javadoc for more information.
    • filter

      private boolean filter(int code) throws SQLException
      Returns true if the specified code should be included in this map.
      Throws:
      SQLException
    • getCodeAt

      private int getCodeAt(int index) throws SQLException
      Returns the code at the given index, or -1 if the index is out of bounds.
      Parameters:
      index - index of the code to fetch.
      Returns:
      the code at the given index, or -1 if out of bounds.
      Throws:
      SQLException - if an error occurred while querying the database.
    • isEmpty

      public boolean isEmpty()
      Returns true if this map contains no element. This method fetches at most one row instead of counting all rows.
      Specified by:
      isEmpty in interface Map<String,String>
      Overrides:
      isEmpty in class AbstractMap<String,String>
      Returns:
      true if this map contains no element.
    • size

      public int size()
      Counts the number of elements in this map.
      Specified by:
      size in interface Map<String,String>
      Overrides:
      size in class AbstractMap<String,String>
    • get

      public String get(Object code)
      Returns the object name associated to the given authority code, or null if none. If there is no name for the type of object being queried, then this method returns the code itself.
      Specified by:
      get in interface Map<String,String>
      Parameters:
      code - the code for which to get the description. May be a string or an integer.
      Returns:
      the description for the given code, or null if none.
    • entryIterator

      public AbstractMap.EntryIterator<String,String> entryIterator()
      Returns an iterator over the entries.
      Specified by:
      entryIterator in class AbstractMap<String,String>
      Returns:
      an iterator over the entries in this map, or null.
    • toString

      public String toString()
      Returns a string representation of this map for debugging purpose. This method does not let the default implementation format all entry, since it would be a costly operation.
      Overrides:
      toString in class AbstractMap<String,String>
      Returns:
      a string representation of this map.
    • factoryFailure

      private BackingStoreException factoryFailure(SQLException exception)
      Invoked when a SQL statement cannot be executed, or the result retrieved.
    • writeReplace

      protected Object writeReplace() throws ObjectStreamException
      Returns a serializable copy of this set. This method is invoked automatically during serialization. The serialized map of authority codes is disconnected from the underlying database.
      Throws:
      ObjectStreamException