Package org.odpi.openmetadata.adapters.connectors.resource.jdbc

Class JDBCResourceConnector

java.lang.Object
org.odpi.openmetadata.frameworks.connectors.Connector
org.odpi.openmetadata.frameworks.connectors.ConnectorBase
org.odpi.openmetadata.adapters.connectors.resource.jdbc.JDBCResourceConnector
All Implemented Interfaces:
AuditLoggingComponent, SecureConnectorExtension, VirtualConnectorExtension
public class JDBCResourceConnector extends ConnectorBase implements AuditLoggingComponent
JDBCResourceConnector provides a resource connector to work with JDBC Databases. A JDBC Connection carries a single database transaction and must not be used by two threads at once, so the connector dispenses connections from a pool via a data source object. The data source is a separate object rather than this connector itself because DataSource.getConnection() clashes with ConnectorBase.getConnection() - two methods with the same signature cannot differ only by return type.

The pool is a HikariDataSource. Callers therefore obtain a connection for the duration of one unit of work and must close it when that unit of work ends - ideally with try-with-resources: 
     try (Connection jdbcConnection = jdbcResourceConnector.getDataSource().getConnection())
     {
         ... statements ...

         jdbcConnection.commit();   // only if the unit of work made changes
     }
Closing returns the connection to the pool; it does not close the network connection. Because the connector runs with auto-commit disabled, the pool rolls back any transaction still open when a connection is returned, so a caller that forgets to commit loses its changes rather than leaving the connection idle-in-transaction.

A caller that never closes will exhaust the pool. Set the jdbcConnectionLeakThreshold configuration property to have the pool log a stack trace naming any caller that holds a connection for too long.

  • Constructor Details

    • JDBCResourceConnector

      public JDBCResourceConnector()

  • Method Details

    • setAuditLog

      public void setAuditLog(AuditLog auditLog)
      Receive an audit log object that can be used to record audit log messages. The caller has initialized it with the correct component description and log destinations.
      Specified by:
      setAuditLog in interface AuditLoggingComponent
      Parameters:
      auditLog - audit log object

    • getConnectorComponentDescription

      public ComponentDescription getConnectorComponentDescription()
      Return the component description that is used by this connector in the audit log.
      Specified by:
      getConnectorComponentDescription in interface AuditLoggingComponent
      Returns:
      id, name, description, wiki page URL.

    • start

      public void start() throws ConnectorCheckedException, UserNotAuthorizedException
      Indicates that the connector is completely configured and can begin processing.
      Overrides:
      start in class ConnectorBase
      Throws:
      ConnectorCheckedException - the connector detected a problem.
      UserNotAuthorizedException - the connector was disconnected before/during start

    • setConfigurationProperty

      public void setConfigurationProperty(String propertyName, Object propertyValue)
      Supply a configuration property value on behalf of this connector. This allows a connector that embeds a JDBCResourceConnector to pass a matching property from its own configuration straight through, so that a setting such as JDBCConfigurationProperty.JDBC_MAXIMUM_POOL_SIZE can be tuned where the hosting connector is configured rather than only on the embedded connection.

      This must be called before start(), since that is when the pool is built from these properties.

      A value passed down by the host replaces any value already on this connector's own connection. The value on the connection is typically supplied by a template or content pack and acts as the default; the host's configuration is where a deployment can be tuned, so it has to be able to override that default. Passing null changes nothing, so a host that does not set the property leaves the connection's own value in place.
      Parameters:
      propertyName - name of the configuration property
      propertyValue - value to use - ignored if null

    • getDatabaseName

      public String getDatabaseName()
      Return the name of the database.
      Returns:
      string name

    • getDataSource

      public DataSource getDataSource()
      Return the DataSource implementation for this database. This supports creating the connection to the database. Notice that DataSources are created per thread.
      Returns:
      DataSource

    • addDatabaseDefinitions

      public void addDatabaseDefinitions(Connection jdbcConnection, List<String> ddlStatements) throws PropertyServerException
      Issue the supplied DDL statements.
      Parameters:
      jdbcConnection - connection to use
      ddlStatements - statements to execute
      Throws:
      PropertyServerException - problem communicating with the database

    • issueSQLCommand

      public void issueSQLCommand(Connection jdbcConnection, String sqlCommand) throws PropertyServerException
      Issue a SQL command that expects no results.
      Parameters:
      jdbcConnection - connection to use
      sqlCommand - command to issue
      Throws:
      PropertyServerException - something went wrong

    • getLatestRow

      public Map<String,JDBCDataValue> getLatestRow(Connection jdbcConnection, String tableName, String identifierColumnName, String identifierColumnValue, String timestampColumnName, Map<String,Integer> columnNameTypeMap) throws PropertyServerException
      Retrieve the row with the requested identifier and with the latest timestamp.
      Parameters:
      jdbcConnection - connection to use
      tableName - name of the table to query
      identifierColumnName - name of the column with the identifier in it
      identifierColumnValue - value of the identifier to match on
      timestampColumnName - name of the column with the timestamp
      columnNameTypeMap - map of resulting column names and values to include in the results
      Returns:
      Map of column names to data values that represent the requested row
      Throws:
      PropertyServerException - there was a problem calling the database

    • getMatchingRow

      public Map<String,JDBCDataValue> getMatchingRow(Connection jdbcConnection, String tableName, String whereClause, Map<String,Integer> columnNameTypeMap) throws PropertyServerException
      Retrieve the row that matches the where clause.
      Parameters:
      jdbcConnection - connection to use
      tableName - name of the table to query
      whereClause - condition describing how to match the desired columns
      columnNameTypeMap - map of resulting column names and values to include in the results
      Returns:
      row consisting of column names to data values that represent the requested row
      Throws:
      PropertyServerException - there was a problem calling the database

    • getMatchingRows

      public List<Map<String,JDBCDataValue>> getMatchingRows(Connection jdbcConnection, String tableName, String whereClause, Map<String,Integer> columnNameTypeMap) throws PropertyServerException
      Retrieve the row with the requested identifier and with the latest timestamp.
      Parameters:
      jdbcConnection - connection to use
      tableName - name of the table to query
      whereClause - condition describing how to match the desired columns
      columnNameTypeMap - map of resulting column names and values to include in the results
      Returns:
      list of rows consisting of column names to data values that represent the requested row
      Throws:
      PropertyServerException - there was a problem calling the database

    • getMatchingRows

      public List<Map<String,JDBCDataValue>> getMatchingRows(Connection jdbcConnection, String sqlCommand, Map<String,Integer> columnNameTypeMap) throws PropertyServerException
      Retrieve the row with the requested identifier and with the latest timestamp.
      Parameters:
      jdbcConnection - connection to use
      sqlCommand - condition describing how to match the desired columns
      columnNameTypeMap - map of resulting column names and values to include in the results
      Returns:
      list of rows consisting of column names to data values that represent the requested row
      Throws:
      PropertyServerException - there was a problem calling the database

    • getRowCount

      public int getRowCount(Connection jdbcConnection, String tableName) throws PropertyServerException
      Retrieve the number of rows in the table.
      Parameters:
      jdbcConnection - connection to use
      tableName - name of the table to query
      Returns:
      number of rows in the named table
      Throws:
      PropertyServerException - there was a problem calling the database

    • countMatchingRows

      public long countMatchingRows(Connection jdbcConnection, String sqlCommand) throws PropertyServerException
      Retrieve the number of rows that would be returned by the supplied SQL query (which should be a "SELECT COUNT(...) FROM ... WHERE ..." style command). This allows a caller to reuse a WHERE clause built for a row-fetching query, without fetching and materializing every matching row.
      Parameters:
      jdbcConnection - connection to use
      sqlCommand - the full "SELECT COUNT(...)" SQL command to execute
      Returns:
      number of rows matching the supplied SQL command
      Throws:
      PropertyServerException - there was a problem calling the database

    • getRows

      public List<Map<String,JDBCDataValue>> getRows(Connection jdbcConnection, String tableName, Map<String,Integer> columnNameTypeMap) throws PropertyServerException
      Retrieve the row with the requested identifier and with the latest timestamp.
      Parameters:
      jdbcConnection - connection to use
      tableName - name of the table to query
      columnNameTypeMap - map of resulting column names and values to include in the results
      Returns:
      list of rows consisting of column names to data values that represent the requested row
      Throws:
      PropertyServerException - there was a problem calling the database

    • getUnmappedRows

      public List<Map<String,Object>> getUnmappedRows(Connection jdbcConnection, String tableName) throws PropertyServerException
      Retrieve the row with the requested identifier and with the latest timestamp.
      Parameters:
      jdbcConnection - connection to use
      tableName - name of the table to query
      Returns:
      list of rows consisting of column names to data values that represent the requested row
      Throws:
      PropertyServerException - there was a problem calling the database

    • doesTableExist

      public boolean doesTableExist(Connection jdbcConnection, String tableName) throws PropertyServerException
      Return whether a table exists or not.
      Parameters:
      jdbcConnection - connection to use
      tableName - name of the table to query
      Returns:
      boolean
      Throws:
      PropertyServerException - there was a problem calling the database

    • insertRowIntoTable

      public void insertRowIntoTable(Connection jdbcConnection, String tableName, Map<String,JDBCDataValue> columnNameValueMap) throws PropertyServerException
      Prepare an INSERT SQL statement with all the columns for the new row filled out.
      Parameters:
      jdbcConnection - connection to use
      tableName - name of the table where the row is to be added
      columnNameValueMap - column names, values and types
      Throws:
      PropertyServerException - problem executing the command

    • insertRowsIntoTable

      public void insertRowsIntoTable(Connection jdbcConnection, String tableName, List<Map<String,JDBCDataValue>> rows) throws PropertyServerException
      Prepare an INSERT SQL statement with all the columns for each of the new rows filled out.
      Parameters:
      jdbcConnection - connection to use
      tableName - name of the table where the row is to be added
      rows - list of column names, values and types
      Throws:
      PropertyServerException - problem executing the command

    • disconnect

      public void disconnect() throws ConnectorCheckedException
      Free up any resources held since the connector is no longer needed.
      Overrides:
      disconnect in class ConnectorBase
      Throws:
      ConnectorCheckedException - the connector detected a problem.