Package com.aceql.jdbc.driver.free

Class AceQLDriver

java.lang.Object
com.aceql.jdbc.driver.free.AceQLDriver
All Implemented Interfaces:
Driver
public final class AceQLDriver
extends Object
implements Driver
The AceQL JDBC Driver class for accessing remote SQL databases through HTTP from Android or Java desktop programs.

user, password, and database are the only required properties.

Properties:
  • user: Username to connect to the remote database.
  • password: Password to use for authentication.
  • database: Name of the remote database as defined in the server aceql-server.properties file.
  • proxyType: java.net.Proxy type to use: DIRECT, HTTP, or SOCKS. Defaults to DIRECT.
  • proxyHostname: java.net.Proxy hostname to use.
  • proxyPort: java.net.Proxy port to use.
  • proxyUsername: Proxy credential username.
  • proxyPassword: Proxy credential password.
  • connectTimeout: Timeout value, in milliseconds, to be used when opening a communications link to the remote server. If the timeout expires before the connection can be established, a java.net.SocketTimeoutException is raised. A timeout of zero is interpreted as an infinite timeout. Defaults to 0.
  • readTimeout: Read timeout in milliseconds. A non-zero value specifies the timeout when reading from an InputStream after a connection is established. If the timeout expires before there is data available for reading, a java.net.SocketTimeoutException is raised. A timeout of zero is interpreted as an infinite timeout. Defaults to 0.
  • gzipResult: Boolean indicating whether the ResultSet is gzipped before download. Defaults to true.
  • resultSetMetaDataPolicy: Defines the ResultSet metadata policy. Indicates if the ResultSet metadata is downloaded along with the ResultSet. Possible values are "on" and "off". Defaults to "on".
  • clobReadCharset: Name of the charset to use when reading CLOB content with the ResultSet methods. Defaults to null.
  • clobWriteCharset: Name of the charset to use when writing CLOB content with the PreparedStatement streaming methods. Defaults to "UTF-8".
  • maxRetries: Maximum number of retries for failed HTTP calls. Defaults to 3.
  • retryIntervalMs: Delay between retries, in milliseconds. Defaults to 1000 ms.

Usage of the AceQL JDBC Driver is straightforward: 

 // Define URL of the path to the AceQL Manager Servlet
 // We will use a secure SSL/TLS session. All uploads/downloads of SQL
 // commands and data will be encrypted.
 String url = "http://localhost:9090/aceql";

 // The login info for strong authentication on server side.
 // These are *not* the username/password of the remote JDBC Driver,
 // but are the auth info checked by remote server
 // UserAuthenticator.login(username, password) method.
 String database = "sampledb";
 String user = "user1";
 String password = "password1";

 // Register and Load the Driver
 DriverManager.registerDriver(new AceQLDriver());
 String driverClassName = AceQLDriver.class.getName();
 Class.forName(driverClassName);

 // Attempts to establish a connection to the remote database:
 Properties info = new Properties();
 info.put("user", user);
 info.put("password", password);
 info.put("database", database);

 Connection connection = DriverManager.getConnection(url, info);
 return connection;

An alternate way of passing connection info is to add them as request parameters to the URL: 


 // Define URL of the path to the AceQL Manager Servlet, with all properties
 // passed as request parameters.
 // (We presume that the aceql_license_key.txt is installed in user.dir.)
 String url = "http://localhost:9090/aceql?user=user1&password=password1&database=sampledb";

 // Register and Load the Driver 
 DriverManager.registerDriver(new AceQLDriver());
 String driverClassName = AceQLDriver.class.getName();
 Class.forName(driverClassName);

 // Attempts to establish a connection to the remote database:
 Connection connection = DriverManager.getConnection(url, new Properties());
The Connection returned is now ready to be used as a regular or classic Connection: 

 String sql = "select * from customer where customer_id >= 1 order by customer_id";
 Statement statement = connection.createStatement();
 statement.execute(sql);

 ResultSet rs = statement.getResultSet();
 // Etc.
The built Connection is an instance of AceQLConnection that contains some specific method. See AceQLConnection for more info.

Since:
6.0
Author:
Nicolas de Pomereu

  • Constructor Details

    • AceQLDriver

      public AceQLDriver()

  • Method Details

    • connect

      public Connection connect​(String url, Properties info) throws SQLException
      Attempts to make a database connection to the given URL. The driver will return "null" if it realizes it is the wrong kind of driver to connect to the given URL. acceptsURL(java.lang.String) will return null.

      The driver will throwSQLException if it is the right driver to connect to the given URL but has trouble connecting to the database.

      The java.util.Properties argument can be used to pass arbitrary string tag/value pairs as connection arguments. At least "user", "password" and "database" properties should be included in the Properties object, or either passed through the URL parameter.

      Specified by:
      connect in interface Driver
      Parameters:
      url - the URL of the database to which to connect
      info - a list of arbitrary string tag/value pairs as connection arguments. At least a "user" and "password" property should be included.
      Returns:
      a Connection object that represents a connection to the URL
      Throws:
      SQLException - if a database access error occurs

    • acceptsURL

      public boolean acceptsURL​(String url) throws SQLException
      Retrieves whether the driver thinks that it can open a connection to the given URL. Typically drivers will return true if they understand the subprotocol specified in the URL and false if they do not.

      The AceQL driver requires an URL which is an http url in the format:
      jdbc:aceql:http(s)://<server-name:port>/<AceQL Manager servlet call name>

      Example:
      jdbc:aceql:https://www.acme.com:9443/aceql

      Note that the "jdbc:aceql:" prefix is optional and thus an URL such as https://www.aceql.com:9443/aceql is accepted
      Specified by:
      acceptsURL in interface Driver
      Parameters:
      url - the URL of the database
      Returns:
      true if this driver understands the given URL; false otherwise
      Throws:
      SQLException - if a database access error occurs

    • getPropertyInfo

      public DriverPropertyInfo[] getPropertyInfo​(String url, Properties info) throws SQLException
      Gets information about the possible properties for this driver.

      The getPropertyInfo method is intended to allow a generic GUI tool to discover what properties it should prompt a human for in order to get enough information to connect to a database. Note that depending on the values the human has supplied so far, additional values may become necessary, so it may be necessary to iterate though several calls to the getPropertyInfo method.

      Specified by:
      getPropertyInfo in interface Driver
      Parameters:
      url - the URL of the database to which to connect
      info - a proposed list of tag/value pairs that will be sent on connect open
      Returns:
      an array of DriverPropertyInfo objects describing possible properties.
      Throws:
      SQLException - if a database access error occurs

    • getMajorVersion

      public int getMajorVersion()
      Retrieves this driver's major version number.
      Specified by:
      getMajorVersion in interface Driver
      Returns:
      this driver's major version number

    • getMinorVersion

      public int getMinorVersion()
      Gets the driver's minor version number.
      Specified by:
      getMinorVersion in interface Driver
      Returns:
      this driver's minor version number

    • jdbcCompliant

      public boolean jdbcCompliant()
      Reports whether this driver is a genuine JDBC Compliant ™ driver. A driver may only report true here if it passes the JDBC compliance tests; otherwise it is required to return false.

      JDBC compliance requires full support for the JDBC API and full support for SQL 92 Entry Level.

      Because the AceQL driver works as a special Driver over HTTP to support many SQL databases vendors, it does not aim to be a genuine JDBC Compliant ™ driver. Thus, method returns false.

      Specified by:
      jdbcCompliant in interface Driver
      Returns:
      false

    • getParentLogger

      public Logger getParentLogger() throws SQLFeatureNotSupportedException
      Return the parent Logger of all the Loggers used by this driver. This should be the Logger farthest from the root Logger that is still an ancestor of all of the Loggers used by this driver. Configuring this Logger will affect all of the log messages generated by the driver. In the worst case, this may be the root Logger.
      Specified by:
      getParentLogger in interface Driver
      Returns:
      the parent Logger for this driver
      Throws:
      SQLFeatureNotSupportedException - if the driver does not use java.util.logging.
      Since:
      1.7