# Class JDBCStarTable

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

All Implemented Interfaces:
  `Closeable, 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
Description
`JDBCStarTable(Connector connx, 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, 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

Modifier and Type
Method
Description
`Object`
`getCell(long lrow, int icol)`
The `AbstractStarTable` implementation of this method throws an `UnsupportedOperationException`, since unless otherwise provided there is no random access.
`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.
`Connection`
`getConnection()`
Returns a JDBC Connection that can supply the data for this table.
`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.
`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 AbstractStarTable

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

### Methods inherited from class Object

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

### Methods inherited from interface StarTable

`getParameterByName, setParameter`

## Constructor Details

### JDBCStarTable

public JDBCStarTable(Connector connx, String sql) throws 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:
  `SQLException`

### JDBCStarTable

public JDBCStarTable(Connector connx, String sql, boolean isRandom) throws 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:
  `SQLException`

## Method Details

### 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 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 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:
  `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 Object getCell(long lrow, int icol) throws 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:
  `IOException` - if there is an error reading the data

### getRow

public Object[] getRow(long lrow) throws 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:
  `IOException` - if there is an error reading the data

### getRowAccess

public RowAccess getRowAccess() throws 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:
  `IOException` - if there is an error setting up access

### getRowSequence

public RowSequence getRowSequence() throws 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:
  `IOException` - if there is an error providing access

### getConnection

public Connection getConnection() throws SQLException
Returns a JDBC Connection that can supply the data for this table.

Returns:
  a JDBC Connection object
Throws:
  `SQLException`

### getSql

public String getSql()
Returns the text of the SQL query used for this table.

Returns:
  the SQL query text