buttle.driver — buttle 1.0.0

The Buttle java.sql.Driver.

This namespace delivers buttle.jdbc.Driver via :gen-class. This named class can be used by tools (like SQuirreL) and the SPI services/java.sql.Driver.

The -init constructor function will register a Buttle Driver proxy (see make-driver) with the java.sql.DriverManager. So whenever an instance of buttle.jdbc.Driver is created, a new proxy ( not the buttle.jdbc.Driver!) is registered.

Example JDBC-URL:

jdbc:buttle:{:user "<user>" :password "<password>" :target-url "jdbc:postgresql://127.0.0.1:6632/postgres"}

Example Wildfly datasource (see README for more details):

  <datasource jndi-name="java:/jdbc/buttle-ds" pool-name="buttle-ds" use-java-context="true">
      <driver>buttle-driver</driver>
      <connection-url>
              jdbc:buttle:{
                      :user "<user>"
                      :password "<password>"
                      :class-for-name "org.postgresql.Driver"
                      :target-url "jdbc:postgresql://<host>:<port>/<db-id>"}
          </connection-url>
  </datasource>

When this namespace is loaded eval-buttle-user-file! will be executed.

WARNING: this means that anyone who controls the system properties of the hosting JVM can run any Clojure code (but then again --- when someone controls the system properties he/she is probably able to run any command anyway).

Functions in this namespace deliver all the functionality needed for the java.sql.Driver interface/contract. Things for connections, statements etc. are all delivered through buttle.proxy.

-acceptsURL clj

(-acceptsURL this url)

Implements java.sql.Driver.acceptsURL(String). Just delegates to the referenced/internal driver (see -init).

-connect clj

(-connect this url info)

Implements java.sql.Driver.connect(String, Properties). Just delegates to the referenced/internal driver (see -init) which calls connect-fn.

-getMajorVersion clj

(-getMajorVersion this)

Just delegates to the referenced/internal driver (see -init).

-getMinorVersion clj

(-getMinorVersion this)

Just delegates to the referenced/internal driver (see -init).

-getParentLogger clj

(-getParentLogger this)

Just delegates to the referenced/internal driver (see -init).

-getPropertyInfo clj

(-getPropertyInfo this url info)

Just delegates to the referenced/internal driver (see -init).

-init clj

Constructor function of buttle.jdbc.Driver.

On first invokation creates a Buttle Driver (see make-driver), keeps a reference to it and registers it with the java.sql.DriverManager.

This Buttle driver becomes the internal state of the buttle.jdbc.Driver. All Driver method implemenations of this class delegate to this internal driver.

-jdbcCompliant clj

(-jdbcCompliant this)

Just delegates to the referenced/internal driver (see -init).

accepts-url-fn clj

(accepts-url-fn url)

Parses url via parse-jdbc-url and retrieves the keys :target-url, :user, :password, :class-for-name and :datasource-spec from the returned value (assuming that it is a map). Returns a map with those keys/values.

connect-fn clj

(connect-fn url {info-user "user" info-password "password" :as info})

Returns a JDBC connection for given url.

Returns nil if url is not a Buttle URL (as of accepts-url-fn). Else opens a JDBC Connection to :target-url via buttle.driver-manager/get-connection. If that throws then this function throws. Otherwise the connection is returned. Note that in this case Buttle does not call/use the proxied JDBC driver directly (but relies on the DriverManager).

If :datasource-spec is given in the Buttle URL a datasource ds (as of buttle-ds/retrieve-data-soure) will be used instead of the buttle.driver-manager/get-connection.

Authentication credentials (user and password) are taken from info (keys "user" and "password") if given. Else they are taken from Buttle URL (keys :user and :password). If the connection is opened via DriverManager then info will be passed onto DriverManager/getConnection so that any properties beyond "user" and "password" (which are set to the authentication credentials) contained in info are preserved.

If :class-for-name is set in the Buttle url then calls (Class/forName class-for-name) before opening the connection. This takes care of cases when the proxied driver is not loaded auto-magically by the DriverManager. This may happen when the DriverManager is initialized and the classloader does not see the proxied driver classes at that point (e.g. in JEE application servers when loading things via isolated classloaders).

eval-buttle-user-file! clj

(eval-buttle-user-file!)

If system property buttle.user-file is set, uses load-file to evaluate that file.

This function is called when namespace buttle.driver is loaded. This happens for example when die Buttle JDBC driver is loaded.

Use this function to load your own code when you do not control the main program flow (like when using Buttle in tools like SQuirreL or in a Java application server when you do not control/own the main application).

make-driver clj

(make-driver)

Creates and returns a Buttle java.sql.Driver.

Note that the underlying driver (which delegates to the real driver) is a Clojure proxy (not an instance of buttle.jdbc.Driver) which is wrapped by a buttle.proxy/make-proxy. So calls to retured driver can be intercepted by buttle.proxy/def-handle.

This driver can be registered with the java.sql.DriverManager. There are two important methods that this driver (proxy) implements: connect and acceptsURL. These are needed for interaction with the DriverManager so that the Buttle driver can be picked up for Buttle URLs.

Note: the Buttle proxy will set the current thread's context classloader (TCCL) to Buttle's classloader when delegating to buttle.proxy/handle. This is needed for cases when Buttle is used as a data-source and deployed as a module in Wildfly/JBoss application server. In this case clojure.lang.RT tries to load clojure/core.clj which it can't because it uses the current thread's context classloader and for Wildfly that will not be the Buttle module's classloader. So we explicitly set the TCCL and things work. In non-application-server cases this usually does not hurt. At the moment you cannot configure this feature.

parse-jdbc-url clj

(parse-jdbc-url url)

Parses a Buttle JDBC URL.

A Buttle JDBC URL has the format #"jdbc:buttle:(.+)". Any text after jdbc:buttle: will be read-string-eval'ed and should yield a map with keys :target-url, :user and :password. The eval'ed value is returned (even if not a map). If url does not match the pattern nil is returned. If read-string-eval throws an Exception then an Exception will be thrown.