Java comes with a core set of libraries, including those that define commonly used data types and related behavior, like String or Date; utilities to interact with the host operating system, such as System or File; and useful subsystems to manage security, deal with network communications, and create or parse XML. Given the richness of this core set of libraries, it's often easy to find the necessary bits and pieces to reduce the amount of code a programmer must write to solve a problem.
Even so, there are a lot of interesting Java libraries created by people who find gaps in the core libraries. For example, Apache Commons "is an Apache project focused on all aspects of reusable Java components" and provides a collection of some 43 open source libraries (as of this writing) covering a range of capabilities either outside the Java core (such as geometry or statistics) or that enhance or replace capabilities in the Java core (such as math or numbers).
Another common type of Java library is an interface to a system component—for example, to a database system. This article looks at using such an interface to connect to a PostgreSQL database and get some interesting information. But first, I'll review the important bits and pieces of a library.
What is a library?
A library, of course, must contain some useful code. But to be useful, that code needs to be organized in such a way that the Java programmer can access the components to solve the problem at hand.
I'll boldly claim that the most important part of a library is its application programming interface (API) documentation. This kind of documentation is familiar to many and is most often produced by Javadoc, which reads structured comments in the code and produces HTML output that displays the API's packages in the panel in the top-left corner of the page; its classes in the bottom-left corner; and the detailed documentation at the library, package, or class level (depending on what is selected in the main panel) on the right. For example, the top level of API documentation for Apache Commons Math looks like:
Clicking on a package in the main panel shows the Java classes and interfaces defined in that package. For example, org.apache.commons.math4.analysis.solvers shows classes like BisectionSolver for finding zeros of univariate real functions using the bisection algorithm. And clicking on the BisectionSolver link lists all the methods of the class BisectionSolver.
This type of documentation is useful as reference information; it's not intended as a tutorial for learning how to use the library. For example, if you know what a univariate real function is and look at the package org.apache.commons.math4.analysis.function, you can imagine using that package to compose a function definition and then using the org.apache.commons.math4.analysis.solvers package to look for zeros of the just-created function. But really, you probably need more learning-oriented documentation to bridge to the reference documentation. Maybe even an example!
This documentation structure also helps clarify the meaning of package—a collection of related Java class and interface definitions—and shows what packages are bundled in a particular library.
The code for such a library is most commonly found in a .jar file, which is basically a .zip file created by the Java jar command that contains some other useful information. .jar files are typically created as the endpoint of a build process that compiles all the .java files in the various packages defined.
There are two main steps to accessing the functionality provided by an external library:
- Make sure the library is available to the Java compilation step—javac—and the execution step—java—via the classpath (either the -cp argument on the command line or the CLASSPATH environment variable).
- Use the appropriate import statements to access the package and class in the program source code.
The rest is just like coding with Java core classes, such as String—write the code using the class and interface definitions provided by the library. Easy, eh? Well, maybe not quite that easy; first, you need to understand the intended use pattern for the library components, and then you can write code.
An example: Connect to a PostgreSQL database
The typical use pattern for accessing data in a database system is:
- Gain access to the code specific to the database software being used.
- Connect to the database server.
- Build a query string.
- Execute the query string.
- Do something with the results returned.
- Disconnect from the database server.
The programmer-facing part of all of this is provided by a database-independent interface package, java.sql, which defines the core client-side Java Database Connectivity (JDBC) API. The java.sql package is part of the core Java libraries, so there is no need to supply a .jar file to the compile step. However, each database provider creates its own implementation of the java.sql interfaces—for example, the Connection interface—and those implementations must be provided on the run step.
Let's see how this works, using PostgreSQL.
Gain access to the database-specific code
The following code uses the Java class loader (the Class.forName() call) to bring the PostgreSQL driver code into the executing virtual machine:
import java.sql.*;
public class Test1 {
public static void main(String args[]) {
// Load the driver (jar file must be on class path) [1]
try {
Class.forName("org.postgresql.Driver");
System.out.println("driver loaded");
} catch (Exception e1) {
System.err.println("couldn't find driver");
System.err.println(e1);
System.exit(1);
}
// If we get here all is OK
System.out.println("done.");
}
}Because the class loader can fail, and therefore can throw an exception when failing, surround the call to Class.forName() in a try-catch block.
If you compile the above code with javac and run it with Java:
me@mymachine:~/Test$ javac Test1.java
me@mymachine:~/Test$ java Test1
couldn't find driver
java.lang.ClassNotFoundException: org.postgresql.Driver
me@mymachine:~/Test$The class loader needs the .jar file containing the PostgreSQL JDBC driver implementation to be on the classpath:
me@mymachine:~/Test$ java -cp ~/src/postgresql-42.2.5.jar:. Test1
driver loaded
done.
me@mymachine:~/Test$Connect to the database server
The following code loads the JDBC driver and creates a connection to the PostgreSQL database:
import java.sql.*;
public class Test2 {
public static void main(String args[]) {
// Load the driver (jar file must be on class path) [1]
try {
Class.forName("org.postgresql.Driver");
System.out.println("driver loaded");
} catch (Exception e1) {
System.err.println("couldn't find driver");
System.err.println(e1);
System.exit(1);
}
// Set up connection properties [2]
java.util.Properties props = new java.util.Properties();
props.setProperty("user","me");
props.setProperty("password","mypassword");
String database = "jdbc:postgresql://myhost.org:5432/test";
// Open the connection to the database [3]
try (Connection conn = DriverManager.getConnection(database, props)) {
System.out.println("connection created");
} catch (Exception e2) {
System.err.println("sql operations failed");
System.err.println(e2);
System.exit(2);
}
System.out.println("connection closed");
// If we get here all is OK
System.out.println("done.");
}
}Compile and run it:
me@mymachine:~/Test$ javac Test2.java
me@mymachine:~/Test$ java -cp ~/src/postgresql-42.2.5.jar:. Test2
driver loaded
connection created
connection closed
done.
me@mymachine:~/Test$Some notes on the above:
- The code following comment [2] uses system properties to set up connection parameters—in this case, the PostgreSQL username and password. This allows for grabbing those parameters from the Java command line and passing all the parameters in as an argument bundle. There are other Driver.getConnection() options for passing in the parameters individually.
- JDBC requires a URL for defining the database, which is declared above as String database and passed into the Driver.getConnection() method along with the connection parameters.
- The code uses try-with-resources, which auto-closes the connection upon completion of the code in the try-catch block. There is a lengthy discussion of this approach on Stack Overflow.
- The try-with-resources provides access to the Connection instance and can execute SQL statements there; any errors will be caught by the same catch statement.
Do something fun with the database connection
In my day job, I often need to know what users have been defined for a given database server instance, and I use this handy piece of SQL for grabbing a list of all users:
import java.sql.*;
public class Test3 {
public static void main(String args[]) {
// Load the driver (jar file must be on class path) [1]
try {
Class.forName("org.postgresql.Driver");
System.out.println("driver loaded");
} catch (Exception e1) {
System.err.println("couldn't find driver");
System.err.println(e1);
System.exit(1);
}
// Set up connection properties [2]
java.util.Properties props = new java.util.Properties();
props.setProperty("user","me");
props.setProperty("password","mypassword");
String database = "jdbc:postgresql://myhost.org:5432/test";
// Open the connection to the database [3]
try (Connection conn = DriverManager.getConnection(database, props)) {
System.out.println("connection created");
// Create the SQL command string [4]
String qs = "SELECT " +
" u.usename AS \"User name\", " +
" u.usesysid AS \"User ID\", " +
" CASE " +
" WHEN u.usesuper AND u.usecreatedb THEN " +
" CAST('superuser, create database' AS pg_catalog.text) " +
" WHEN u.usesuper THEN " +
" CAST('superuser' AS pg_catalog.text) " +
" WHEN u.usecreatedb THEN " +
" CAST('create database' AS pg_catalog.text) " +
" ELSE " +
" CAST('' AS pg_catalog.text) " +
" END AS \"Attributes\" " +
"FROM pg_catalog.pg_user u " +
"ORDER BY 1";
// Use the connection to create a statement, execute it,
// analyze the results and close the result set [5]
Statement stat = conn.createStatement();
ResultSet rs = stat.executeQuery(qs);
System.out.println("User name;User ID;Attributes");
while (rs.next()) {
System.out.println(rs.getString("User name") + ";" +
rs.getLong("User ID") + ";" +
rs.getString("Attributes"));
}
rs.close();
stat.close();
} catch (Exception e2) {
System.err.println("connecting failed");
System.err.println(e2);
System.exit(1);
}
System.out.println("connection closed");
// If we get here all is OK
System.out.println("done.");
}
}In the above, once it has the Connection instance, it defines a query string (comment [4] above), creates a Statement instance and uses it to execute the query string, then puts its results in a ResultSet instance, which it can iterate through to analyze the results returned, and ends by closing both the ResultSet and Statement instances (comment [5] above).
Compiling and executing the program produces the following output:
me@mymachine:~/Test$ javac Test3.java
me@mymachine:~/Test$ java -cp ~/src/postgresql-42.2.5.jar:. Test3
driver loaded
connection created
User name;User ID;Attributes
fwa;16395;superuser
vax;197772;
mbe;290995;
aca;169248;
connection closed
done.
me@mymachine:~/Test$This is a (very simple) example of using the PostgreSQL JDBC library in a simple Java application. It's worth emphasizing that it didn't need to use a Java import statement like import org.postgresql.jdbc.*; in the code because of the way the java.sql library is designed. Because of that, there's no need to specify the classpath at compile time. Instead, it uses the Java class loader to bring in the PostgreSQL code at run time.
Comments are closed.