Document Revision: 1
Release Information | |
---|---|
Project Name | JDBWC |
Project Type | Type 3 Java JDBC Driver |
Version | 1.0.0-4beta |
License | GNU GPLv3 http://www.gnu.org/licenses/ |
Web | http://jdbwc.sourceforge.net/ |
Support | https://sourceforge.net/projects/jdbwc/support |
This document requires you have some knowledge of web-servers and the Java programming language (and ideally JDBC). Its beyond the scope of this document to explain these subjects in great detail.
Throughout this document there are some descriptive terms that may be unclear. Their meanings are clarified below.
Client Side:
the Java JDBC part of the JDBWC Driver.
Also referred to as JDBC (Java DataBase Connector).
Server-Side:
the PHP side (with a web-server and one or more database-server/s).
Also referred to as WC (Web Connector).
Upstream:
data going from the Client-side to the Server-side.
Downstream:
data going from the Server-side to the Client-side.
JDBWC is an acronym for Java-Data-Base-Web-Connector. In essence, JDBWC is a Java JDBC Driver with its own server written in PHP. Ideally suited to Java Desktop applications that require JDBC access across wide area networks like the internet but do not wish to expose the remote database-server through the remote hosts firewall. EG: the database server does not need to be exposed to the internet at all.
Client-side:
Java JRE >= 1.6.0_20 (you can also compile from source to suit your target JRE)
Server-side:
Apache-Web-server >= 1.3.41
PHP >= 5.1.x with MySQL >= 5.x.x and/or PostgreSQL >= 7.4.x
If your using MySQL you should enable the
PHP mysqli extension for full metadata functionality.
The existence of the mysqli extension is determined on the server-side.
Supplied dependencies (licensed under an extended Apache-2 license)
HttpClient 4.0.1 (GA) + dependencies
jdbwc-lib
" folder containing "jdbwc.jar
" and dependencies
to a location relative to your Java application files. Class-Path: jdbwc-lib/jdbwc.jar or Class-Path: jdbwc.jar
depending on where you put the jar files in relation to your java app. IDE's usually require all of the jars in the build path as do SQL Clients (like SQuirreL, SQLWorkBench, DBVisualizer, etc.).
For apps, the required jdbwc dependencies will be added to your classpath by jdbwc.jar
Once the Server-side portion is installed and configs are set you can forget about it.
It only interacts with the JDBC portion and doesn't need to be maintained.
It does maintain an event.log file that you may want to
look at occasionally to see what's been happening on your server.
The event.log can be invaluable for debugging, however any exceptions or errors encountered on
the server will be thrown back to the JDBC driver as an SQL exception (or extension of).
Most PHP warnings will only be logged, not relayed as they usually aren't critical and don't warrant halting the driver.
SQL errors will contain the database servers original message with the offending SQL
query below that. The usual java exception trail will follow.
It will also be logged in the servers event log as an SQL-ERROR.
In the distribution package you will find a zip file called server-side-bundle.zip
.
It contains some optional testing files which are explained in the README inside the zip.
NOTE: The folder: "jdbwc/includes/config/local
" is for testing servers. Its supplied for convenience when developing. If it is present on your server, its configs will be used in preference to the production ones in: jdbwc/includes/config
.
The "jdbwc/includes/config/local
" folder should _NOT_ be uploaded to production machines.
upload/jdbwc
folder can be uploaded to the public root dir or any subfolder.http://yourserver.ext/jdbwc
, http://yourserver.ext/subfolder/anotherfolder/jdbwc
, etc.jdbwc/includes/config/configure.php
" jdbwc/includes/config/databases.php
" jdbwc/includes/wc_logs
" full write permissions.jdbwc/includes/sessions
" full write permissions andjdbwc/includes/sessions/phpsess.db
" (sqlite database) write permissions if you chose sqlite as the session handler (in the configure.php
file).That's about it.
See the bundled jdbwctest.zip
file in the distribution folder for details on how to setup your java class/s
to use the jdbwc.jar (JDBC driver). Look in the connect()
method for some examples.
Also have a look at the test class in the file jdbwctest.zip
(included in the distribution).
There are a number of optional connection parameters you can use to fine tune the connection.
The list of optional params may change between different releases depending on additional functionality supported by the driver.
See the section on Connection URL in detail for more info.
JDBWC is a JDBC Driver, so the standard JDBC syntax applies for general use.
To start a JDBC connection using JDBWC
you need to register the driver with the Java DriverManager
and then start a new JDBC connection using a JDBWC specific URL.
The url syntax and required parameters are demonstrated in the example.
Parameters (everything after the ?) can be in any order.
Registering the driver requires a ClassNotFoundException
handler,
starting a new Connection requires an SQLException
handler.
See the example below.
NOTE: SSL is highly recommended over sending sql in plaintext.
v1.0.0.3 will only work with validated certs.
v1.0.0.4 will work with validated and unvalidated/self-signed certs.
Un-validated/self-signed certs require the optional param: nonVerifiedSSL = true
The connection URL consists of 3 main parts. Optional parameters can be added to the connection to customise the connection object. Parameters can be in any order.
Example:
jdbc:jdbwc:mysql//https://example.org:445/exampledirectory/
Theres 2 ways to pass the information into the driver in order to start a new connection.
OR
jdbc:jdbwc://
Requests a default connection from JDBWC. The default is MySql.
jdbc:jdbwc:mysql//
Requests a MySql connection from JDBWC.
jdbc:jdbwc:postgresql//
Requests a PostgreSql connection from JDBWC.
url
The website URL containing the JDBWC server-side PHP bundle.
The url must start with a protocol (http or https) and have a trailing /
Examples:
https://mydomain.ext:445/myfolder/myotherfolder/
(will use port 445)http://mydomain.ext:8080/myfolder/myotherfolder/
(will use port 8080)https://mydomain.ext/myfolder/myotherfolder/
(will default to port 443)http://mydomain.ext/myfolder/myotherfolder/
(will default to port 80) The port number is only required for non standard ports in the range [1-0xfffe] (anything other than 80 or 443).
In rare circumstances custom port usage may incur up to 7ms overhead per query (100 queries = +0.7 of a second). This rare delay seems to be related to the webserver, not the driver.
The JDBWC driver will append jdbwc/index.php
to the end of the URL before requesting a connection from the server.
If the domain name is unknown or not in DNS an IP can be used.
user
The user name you specified in the server-side configure.php
file.
password
The password you specified in the server-side configure.php
file.
databaseName
One of the database names you specified in the server-side databases.php
file.
databaseUser
One of the database user-names you specified in the server-side databases.php
file.
databasePassword
One of the database passwords you specified in the server-side databases.php
file.
proxyUrl
The proxy server URL to communicate through.
The url must start with a protocol (http or https). NO trailing /
Examples:
http://myproxy.ext:8120
http://myproxy.myserver.ext:8000
The port number is ALWAYS required for proxy servers. If this parameter is used and there is no proxy, the connection will fail.
timeout
Connection timeout. The maximum amount of time before a connection will timeout if it hasn't received a response from the server. If the server is offline, the driver will throw an exception as soon as it determines there's no one home.
OPTIONS: a time in milliseconds. 1 second = 1000 milliseconds
nonVerifiedSSL
Allows the driver to use different qualities of SSL. By default its set to false and the driver will perform full SSL verification including strict hostname checking (similar to a web browser). If this option is set to true the driver will attempt to ignore the usual checks. If the driver is unable to ignore the SSL verification the driver will throw an exception from the java.security
package or/and the javax.net.ssl
package.
OPTIONS: true, false (or not used. defaults to false)
debug
Turns debugging on or off. Its off by default. The other debugXX
options will only take effect if this option is set to true
.
OPTIONS: true, false (or not used. defaults to false)
debugLogger
The type of logger to use for logging. Although there are 3 options, only SimpleLog support is built in to this release. java.util.logging
and Log4J
both require external property files. To find out more about the logger see: http://hc.apache.org/httpcomponents-client-4.0.1/logging.html
OPTIONS: SimpleLog, Jdk14Logger, Log4JLogger
debugLevel
Debugging levels:
0 JDBWC informative/debugging,
1 JDBWC debugging,
2 JDBWC debugging and Enable header wire + context logging - Best for Debugging,
3 JDBWC debugging and Enable full wire + context logging,
4 JDBWC debugging and Enable context logging for connection management,
5 JDBWC debugging and Enable context logging for connection management / request execution.
OPTIONS: [0-5]
useDummyAgent
This is rarely required. Its for situations where the host server blocks the default HttpClient User-Agent
. The server would need to have been configured to deliberately block the HttpClient user agent.
OPTIONS: true, false (or not used. defaults to false)
https://myserver.ext:445/mysubfolder/
)http://myproxyserver.ext:8085
)config/local
folder rather than a host named localhost
(this is usually for testing setups).NOTE: Its strongly advised to use an SSL connection when communicating across a network or the internet as you will be sending raw sql. To correctly install SSL your web-server must have a dedicated IP.
If you notice any, please report them in the projects bug-tracking area at: http://sourceforge.net/tracker/?group_id=233279&atid=1089227
Please be specific with bug reports so they can be properly attended to. Vague reports will not be attended to unless the error is quite obvious.
Include some code or a description of the conditions you encountered the bug in so it can be reproduced. The more detail, the higher the chance of it being fixed quickly.
NOTE: NotImplemented
exceptions are not bugs. They are features that have not been fully implemented yet and will vary for each release. This technique of dealing with unfinished areas is part of the JDBC specification for drivers [http://java.sun.com/products/jdbc/driverdevs.html].
If you would like to see a particular feature implemented, please make a feature request at: http://sourceforge.net/tracker/?group_id=233279&atid=1089230
Copyright ©2008 Tim Gall, All rights reserved.
LEGAL FOOTNOTES:
Java is a trademark of Sun Microsystems Inc. (Also see: Oracle Corporation)
MySql is a trademark of MySql AB. (Also see: Oracle Corporation)
PostgreSql is copyright of: PostgreSQL Global Development Group