Package org.apache.sis.internal.sql.feature

Class Table

java.lang.Object
org.apache.sis.storage.AbstractResource
org.apache.sis.storage.AbstractFeatureSet
org.apache.sis.internal.sql.feature.Table
All Implemented Interfaces:
DataSet, FeatureSet, Resource
final class Table extends AbstractFeatureSet
Description of a table in the database, including columns, primary keys and foreigner keys. This class contains a FeatureType inferred from the table structure. The FeatureType contains an AttributeType for each table column, except foreigner keys which are represented by FeatureAssociationRoles.

Multi-threading

This class is immutable (except for the cache) and safe for concurrent use by many threads. The content of arrays in this class shall not be modified in order to preserve immutability.
Since:
1.0
Version:
1.2

  • Field Details

    • database

      final Database<?> database
      Information about the database (syntax for building SQL statements, …) together with a cache of CRS. Contains the provider of (pooled) connections to the database.

    • featureType

      final DefaultFeatureType featureType
      The structure of this table represented as a feature. Each feature attribute is a table column, except synthetic attributes like "sis:identifier". The feature may also contain associations inferred from foreigner keys that are not immediately apparent in the table.
      See Also:

    • query

      private final String query
      The SQL query to execute for fetching data, or null for querying the table identified by name. This is non-null only if the user explicitly specified a SQL query to execute.
      See Also:

    • name

      final TableReference name
      The name in the database of this Table object, together with its schema and catalog. The catalog and schema parts are optional and can be null, but the table name is mandatory.
      See Also:

    • attributes

      final Column[] attributes
      Attributes in feature instances, excluding operations and associations to other tables. Elements are in the order of columns declared in the SELECT <columns> statement. This array shall not be modified after construction.

      Columns may have alias if it was necessary to avoid name collisions. The alias is given by Column.propertyName and will be the name used in FeatureType.

    • primaryKey

      final PrimaryKey primaryKey
      The columns that constitute the primary key, or null if there is no primary key.

    • importedKeys

      final Relation[] importedKeys
      The primary keys of other tables that are referenced by this table foreign key columns. They are 0:1 relations. May be empty if there are no imported keys but never null.

    • exportedKeys

      final Relation[] exportedKeys
      The foreign keys of other tables that reference this table primary key columns. They are 0:N relations. May be empty if there are no exported keys but never null.

    • hasGeometry

      final boolean hasGeometry
      true if this table contains at least one geometry column.

    • hasRaster

      final boolean hasRaster
      true if this table contains at least one raster column.

    • attributeToColumns

      private Map<String,Column> attributeToColumns
      Map from attribute name to columns. This is built from #columns array when first needed.
      See Also:

    • adapter

      private FeatureAdapter adapter
      The converter of ResultSet rows to Feature instances. Created when first needed.
      See Also:

    • instanceForPrimaryKeys

      private WeakValueHashMap<?,Object> instanceForPrimaryKeys
      Feature instances already created for given primary keys. This map is used only when requesting feature instances by identifiers (not for iterating over all features) and those identifiers are primary keys. We create this map only for tables referenced by foreigner keys of other tables as enumerated by the Relation.Direction.IMPORT and Relation.Direction.EXPORT cases; not for arbitrary cross-reference cases. Values are usually Feature instances, but may also be Collection<Feature>.
      See Also:

    • isEnvelopeAnalyzed

      private boolean isEnvelopeAnalyzed
      true if getEnvelope() has been invoked at least once on this table. This is used for performing only once operations such as PosthreSQL ANALYZE.
      See Also:

  • Constructor Details

    • Table

      Table(Database<?> database, FeatureAnalyzer analyzer, String query) throws Exception
      Creates a description of the table analyzed by the given object.
      Parameters:
      database - information about the database (syntax for building SQL statements, …).
      analyzer - helper functions, e.g. for converting SQL types to Java types.
      query - the SQL query to use for fetching data, or null for querying the table identified by name.
      Throws:
      Exception

    • Table

      Table(Table parent)
      Creates a new table as a projection (subset of columns) of the given table.

  • Method Details

    • setDeferredSearchTables

      final void setDeferredSearchTables(Analyzer analyzer, Map<org.opengis.util.GenericName,Table> tables) throws DataStoreException
      Sets the search tables on all Relation instances for which this operation has been deferred. This happen when a table could not be obtained because of circular dependency. This method is invoked after all tables have been created in order to fill such holes.
      Parameters:
      tables - all tables created.
      Throws:
      DataStoreException

    • appendAll

      @Debug private static void appendAll(TreeTable.Node parent, Relation[] children, String arrow)
      Appends all children to the given parent. The children are added under the given node. If the children array is empty, then this method does nothing.
      Parameters:
      parent - the node where to add children.
      children - the children to add, or an empty array if none.
      arrow - the symbol to use for relating the columns of two tables in a foreigner key.

    • appendTo

      @Debug final void appendTo(TreeTable.Node parent)
      Creates a tree representation of this table for debugging purpose.
      Parameters:
      parent - the parent node where to add the tree representation.

    • toString

      public String toString()
      Formats a graphical representation of this table for debugging purpose. This representation can be printed to the standard output stream (for example) if the output device uses a monospaced font and supports Unicode.
      Overrides:
      toString in class Object

    • getIdentifier

      public final Optional<org.opengis.util.GenericName> getIdentifier()
      Returns the table identifier composed of catalog, schema and table name.
      Specified by:
      getIdentifier in interface Resource
      Overrides:
      getIdentifier in class AbstractFeatureSet
      Returns:
      the resource identifier inferred from feature type.
      See Also:

    • getType

      public final DefaultFeatureType getType()
      Returns the feature type inferred from the database structure analysis.
      Returns:
      description of common properties (never null).

    • getEnvelope

      public Optional<org.opengis.geometry.Envelope> getEnvelope() throws DataStoreException
      Returns an estimation of the envelope of all geometry columns in this table. The returned envelope shall contain at least the two-dimensional spatial components. Whether other dimensions (vertical and temporal) and present or not depends on the implementation.

      Departure from interface contract

      DataSet.getEnvelope() contract allows estimated envelope to be larger than actual envelope (similar to Java2D Shape.getBounds() contract), but smaller envelope are discouraged. Despite that, this method may return smaller envelopes because the computation is done using a subset of all data.

      Limitations

      The exact behavior is database-dependent. For example, PostGIS implementation assumes that all geometries in the same column are in the same CRS. If geometries in different rows use different CRS, coordinate transformations are not applied and the result is likely to be invalid. However if different column use different CRS, coordinate transformations between columns is applied and the result is in the CRS of the first column having at least one geometry.
      Specified by:
      getEnvelope in interface DataSet
      Overrides:
      getEnvelope in class AbstractResource
      Returns:
      an estimation of the spatiotemporal resource extent.
      Throws:
      DataStoreException - if an error occurred while reading or computing the envelope.

    • getColumn

      final Column getColumn(String xpath)
      Returns the column from an attribute name specified as XPath. Current implementation interprets the xpath value only as the attribute name, but a future implementation may parse something like a "table/column" syntax. It may be necessary with Table that are actually views generated by queries.
      Parameters:
      xpath - the XPath (currently only attribute name).
      Returns:
      column for the given XPath, or null if the specified attribute is not found.

    • getInverseOf

      final Relation getInverseOf(Relation exported, TableReference exportedOwner)
      If this table imports the inverse of the given relation, returns the imported relation. Otherwise returns null. This method is used for preventing infinite recursivity.
      Parameters:
      exported - the relation exported by another table.
      exportedOwner - exported.owner.name: table that contains the exported relation.
      Returns:
      the inverse of the given relation, or null if none.

    • instanceForPrimaryKeys

      final WeakValueHashMap<?,Object> instanceForPrimaryKeys()
      Returns a cache for fetching feature instances by identifier. The map is created when this method is first invoked. Keys are primary key values, typically as String or Integer instances or arrays of those if the keys use more than one column. Values are usually Feature instances, but may also be Collection<Feature>.

    • appendFromClause

      final void appendFromClause(SQLBuilder sql)
      Appends the catalog, schema and table name to the given builder after the "FROM" keyword.

    • countRows

      final long countRows(DatabaseMetaData metadata, boolean distinct, boolean approximate) throws SQLException
      Returns the number of rows, or -1 if unknown. Note that some database drivers returns 0, so it is better to consider 0 as "unknown" too (see FeatureIterator.estimatedSize). We do not cache this count because it may change at any time.
      Parameters:
      metadata - information about the database.
      distinct - whether to count distinct values instead of all values.
      approximate - whether approximate or outdated values are acceptable.
      Returns:
      number of rows (may be approximate), or -1 if unknown.
      Throws:
      SQLException

    • adapter

      final FeatureAdapter adapter(Connection connection) throws SQLException, InternalDataStoreException
      Returns the converter of ResultSet rows to Feature instances. The converter is created the first time that this method is invoked, then cached.
      Parameters:
      connection - source of database metadata to use if the adapter needs to be created.
      Throws:
      SQLException
      InternalDataStoreException

    • features

      public Stream<AbstractFeature> features(boolean parallel) throws DataStoreException
      Returns a stream of all features contained in this dataset.
      Parameters:
      parallel - true for a parallel stream (if supported), or false for a sequential stream.
      Returns:
      all features contained in this dataset.
      Throws:
      DataStoreException - if an error occurred while creating the stream.