uk.ac.starlink.table.jdbc

## Class JDBCStarTable

- java.lang.Object
- - uk.ac.starlink.table.AbstractStarTable
  - - uk.ac.starlink.table.jdbc.JDBCStarTable

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, StarTable

      public class JDBCStarTable
      extends AbstractStarTable

  A StarTable implementation based on the results of an SQL query on a JDBC table.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `JDBCStarTable(Connector connx, java.lang.String sql)` Constructs a StarTable representing the data returned by an SQL query using a JDBC connections from a given source, with sequential access only.
    `JDBCStarTable(Connector connx, java.lang.String sql, boolean isRandom)` Constructs a StarTable representing the data returned by an SQL query using JDBC connections from a given source, optionally providing random access.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `getCell(long lrow, int icol)` The `AbstractStarTable` implementation of this method throws an `UnsupportedOperationException`, since unless otherwise provided there is no random access.
    `java.util.List<ValueInfo>` | `getColumnAuxDataInfos()` Goes through the table columns (`ColumnInfo` objects) and picks out all the AuxData items which exist, generalising where necessary and returning a union of them in alphabetical order by name.
    `int` | `getColumnCount()` Returns the number of columns in this table.
    `ColumnInfo` | `getColumnInfo(int icol)` Returns the object describing the data in a given column.
    `java.sql.Connection` | `getConnection()` Returns a JDBC Connection that can supply the data for this table.
    `java.lang.Object[]` | `getRow(long lrow)` The `AbstractStarTable` implementation of this method constructs a row by repeated invocation of `AbstractStarTable.getCell(long, int)`.
    `RowAccess` | `getRowAccess()` Returns an object which can provide random access to this table's data, if random access is implemented.
    `long` | `getRowCount()` Returns the number of rows in this table, if known.
    `RowSequence` | `getRowSequence()` Returns an object which can iterate over all the rows in the table sequentially.
    `java.lang.String` | `getSql()` Returns the text of the SQL query used for this table.
    `boolean` | `isRandom()` The `AbstractStarTable` implementation of this method returns `false`.
    `void` | `setRandom()` Ensures that this table provides random access.

    - ### Methods inherited from class uk.ac.starlink.table.AbstractStarTable

      `checkedLongToInt, close, getName, getParameters, getRowSplittable, getURL, setName, setParameters, setURL`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface uk.ac.starlink.table.StarTable

      `getParameterByName, setParameter`

- - ### Constructor Detail

    - #### JDBCStarTable

          public JDBCStarTable(Connector connx,
                               java.lang.String sql)
                        throws java.sql.SQLException

      Constructs a StarTable representing the data returned by an SQL query using a JDBC connections from a given source, with sequential access only.
      Parameters:
        `connx` - object which can supply JDBC connections
        `sql` - text of the SQL query
      Throws:
        `java.sql.SQLException`

    - #### JDBCStarTable

          public JDBCStarTable(Connector connx,
                               java.lang.String sql,
                               boolean isRandom)
                        throws java.sql.SQLException

      Constructs a StarTable representing the data returned by an SQL query using JDBC connections from a given source, optionally providing random access.

      This was initially written to take a `Connection` rather than a `Connector` object, but it seems that there are limits to the number of `ResultSet`s that can be simultaneously open on a `Connection`.

      Parameters:
        `connx` - object which can supply JDBC connections
        `sql` - text of the SQL query
        `isRandom` - whether this table needs to provide random access or not (there are costs associated with this)
      Throws:
        `java.sql.SQLException`

  - ### Method Detail

    - #### getColumnInfo

          public ColumnInfo getColumnInfo(int icol)

      Description copied from interface: `StarTable`
      Returns the object describing the data in a given column.
      Specified by:
        `getColumnInfo` in interface `StarTable`
      Specified by:
        `getColumnInfo` in class `AbstractStarTable`
      Parameters:
        `icol` - the column for which header information is required
      Returns:
        a ValueInfo object for column `icol`

    - #### getColumnAuxDataInfos

          public java.util.List<ValueInfo> getColumnAuxDataInfos()

      Description copied from class: `AbstractStarTable`
      Goes through the table columns (`ColumnInfo` objects) and picks out all the AuxData items which exist, generalising where necessary and returning a union of them in alphabetical order by name. Subclasses should override this if they can do better, for instance providing an order for the keys.
      Specified by:
        `getColumnAuxDataInfos` in interface `StarTable`
      Overrides:
        `getColumnAuxDataInfos` in class `AbstractStarTable`
      Returns:
        a list of all the auxiliary metadata `ValueInfo` items which in fact crop up in column metadata
      See Also:
        `DefaultValueInfo.getAuxData()`

    - #### getColumnCount

          public int getColumnCount()

      Description copied from interface: `StarTable`
      Returns the number of columns in this table.
      Specified by:
        `getColumnCount` in interface `StarTable`
      Specified by:
        `getColumnCount` in class `AbstractStarTable`
      Returns:
        the number of columns

    - #### getRowCount

          public long getRowCount()

      Description copied from interface: `StarTable`
      Returns the number of rows in this table, if known. If the number of rows cannot be (easily) determined, a value of -1 will be returned.
      Specified by:
        `getRowCount` in interface `StarTable`
      Specified by:
        `getRowCount` in class `AbstractStarTable`
      Returns:
        the number of rows, or -1

    - #### setRandom

          public void setRandom()
                         throws java.sql.SQLException

      Ensures that this table provides random access. Following this call the `isRandom` method will return true. Calling this method multiple times is harmless.
      Throws:
        `java.sql.SQLException`

    - #### isRandom

          public boolean isRandom()

      Description copied from class: `AbstractStarTable`
      The `AbstractStarTable` implementation of this method returns `false`.
      Specified by:
        `isRandom` in interface `StarTable`
      Overrides:
        `isRandom` in class `AbstractStarTable`
      Returns:
        `true` if table random access methods are available

    - #### getCell

          public java.lang.Object getCell(long lrow,
                                          int icol)
                                   throws java.io.IOException

      Description copied from class: `AbstractStarTable`
      The `AbstractStarTable` implementation of this method throws an `UnsupportedOperationException`, since unless otherwise provided there is no random access.
      Specified by:
        `getCell` in interface `StarTable`
      Overrides:
        `getCell` in class `AbstractStarTable`
      Parameters:
        `lrow` - the index of the cell's row
        `icol` - the index of the cell's column
      Returns:
        the contents of this cell
      Throws:
        `java.io.IOException` - if there is an error reading the data

    - #### getRow

          public java.lang.Object[] getRow(long lrow)
                                    throws java.io.IOException

      Description copied from class: `AbstractStarTable`
      The `AbstractStarTable` implementation of this method constructs a row by repeated invocation of `AbstractStarTable.getCell(long, int)`.
      Specified by:
        `getRow` in interface `StarTable`
      Overrides:
        `getRow` in class `AbstractStarTable`
      Parameters:
        `lrow` - the index of the row to retrieve
      Returns:
        an array of the objects in each cell in row `irow`
      Throws:
        `java.io.IOException` - if there is an error reading the data

    - #### getRowAccess

          public RowAccess getRowAccess()
                                 throws java.io.IOException

      Description copied from interface: `StarTable`
      Returns an object which can provide random access to this table's data, if random access is implemented. Each such returned object is safe for use within a single thread, but not in general from multiple threads concurrently.
      Specified by:
        `getRowAccess` in interface `StarTable`
      Overrides:
        `getRowAccess` in class `AbstractStarTable`
      Returns:
        new RowAccess
      Throws:
        `java.io.IOException` - if there is an error setting up access

    - #### getRowSequence

          public RowSequence getRowSequence()
                                     throws java.io.IOException

      Description copied from interface: `StarTable`
      Returns an object which can iterate over all the rows in the table sequentially. Each such returned object is safe for use within a single thread, but not in general from multiple threads concurrently.
      Specified by:
        `getRowSequence` in interface `StarTable`
      Specified by:
        `getRowSequence` in class `AbstractStarTable`
      Returns:
        new RowSequence
      Throws:
        `java.io.IOException` - if there is an error providing access

    - #### getConnection

          public java.sql.Connection getConnection()
                                            throws java.sql.SQLException

      Returns a JDBC Connection that can supply the data for this table.
      Returns:
        a JDBC Connection object
      Throws:
        `java.sql.SQLException`

    - #### getSql

          public java.lang.String getSql()

      Returns the text of the SQL query used for this table.
      Returns:
        the SQL query text