Package org.kawanfw.sql.api.server

Interface DatabaseConfigurator

All Known Implementing Classes:
DefaultDatabaseConfigurator
public interface DatabaseConfigurator
Interface that defines the database configurations for AceQL HTTP.

The implemented methods will be called by AceQL when a client program, referred by a user username, asks for a JDBC operation from the Client side.

A concrete implementation should be developed on the server side in order to:

  • Define how to extract a JDBC Connection from a Connection Pool.
  • Define the directories where the Blobs/Clobs are located for upload and download.
  • Define some Java code to execute before/after a Connection.close().
  • Define the maximum number of rows that may be returned to the client.
  • Define the maximum length allowed for a Blob upload.
  • Define the Logger to use to trap server Exceptions.

Author:
Nicolas de Pomereu

  • Method Summary

    Modifier and Type Method Description
    void close​(Connection connection)
    Allows to define how to close the Connection acquired with getConnection(String) and return it to the pool.
    File getBlobsDirectory​(String username)
    Allows to define the directory into which Blobs/Clobs are uploaded by client side, and from which Blobs/Clobs are downloaded by client side.
    Connection getConnection​(String database)
    Attempts to establish a connection with an underlying data source.
    org.slf4j.Logger getLogger()
    Returns the SLF4J Logger that will be used by AceQL for logging: All Exceptions thrown by server side will be logged. Exceptions thrown are flattened when logged for compatible usage with tools like Logstash. It is not necessary nor recommended to implement this method; do it only if you want take control of the logging to modify the default characteristics of DefaultDatabaseConfigurator.getLogger().
    long getMaxBlobLength​(String username, String database)
    Allows to define the maximum length authorized for of a Blob to be uploaded.
    int getMaxRows​(String username, String database)
    Allows to define the maximum rows per request to be returned to the client.

  • Method Details

    • getConnection

      Connection getConnection​(String database) throws SQLException

      Attempts to establish a connection with an underlying data source.

      Parameters:
      database - the database name to get the connection from
      Returns:
      a Connection to the data source
      Throws:
      SQLException - if a database access error occurs

    • close

      void close​(Connection connection) throws SQLException
      Allows to define how to close the Connection acquired with getConnection(String) and return it to the pool.

      Most connection pool implementations just require to call Connection.close() to release the connection, but it is sometimes necessary for applications to add some operation before/after the close. This method allows you to add specific code before or after the close.

      It is not required to implement this method, because the default implementation DefaultDatabaseConfigurator.close(Connection) closes the connection with an explicit call to Connection.close().
      If you implement this method, you *must* close the connection.
      Parameters:
      connection - a connection to the data source
      Throws:
      SQLException - if a SQLException occurs

    • getMaxRows

      int getMaxRows​(String username, String database) throws IOException, SQLException
      Allows to define the maximum rows per request to be returned to the client. If this limit is exceeded, the excess rows are silently dropped.
      Parameters:
      username - the client username to check the max rows for.
      database - the database name as defined in the JDBC URL field
      Returns:
      the maximum rows per request to be returned to the client; zero means there is no limit
      Throws:
      IOException - if an IOException occurs
      SQLException - if a SQLException occurs

    • getMaxBlobLength

      long getMaxBlobLength​(String username, String database) throws IOException, SQLException
      Allows to define the maximum length authorized for of a Blob to be uploaded. If this limit is exceeded, an IOException is thrown This allows to prevent from DOS attacks that would saturate the AceQL server. 0 means there is no limit.
      Parameters:
      username - the client username
      database - the database name as defined in the JDBC URL field
      Returns:
      the maximum Blob length for upload, 0 means there is no limit
      Throws:
      IOException - if an IOException occurs
      SQLException - if a SQLException occurs

    • getBlobsDirectory

      File getBlobsDirectory​(String username) throws IOException, SQLException
      Allows to define the directory into which Blobs/Clobs are uploaded by client side, and from which Blobs/Clobs are downloaded by client side.
      See default implementation in: DefaultDatabaseConfigurator.getBlobsDirectory(String).
      Parameters:
      username - the client username
      Returns:
      the Blob/Clob upload and download directory for this username
      Throws:
      IOException - if an IOException occurs
      SQLException - if a SQLException occurs

    • getLogger

      org.slf4j.Logger getLogger() throws IOException
      Returns the SLF4J Logger that will be used by AceQL for logging:
      • All Exceptions thrown by server side will be logged.
      • Exceptions thrown are flattened when logged for compatible usage with tools like Logstash.
      It is not necessary nor recommended to implement this method; do it only if you want take control of the logging to modify the default characteristics of DefaultDatabaseConfigurator.getLogger().
      Returns:
      the Logger that will be used by AceQL logging;
      Throws:
      IOException - if an IOException occurs