Chapter 2. Installation

Index:

1. System Requirements
2. Setting the CLASSPATH
3. Loading the Driver
4. Connecting to the Database

System Requirements

HXTT PDF packages include a Type 4 JDBC driver. Type 4 indicates that the driver is written in Pure Java, and communicates in the database system's own network protocol. Because of this, the driver is platform independent; once compiled, the driver can be used on any system. HXTT PDF can run on any platforms with Java VM, which includes Microsoft Windows, Novell Netware, OS2, UNIX, and LINUX. HXTT PDF supports JDK1.6.X, JDK1.7.X, JDK1.8.X, and JDK1.9.X. HXTT PDF includes a database engine which can support multi-user access. It supports { UNION | INTERSECT | EXCEPT | MINUS } [ ALL ] query , INNER JOIN, FULL JOIN, LEFT JOIN, RIGHT JOIN, NATURAL JOIN, CROSS JOIN, and subquery which includes single-row subquery, multirow subquery, multiple-column subquery, inline views, and correlated subquery.

Setting the CLASSPATH

When java loads any class, it searches a list known as the classpath. This is a list of directories where classes are placed, or a list of jar files (archives containing classes and other resources) or both. HXTT PDF driver is a Type 4 driver. You can do this in many different methods, but the most command are:

1. Setting the CLASSPATH environment variable.
2. putting it on the command line using the -cp parameter.
3. placing it in the JVM's lib/ext directory.
4. extract all files in jar file into the directory of your application.

You can know detailed information about "Setting the Classpath" from your JDK Tools and Utilities. Let's use JDBC4.0 package as a simple sample. To put PDF_JDBC40.jar into your class path, you should use "export CLASSPATH=/usr/share/lib/PDF_JDBC40.jar:$CLASSPATH" on Solaris and Linux, and "SET CLASSPATH=\javalib\PDF_JDBC40.jar;%classpath%" on Windows.

Loading the Driver

Any source that uses JDBC needs to import the java.sql package by using " import java.sql.*;".

HXTT PDF driver' name is com.hxtt.sql.pdf.PDFDriver, and you can uses it without involving hard coding the driver into your code. You do this by setting the jdbc.drivers system property. For example, for command line apps you can use:
java -Djdbc.drivers=com.hxtt.sql.pdf.PDFDriver yourApp
Then, the JVM upon startup will load the drivers automatically. Some applications (JBoss, Tomcat etc) support a .properties file which they use to save putting this on the command line.

The second method is the most common and involves you loading the driver yourself. It's simple:
Class.forName("com.hxtt.sql.pdf.PDFDriver");
From then on you can get connections from DriverManager.
Note: If Class.forName() throws ClassNotFoundException, you should check your classpath.

Connecting to the Database

After the driver has been registered with the DriverManager, you can obtain a Connection instance that is connected to a particular database by calling DriverManager.getConnection(). With JDBC, a database is represented by a URL (Uniform Resource Locator).

        Embedded:
                jdbc:pdf:[//]/[DatabasePath][?prop1=value1[;prop2=value2]] (You can omit that "//" characters sometimes)
                        For example:
                                "jdbc:pdf:/."
                                "jdbc:pdf:/c:/data" for Windows driver
                                "jdbc:pdf:///c:/data" for Windows driver
                                "jdbc:pdf:////usr/data" for unix or linux
                                "jdbc:pdf://///192.168.10.2/sharedir" for UNC path
                                "jdbc:pdf:/./data"
                                "jdbc:pdf:/./data/testabc.pdf"
        Remote Access (client/server mode):
                jdbc:pdf://host:port/[DatabasePath]
                        For example: "jdbc:pdf://domain.com:3099/c:/data" if one PDFServer is run on the 3099 port of domain.com
                                     "jdbc:pdf://domain.com:3099/c:/data/mydata.pdf"
        Compressed Database:(.ZIP, .JAR, .GZ, .TAR, .BZ2, .TGZ, .TAR.GZ, .TAR.BZ2, .7z) 
                jdbc url format is the same as embedded url and remote url.
                        For example:
                                "jdbc:pdf:/c:/test/testpdf.zip
        Memory-only Database:
                jdbc:pdf:/_memory_/
        URL Database:(http protocol, https protocol, ftp protocol, sftp protocol)
                jdbc:pdf:http://httpURL
                jdbc:pdf:https://httpsURL
                jdbc:pdf:ftp://ftpURL
                jdbc:pdf:ftps://ftpURL
                jdbc:pdf:ftpes://ftpURL
                jdbc:pdf:sftp://sftpURL
                        For example:
                                "jdbc:pdf:http://www.hxtt.com/test" //Note: FTP site's user/password should be set in ftpURL, and cannot be set in JDBC connection property because user/password JDBC connection property belongs to server/client connection.
                                               //FTP  protocol supports  explicit SSL/TLS encryption (FTPES)  and  implicit SSL/TLS (FTPS). FTPES can be detected according to FTP Server reply, and FTPS can be used if you use port 990 in  Ftp url.
                                "jdbc:pdf:sftp://testa:123456@localhost"
        SAMBA Database:(smb protocol)
                                jdbc:pdf:smb://[[[domain;]username[:password]@]server[:port]/[[share/[dir/]file]]][?[param=value]]
                        For example:
                                "jdbc:pdf:smb://test1:123@100.100.13.94/pdffiles/zone" //Note: SAMBA user/password should be set in SMB url, and cannot be set in JDBC connection property because user/password JDBC connection property belongs to server/client connection.
	UNC path JDBC url:
                jdbc:pdf:/uncpath
                jdbc:pdf:///uncpath
                        For example:
                                "jdbc:pdf:/\\PC17\c$\values" 
                                "jdbc:pdf:/\\PC17\val"
	Free JDBC url:(Warning: only use it for special project)
                jdbc:pdf:/" or "jdbc:pdf:///". Then you can use some full UNC path names in SQL to visit anywhere where your Java VM has right to access.
                        For instance:
                                select * from \\amd2500\e$\pdffiles\test;
                                select * from "\\amd2500\d$\pdffiles".test;
                                select * from ".".test;

         HXTT PDF supports seamlessly data mining on memory-only table, physical table, url table, compressed table, SAMBA table in a sql. More details
         is in Advanced Programming chapter.

To connect, you need to get a Connection instance from JDBC. To do this, you use the DriverManager.getConnection() method:

Connection con = DriverManager.getConnection(url, properties);

There are a few different signatures for the getConnection() method. You should see the API documentation that comes with your JDK for more specific information on how to use them. You can specify additional properties to the JDBC driver by placing them in a java.util.Properties instance and passing that instance to the DriverManager when you connect.

When your code then tries to open a Connection, and you get a No driver available SQLException being thrown, this is probably caused by the driver not being in the class path, or the JDBC url not being correct.

To close the database connection, simply call the close() method to the Connection:

con.close();