Holger's Java API

## com.antelmann.sql
Class Connector

    java.lang.Object
      com.antelmann.sql.Connector

All Implemented Interfaces:
  Factory<Connection>

    @ThirdParty(value="JDBC driver classes if used")
    public class Connector

extends Object
implements Factory<Connection>

The Connector class provides some simplified access to several database systems through convenient methods. Although the class doesn't require any additional driver software for compilation, certain methods may through SQLException if the specified driver is not present at the time.

Author:
  Holger Antelmann
See Also:
  `ConnectorSettings`, `JConnectionLogin`

Nested Class Summary
`static class` `Connector.DBType` supported database types transparently supported by the Connector class

Field Summary
`protected String` `MYSQL_DRIVER_CLASS`
`static String` `ODBC_DRIVER`

Constructor Summary
`Connector()`
`Connector(String propertiesPrefix)`

Method Summary
`Connection` `createInstance(EventObject eo)` this implementation calls `getConnectionFromSettings()`
`Connection` `getAccessConnection(File msAccessFile)`
`Connection` `getAccessConnection(File msAccessFile, String user, String password, boolean memoryOnly)`
`CipherKey` `getCipherKey()`
`Connection` `getConnection(Connector.DBType type, String server, int port, String dbname, String user, String password)` returns a connection based on the information given.
`Connection` `getConnection(Connector.DBType type, String server, String dbname, String user, String password)` returns a connection based on the information given.

`Connection`

`getConnectionFromProperties(String prefix, Properties props)`
this methods looks for the following property keys in the given properties from which it creates the connection (the given prefix will be prepended): cipherKey - if given, a `CipherKey` is used to try to decrypt user and password The other settings are read according to `getConnectionFromProperties(String, Properties, CipherKey)` #see `getConnectionFromProperties(String, Properties, CipherKey)`

`Connection`

`getConnectionFromProperties(String prefix, Properties props, CipherKey key)`
this methods looks for the following property keys in the given properties from which it creates the connection (the given prefix will be prepended): db.odbc - if given, a simple ODBC connection will be returned db.driver.class - if given (along with a url), the given class is dynamically loaded and used with the url (see below) db.driver.class.init - if true, a given driver class would be initialized while loading db.driver.url - if given (along with a class) this url is used to create the connection db.type - specifies the database type; corresponds to the `Connector.DBType` db.server db.port db.name db.user db.password db.ssl - specifies whether SSL is to be used

`Connection` `getConnectionFromSettings()`
`Connection` `getConnectionFromSettings(String prefix)`
`Properties` `getConnectionProperties()` allows to specify further connection properties
`Connection` `getDerbyConnection(String dbName, boolean createOption)`
`Connection` `getDerbyConnection(String hostName, int port, String dbName, String user, String password, boolean createOption)` uses the embedded Apache Derby (JavaDB) driver by connecting to a running server
`Connection` `getDerbyConnection(String dbName, String user, String password, boolean createOption)` uses the embedded Apache Derby (JavaDB) driver in a single-process mode
`Connection` `getDerbyConnection(String hostName, String dbName, String user, String password, boolean createOption)`
`Connection` `getFirebirdConnection(String server, int port, String dbFileName, String user, String password)`
`Connection` `getFirebirdConnection(String server, String dbFileName)`
`Connection` `getFirebirdConnection(String server, String dbFileName, String user, String password)`
`Processor<Connection,SQLException>` `getHandler()`
`Connection` `getHsqldbConnection(String host, int port, String dbName, String login, String password)` provides JDBC access through the Hsqldb driver (http://hsqldb.sourceforge.net/)
`Connection` `getHsqldbConnection(String dbName, String login, String password)` provides JDBC access through the Hsqldb driver (http://hsqldb.sourceforge.net/)
`Connection` `getHsqldbConnection(String host, String dbName, String login, String password)` provides JDBC access through the Hsqldb driver (http://hsqldb.sourceforge.net/)
`Connection` `getHsqldbInMemory()` a special in-memory database using the HSQLDB driver
`Connection` `getMDBConnection(File mdbFile)` provides some simplified access to an existing Microsoft Access database through Sun's JDBC/ODBC bridge
`Connection` `getMDBConnection(File mdbFile, File workGroupFile, Properties props)` provides some simplified access to an existing Microsoft Access database through Sun's JDBC/ODBC bridge
`Connection` `getMDBConnection(File mdbFile, File workGroupFile, String user, String password, Properties props)` provides some simplified access to an existing Microsoft Access database through Sun's JDBC/ODBC bridge
`Connection` `getMDBConnection(File mdbFile, Properties props)` provides some simplified access to an existing Microsoft Access database through Sun's JDBC/ODBC bridge
`Connection` `getMySQLConnection(String host, int port, String dbName, String login, String password)` provides simplified access to a MySQL database using MySQL Connector/J 3.1
`Connection` `getMySQLConnection(String host, String dbName, String login, String password)` uses the standard port 3306
`Connection` `getODBCConnection(String dbName)` provides some simplified access to existing ODBC connections through Sun's JDBC/ODBC bridge
`Connection` `getODBCConnection(String dbName, Properties props)`
`Connection` `getODBCConnection(String dbName, String login, String password)` provides some simplified access to existing ODBC connections through Sun's JDBC/ODBC bridge
`String` `getPropertiesPrefix()`
`Connection` `getSAPDBConnection(String host, int port, String dbName, String user, String password)`
`Connection` `getSAPDBConnection(String host, String dbName, String user, String password)`
`Connection` `getSQLiteConnection(String dbname)` uses the JDBC driver from www.ch-werner.de/javasqlite
`Connection` `getSQLiteMemoryConnection()`
`Connection` `getSQLServerConnection(String host, int port, String dbName, String login, String password)` getSQLServerConnection() provides access to a Microsoft SQL-Server database.
`Connection` `getSQLServerConnection(String host, String dbName, String login, String password)`
`String` `getSQLServerDriver()`
`protected Connection` `init(Connection con)`
`boolean` `isSQLiteFile(File file)`
`boolean` `isUseSSL()`
`Class<?>` `loadDriverClass(String driverClass, boolean initNewInstance, URL... driverJarUrls)` loads the given class and wraps occurring exceptions into an SQLException
`void` `setCipherKey(CipherKey cipherKey)`
`void` `setDerbySystemHome(String directory)` sets the system home directory to be used for the Apache Derby (JavaDB) database access
`void` `setHandler(Processor<Connection,SQLException> handler)`
`void` `setPropertiesPrefix(String propertiesPrefix)`
`void` `setSQLServerDriver(String driverClassName)` sets the name of the driver class to be used by `getSQLServerConnection()`.
`void` `setUseSSL(boolean flag)`
`void` `shutDownDerby(String dbName)`
`void` `shutDownDerby(String dbName, String user, String password)` shuts down the Apache Derby (JavaDB) database if the given dbName is null, all databases are shut down

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### ODBC_DRIVER

    public static final String ODBC_DRIVER

See Also:
  Constant Field Values

### MYSQL_DRIVER_CLASS

    protected String MYSQL_DRIVER_CLASS

Constructor Detail

### Connector

    public Connector()

### Connector

    public Connector(String propertiesPrefix)

Method Detail

### createInstance

    public Connection createInstance(EventObject eo)
                              throws Exception

  this implementation calls `getConnectionFromSettings()`

  Specified by:
    `createInstance` in interface `Factory<Connection>`
  Parameters:
    `eo` - the event that triggered this instance creation; normally, this method should also cope with the event to be null.
  Throws:
    `Exception`

### isUseSSL

    public boolean isUseSSL()

### setUseSSL

    public void setUseSSL(boolean flag)

### getHandler

    public Processor<Connection,SQLException> getHandler()

### setHandler

    public void setHandler(Processor<Connection,SQLException> handler)

### init

    protected Connection init(Connection con)
                       throws SQLException

  Throws:
    `SQLException`

### getCipherKey

    public CipherKey getCipherKey()

### setCipherKey

    public void setCipherKey(CipherKey cipherKey)

### getPropertiesPrefix

    public String getPropertiesPrefix()

### setPropertiesPrefix

    public void setPropertiesPrefix(String propertiesPrefix)

### getConnectionFromSettings

    public Connection getConnectionFromSettings()
                                         throws SQLException,
                                                GeneralSecurityException

  Throws:
    `SQLException`
    `GeneralSecurityException`

### getConnectionFromSettings

    public Connection getConnectionFromSettings(String prefix)
                                         throws SQLException,
                                                GeneralSecurityException

  Throws:
    `SQLException`
    `GeneralSecurityException`
  See Also:
    `Settings.getProperties()`

### getConnectionFromProperties

    public Connection getConnectionFromProperties(String prefix,
                                                  Properties props)
                                           throws SQLException,
                                                  GeneralSecurityException

  this methods looks for the following property keys in the given properties from which it creates the connection (the given prefix will be prepended):
  - cipherKey - if given, a `CipherKey` is used to try to decrypt user and password
  The other settings are read according to `getConnectionFromProperties(String, Properties, CipherKey)` #see `getConnectionFromProperties(String, Properties, CipherKey)`

  Throws:
    `SQLException`
    `GeneralSecurityException`

### getConnectionFromProperties

    public Connection getConnectionFromProperties(String prefix,
                                                  Properties props,
                                                  CipherKey key)
                                           throws SQLException

  this methods looks for the following property keys in the given properties from which it creates the connection (the given prefix will be prepended):
  - db.odbc - if given, a simple ODBC connection will be returned
  - db.driver.class - if given (along with a url), the given class is dynamically loaded and used with the url (see below)
  - db.driver.class.init - if true, a given driver class would be initialized while loading
  - db.driver.url - if given (along with a class) this url is used to create the connection
  - db.type - specifies the database type; corresponds to the `Connector.DBType`
  - db.server
  - db.port
  - db.name
  - db.user
  - db.password
  - db.ssl - specifies whether SSL is to be used

  Parameters:
    `key` - if a key is given, user and password will go through a decryption attempt before use
  Throws:
    `SQLException`
  See Also:
    `getConnection(DBType, String, String, String, String)`

### getConnectionProperties

    public Properties getConnectionProperties()

  allows to specify further connection properties

### getConnection

    public Connection getConnection(Connector.DBType type,
                                    String server,
                                    String dbname,
                                    String user,
                                    String password)
                             throws SQLException

  returns a connection based on the information given. For `Connector.DBType.ODBC`, the server parameter is ignored; for `Connector.DBType.SQLite`, all but the dbname parameter are ignored.

  Throws:
    `SQLException`

### getConnection

    public Connection getConnection(Connector.DBType type,
                                    String server,
                                    int port,
                                    String dbname,
                                    String user,
                                    String password)
                             throws SQLException

  returns a connection based on the information given. For `Connector.DBType.ODBC`, the server parameter is ignored; for `Connector.DBType.SQLite`, all but the dbname parameter are ignored.

  Throws:
    `SQLException`

### loadDriverClass

    public Class<?> loadDriverClass(String driverClass,
                                    boolean initNewInstance,
                                    URL... driverJarUrls)
                             throws SQLException

  loads the given class and wraps occurring exceptions into an SQLException

  Parameters:
    `driverClass` - the name of the driver class to be loaded
    `initNewInstance` - if true, a new instance is created of the given class
    `driverJarUrls` - allows to specify external jar files that will be dynamically loaded using a `URLClassLoader`
  Throws:
    `SQLException`
  See Also:
    `DriverWrapper`

### getFirebirdConnection

    public Connection getFirebirdConnection(String server,
                                            String dbFileName)
                                     throws SQLException

  Throws:
    `SQLException`

### getFirebirdConnection

    public Connection getFirebirdConnection(String server,
                                            String dbFileName,
                                            String user,
                                            String password)
                                     throws SQLException

  Throws:
    `SQLException`

### getFirebirdConnection

    public Connection getFirebirdConnection(String server,
                                            int port,
                                            String dbFileName,
                                            String user,
                                            String password)
                                     throws SQLException

  Throws:
    `SQLException`

### getSAPDBConnection

    public Connection getSAPDBConnection(String host,
                                         String dbName,
                                         String user,
                                         String password)
                                  throws SQLException

  Throws:
    `SQLException`

### getSAPDBConnection

    public Connection getSAPDBConnection(String host,
                                         int port,
                                         String dbName,
                                         String user,
                                         String password)
                                  throws SQLException

  Throws:
    `SQLException`

### getMySQLConnection

    public Connection getMySQLConnection(String host,
                                         String dbName,
                                         String login,
                                         String password)
                                  throws SQLException

  uses the standard port 3306

  Throws:
    `SQLException`

### getMySQLConnection

    public Connection getMySQLConnection(String host,
                                         int port,
                                         String dbName,
                                         String login,
                                         String password)
                                  throws SQLException

  provides simplified access to a MySQL database using MySQL Connector/J 3.1

  Throws:
    `SQLException`

### getMDBConnection

    public Connection getMDBConnection(File mdbFile)
                                throws SQLException

  provides some simplified access to an existing Microsoft Access database through Sun's JDBC/ODBC bridge

  Throws:
    `SQLException`

### getMDBConnection

    public Connection getMDBConnection(File mdbFile,
                                       Properties props)
                                throws SQLException

  provides some simplified access to an existing Microsoft Access database through Sun's JDBC/ODBC bridge

  Throws:
    `SQLException`

### getMDBConnection

    public Connection getMDBConnection(File mdbFile,
                                       File workGroupFile,
                                       String user,
                                       String password,
                                       Properties props)
                                throws SQLException

  provides some simplified access to an existing Microsoft Access database through Sun's JDBC/ODBC bridge

  Throws:
    `SQLException`

### getMDBConnection

    public Connection getMDBConnection(File mdbFile,
                                       File workGroupFile,
                                       Properties props)
                                throws SQLException

  provides some simplified access to an existing Microsoft Access database through Sun's JDBC/ODBC bridge

  Throws:
    `SQLException`

### getODBCConnection

    public Connection getODBCConnection(String dbName)
                                 throws SQLException

  provides some simplified access to existing ODBC connections through Sun's JDBC/ODBC bridge

  Throws:
    `SQLException`

### getODBCConnection

    public Connection getODBCConnection(String dbName,
                                        Properties props)
                                 throws SQLException

  Throws:
    `SQLException`

### getODBCConnection

    public Connection getODBCConnection(String dbName,
                                        String login,
                                        String password)
                                 throws SQLException

  provides some simplified access to existing ODBC connections through Sun's JDBC/ODBC bridge

  Throws:
    `SQLException`

### getSQLServerDriver

    public String getSQLServerDriver()

### setSQLServerDriver

    public void setSQLServerDriver(String driverClassName)
                            throws IllegalArgumentException

  sets the name of the driver class to be used by `getSQLServerConnection()`. Currently known drivers:
  - `com.microsoft.jdbc.sqlserver`
  - `net.sourceforge.jtds.jdbc.Driver`
  - `com.microsoft.sqlserver.jdbc.SQLServerDriver`

  Throws:
    `IllegalArgumentException` - if the given driver name isn't known to this implementation

### getSQLServerConnection

    public Connection getSQLServerConnection(String host,
                                             String dbName,
                                             String login,
                                             String password)
                                      throws SQLException

  Throws:
    `SQLException`

### getSQLServerConnection

    public Connection getSQLServerConnection(String host,
                                             int port,
                                             String dbName,
                                             String login,
                                             String password)
                                      throws SQLException

  getSQLServerConnection() provides access to a Microsoft SQL-Server database. The driver to be used depends on what has been configured.

  Throws:
    `SQLException`
  See Also:
    `setSQLServerDriver(String)`

### getHsqldbInMemory

    public Connection getHsqldbInMemory()
                                 throws SQLException

  a special in-memory database using the HSQLDB driver

  Throws:
    `SQLException`

### getHsqldbConnection

    public Connection getHsqldbConnection(String host,
                                          String dbName,
                                          String login,
                                          String password)
                                   throws SQLException

  provides JDBC access through the Hsqldb driver (http://hsqldb.sourceforge.net/)

  Throws:
    `SQLException`

### getHsqldbConnection

    public Connection getHsqldbConnection(String host,
                                          int port,
                                          String dbName,
                                          String login,
                                          String password)
                                   throws SQLException

  provides JDBC access through the Hsqldb driver (http://hsqldb.sourceforge.net/)

  Throws:
    `SQLException`

### getHsqldbConnection

    public Connection getHsqldbConnection(String dbName,
                                          String login,
                                          String password)
                                   throws SQLException

  provides JDBC access through the Hsqldb driver (http://hsqldb.sourceforge.net/)

  Parameters:
    `dbName` - the path and name of the database (example: `/dir/db1`)
    `login` - as a default, `sa` can be used for the system administrator
  Throws:
    `SQLException`

### setDerbySystemHome

    public void setDerbySystemHome(String directory)

  sets the system home directory to be used for the Apache Derby (JavaDB) database access

### shutDownDerby

    public void shutDownDerby(String dbName)
                       throws SQLException

  Throws:
    `SQLException`

### shutDownDerby

    public void shutDownDerby(String dbName,
                              String user,
                              String password)
                       throws SQLException

  shuts down the Apache Derby (JavaDB) database if the given dbName is null, all databases are shut down

  Throws:
    `SQLException`

### getDerbyConnection

    public Connection getDerbyConnection(String dbName,
                                         boolean createOption)
                                  throws SQLException

  Throws:
    `SQLException`

### getDerbyConnection

    public Connection getDerbyConnection(String dbName,
                                         String user,
                                         String password,
                                         boolean createOption)
                                  throws SQLException

  uses the embedded Apache Derby (JavaDB) driver in a single-process mode

  Throws:
    `SQLException`

### getDerbyConnection

    public Connection getDerbyConnection(String hostName,
                                         String dbName,
                                         String user,
                                         String password,
                                         boolean createOption)
                                  throws SQLException

  Throws:
    `SQLException`

### getDerbyConnection

    public Connection getDerbyConnection(String hostName,
                                         int port,
                                         String dbName,
                                         String user,
                                         String password,
                                         boolean createOption)
                                  throws SQLException

  uses the embedded Apache Derby (JavaDB) driver by connecting to a running server

  Throws:
    `SQLException`

### getSQLiteConnection

    public Connection getSQLiteConnection(String dbname)
                                   throws SQLException

  uses the JDBC driver from www.ch-werner.de/javasqlite

  Throws:
    `SQLException`

### getSQLiteMemoryConnection

    public Connection getSQLiteMemoryConnection()
                                         throws SQLException

  Throws:
    `SQLException`

### isSQLiteFile

    public boolean isSQLiteFile(File file)
                         throws IOException

  Throws:
    `IOException`

### getAccessConnection

    @ThirdParty(value="net.ucanaccess.jdbc.UcanaccessDriver")
    public Connection getAccessConnection(File msAccessFile)
                                   throws SQLException

  Throws:
    `SQLException`

### getAccessConnection

    @ThirdParty(value="net.ucanaccess.jdbc.UcanaccessDriver")
    public Connection getAccessConnection(File msAccessFile,
                                                          String user,
                                                          String password,
                                                          boolean memoryOnly)
                                   throws SQLException

  Throws:
    `SQLException`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads