This article provides an introduction to the array of core new features available in JDBC 3.0. More specifically, the features ‘supporting save points’, ‘using parameter metadata’, ‘updating large objects’ and ‘auto generated keys’ are discussed. Wherever possible, to get a hang of it, relevant code samples have been provided in the respective sections.

Download Source Code: New Features in JDBC 3.0 (67)

Defining savepoints

It is possible to programmatically control the creation and releasing of save points through JDBC 3.0. But before doing it, one must check whether the underlying database supports the concepts of savepoints. Save points provide multiple-level-control of database commit or rollback operations within a single transaction. For example, if two unrelated database operations have to happen with a single transaction, these two save points can be created for the very purpose. Then based on various business conditions, commit/rollback can be done to any of these save points within the same transaction. To illustrate the usage, consider the following example,

package net.javabeat.jdbc3.newfeatures.savepoint;
import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.sql.PreparedStatement;
import java.sql.Savepoint;

import net.javabeat.jdbc3.newfeatures.CommonUtils;

public class SavepointTest {
 public static void main(String[] args) throws Exception{
	Connection connection = CommonUtils.getConnection();
	DatabaseMetaData databaseMetadata = connection.getMetaData();
	if (databaseMetadata.supportsSavepoints()){
		System.out.println("Savepoints supported by
		       the target database");
		processTable(connection);
	}
	}

	private static void processTable(Connection connection)
		throws Exception{
		PreparedStatement pStatement = connection.prepareStatement("
		          INSERT INTO CUSTOMER VALUES (?, ?)");
		pStatement.setInt(1, 1);
		pStatement.setString(2, "New Customer");
		pStatement.execute();
		Savepoint countrySavepoint =
			connection.setSavepoint("country");
		pStatement = connection.prepareStatement("
		          INSERT INTO COUNTRY VALUES (?, ?)");
		pStatement.setInt(1, 1);
		pStatement.setString(2, "India");
		// Make this transaction to fail deliberately
		connection.rollback(countrySavepoint);
		connection.commit();
	}
}

As seen from the above example, the program checks whether save points are supported by the target database by querying methods available in DatabaseMetadata. Note for save points are created by calling the method setSavePoint() defined on the Connection object. A save point can be given a name so that at a later point of time, a transaction can be made to commit or rollback based on the name. In the example code, to illustrate the usage of save point, we deliberately rollback the operation related to customer table, whereas, the changes made to country table are committed.

Parameter Metadata

Construction of queries for statements such as prepared statements might involve specifying dynamic values through ‘?’. Previously, there was no support for the tools or for the applications to identify the parameter information embedded in the queries. Now, support has been added to retrieve the parameter information that is passed to prepared statements. Please refer the below code that illustrates the usage,

package net.javabeat.jdbc3.newfeatures.pmd;

import java.sql.Connection;
import java.sql.ParameterMetaData;
import java.sql.PreparedStatement;

import net.javabeat.jdbc3.newfeatures.CommonUtils;

public class PMDTest {
	public static void main(String[] args) throws Exception{
		Connection connection = CommonUtils.getConnection();
		PreparedStatement pStatement = connection.prepareStatement(
			"INSERT INTO CUSTOMER VALUES (?, ?)");
		pStatement.setInt(1, 1);
		pStatement.setString(2, "New Customer");
		ParameterMetaData parameterMetadata = pStatement.getParameterMetaData();
		int parameterCount = parameterMetadata.getParameterCount();
		for (int index = 1; index <= parameterCount; index ++){
			String parameterClassName = parameterMetadata.getParameterClassName(index);
			int parameterMode = parameterMetadata.getParameterMode(index);
			String paramterTypeName = parameterMetadata.getParameterTypeName(index);
			System.out.println(parameterClassName + "/" + parameterMode + "/"
				+ "/" + paramterTypeName);
		}
	}
}

Auto Generated Keys

Execution of queries sometimes results in the automatic generation of fields or values for tables. The behavior is entirely dependent on the underlying database implementation. Previously, there was no standard mechanism for retrieving such information once the query is executed. Application developers are forced to use non-standard mechanisms for fetching information that happens outside the scope of query execution. For example, consider a table column containing a particular column, say ‘name’, and an equivalent upper column, let’s say ‘upper_name’. The value for the ‘upper_name’ will be automatically populated as soon as the value is populated for the ‘name’ column. This is one of the examples of auto generation feature and the newer specification supports this feature. Refer the code sample below,

package net.javabeat.jdbc3.newfeatures.autogenkey;

import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.sql.ResultSet;
import java.sql.Statement;

import net.javabeat.jdbc3.newfeatures.CommonUtils;

public class AutoGeneratedKeyTest {
	public static void main(String[] args) throws Exception{
		Connection connection = CommonUtils.getConnection();
		DatabaseMetaData databaseMetadata = connection.getMetaData();
		if (databaseMetadata.supportsGetGeneratedKeys()){
			processAutoGeneratedKeys(connection);
		}
	}

	private static void processAutoGeneratedKeys(Connection connection)
		throws Exception{
		System.out.println("Auto generated keys can be retrived");
		Statement statement = connection.createStatement();
		statement.execute("INSERT INTO ADDRESSINFORMATION (ADDRESSDATA ) " +
			"VALUES ('Address Text')", Statement.RETURN_GENERATED_KEYS);
		ResultSet resultSet = statement.getGeneratedKeys();
		java.sql.ResultSetMetaData rsMetadata = resultSet.getMetaData();
		for (int index = 1; index <= rsMetadata.getColumnCount(); index ++){
			while (resultSet.next()){
				String columnLabel = rsMetadata.getColumnName(index);
				System.out.println(resultSet.getObject(columnLabel));
			}
		}
	}

}

Note that, while executing the statement, the application has to provide indication to the underlying engine that, if any auto generation columns are applicable once the query is executed, those information have to be made available in the equivalent statement object. This is done through the method Statement.execute() where the second parameter specifies this option. Next, the method getGeneratedKeys() is added to the Statement object which returns a ResultSet containing the desired values. Because, this feature may or may not be supported by the database engine, the API supportsGeteGeneratedKeys() can be used to check the feature availability.

Updating clob/blob objects

The support to update clob objects is directly available on the Clob/Blob objects. The method updateClob() is added to the ResultSet object. Previously, there is no standard way to update large data objects. Note to ensure that this works and because the operation is defined on the ResultSet, the underlying ResultSet object should support updating the record. This is possible if the ResultSet is a flavor of CONCUR_UPDATABLE. Please refer the below code,

package net.javabeat.jdbc3.newfeatures.clblupdate;

import java.io.StringReader;
import java.sql.Clob;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;

import net.javabeat.jdbc3.newfeatures.CommonUtils;

public class ClobTest {

	public static void main(String[] args) throws Exception{
		Connection connection = CommonUtils.getConnection();
		int key = 1;
		insertClob(connection, key);
		readAndUpdateClob(connection, key);
	}

	private static void insertClob(Connection connection, int key)
		throws Exception{
		String sql = "INSERT INTO CLOBTEST VALUES (?, ?)";
		PreparedStatement pStatement = connection.prepareStatement(sql);
		pStatement.setInt(1, key);
		StringReader reader = new StringReader("som big data");
		pStatement.setClob(2, reader);
		pStatement.execute();
	}

	private static void readAndUpdateClob(Connection connection, int key)
		throws Exception{
		String sql =  "SELECT DATA FROM CLOBTEST WHERE ID = ?";
		PreparedStatement pStatement = connection.prepareStatement(
			sql, ResultSet.TYPE_SCROLL_SENSITIVE, ResultSet.CONCUR_UPDATABLE);
		pStatement.setInt(1, key);
		ResultSet resultSet = pStatement.executeQuery();
		if (resultSet.next()){
			Clob clobObject = resultSet.getClob(1);
			clobObject.setString(1, "new big data");
			resultSet.updateClob(1, clobObject);
		}
	}
}

Conclusion

Download Source Code: New Features in JDBC 3.0 (67)

The new features in JDBC 3.0 have addressed most of the common problems that tools or developer community is encountering, thereby providing a unified way of solution. There are other minor updates done to JDBC 3.0, such as ‘configuring connection pools’, ‘adding of new data types as Boolean, Datalink, URL’ etc.

Download Source Code: Java Agents (360)

Writing the first agent

This section details on writing the first java agent. The purpose of the agent will be get as simple as possible as the aim of this section is just to get a bit introduced to the the usage of java agents. Coding a agent requires writing a java class that has the premain() method. Please refer the below code.

package net.javabeat.articles.javaagent.test;
import java.lang.instrument.Instrumentation;
public class TestJavaAgent {
	public static void premain(String agentArgument,
                   Instrumentation instrumentation){
		System.out.println("Test Java Agent");
	}
}

Note that it is mandatory for agents to have the above method with the exact signature. Note that the above agent does nothing another that printing sample content to the console.

Manifest-Version: 1.0
Premain-Class: net.javabeat.articles.javaagent.
                                test.TestJavaAgent

Agents are packaged as jar files and are made visible to the application using the option ‘javaagent’. Note that it is essential for the jar file to have the Premain-Class attribute that specifies the fully qualified name of the agent class containing the premain method. Now that we have written an agent, we have to make use of the agent. For making use of the agent, let us create a sample java class as follows. Note that nowhere in the code, we are invoking the agent. Instead while running the application, agents are specified as virtual machine arguments.

package net.javabeat.articles.javaagent.test;

public class TestMain {

	public static void main(String[] args) {
		System.out.println("Test Main Class");
	}
}

• Create a jar file called ‘test-agent.jar’ by packaging the class file ‘net.javabeat.articles.javaagent.test.TestJavaAgent’ and the manifest file ‘MANIFEST.MF’
• Make use of the command, to run the agent, java -javaagent:test-agent.jar net.javabeat.articles.javaagent.test.TestMain

The above command will produce the below output,

Test Java Agent
Test Main Class

Note that there are several things to be noted in the above section. First of all, the agent to be run is passed as virtual machine parameter to the application. This is done through the option ‘javaagent’, what follows after that is ‘:’ followed by the path to the jar file. Note that agent classes are invoked first before the above application classes, this can be seen from the output produced by the sample program.

Writing a simple Agent

Now that we have familiarized with the several aspects involved in writing a simple agent, let us start adding some more functionality to the agent in this section. Consider the below code snippet representing the agent,

package net.javabeat.articles.javaagent.simple;
import java.lang.instrument.Instrumentation;
public class SimpleAgent {
	public static void premain(String agentArguments,
                      Instrumentation instrumentation){
		System.out.println("Simple Agent");
		SimpleClassTransformer transformer =
                    new SimpleClassTransformer();
		instrumentation.addTransformer(transformer);
	}
}

Note that the very purpose of having agent is to provide instrumentation capabilities to the application – i.e. the capability to re-define the signature of the class files during run-time. The method premain() is passed with Instrumentation object that serves its very purpose. Using Instrumentation object it is possible to adding transformer objects. Transformer object does the real job of transforming (or re-defining) the content of class files at run-time. The above code defines a transformer object, whose declaration is given below,

package net.javabeat.articles.javaagent.simple;
import java.lang.instrument.ClassFileTransformer;
import java.lang.instrument.IllegalClassFormatException;
import java.security.ProtectionDomain;
public class SimpleClassTransformer implements ClassFileTransformer{
	public byte[] transform(ClassLoader    loader,
            String              className,
            Class            classBeingRedefined,
            ProtectionDomain    protectionDomain,
            byte[]              classfileBuffer)
			throws IllegalClassFormatException {

		System.out.println(className);
		return classfileBuffer;
	}
}

Note that, a transformer object must implement the ClassFileTransformer interface and the abstract method transform needs to be overridden. This method will be called for every class that is loaded as part of the application. Note that the content of the class can be represented as byte array and this method can re-define the class content that returnss a different byte array (as denoted by the method signature). For simplicity, this method returns the original class byte array that is passed to it.

Manifest-Version: 1.0
Premain-Class: net.javabeat.articles.javaagent.simple.SimpleAgent

Given above is the content of the manifest file for the agent. Note that for testing the agent, we need a sample application file which is given below. To illustrate the behavior of class loading, the application creates instances for Test classes.

package net.javabeat.articles.javaagent.simple;
public class SimpleMain {
	public static void main(String[] args) {
		Test1 one = new Test1();
		Test2 two = new Test2();
		System.out.println("Simple Main " + one + two);
	}
}
class Test1{}
class Test2{}

Running the above application along with the agent will produce the following output.

Simple Agent
net/javabeat/articles/javaagent/simple/SimpleMain
net/javabeat/articles/javaagent/simple/Test1
net/javabeat/articles/javaagent/simple/Test2
Simple Main net.javabeat.articles.javaagent.simple.
Test1@61de33net.javabeat.articles.javaagent.simple.Test2@14318bb

Agents for collecting statistical data

In the last section, we have seen how to make use of Instrumentation object. We also saw how to manipulate Instrumentation object by adding Transformer objects. In this final section, we will see the real capability of agents for providing some statistical information about the methods being loaded for a particular class. For the purpose of illustration, let us expand the scope of the sample by provide a business class having empty business methods. Let us also assume that because the methods are for external usage, all the methods have to be public.

package net.javabeat.articles.javaagent.statistics;
public class MyBusinessClass {
	public void bizMethod1(){
		System.out.println("Biz Method 1");
	}
	@SuppressWarnings("unused")
	private void bizMethod2(){
		System.out.println("Biz Method 2");
	}
}

The above code has the definition of the business class. Deliberately, the modifier for the method bizMethod2() is given as private. The agent class is given below. Note that, as illustrated in the last section, this class makes use of Instrumentation object to add transformer objects to it.

package net.javabeat.articles.javaagent.statistics;
import java.lang.instrument.Instrumentation;
public class StatisticsAgent {
	public static void premain(String agentArguments,
                         Instrumentation instrumentation){
		StatisticsClassTransformer transformer =
                   new StatisticsClassTransformer();
		instrumentation.addTransformer(transformer);
	}
}

The flavor of the Transformer class that has the functionality of providing statistical information is given below. At this point, note that by the time when the agent is invoked, the class is not loaded. It is only during the class loading time, the agent is invoked. Hence reflection related APIs cannot be used at this point. For querying the method information for a particular class, the implementation makes use of ASM (byte code analysis library).

package net.javabeat.articles.javaagent.statistics;

import java.io.IOException;
import java.lang.instrument.ClassFileTransformer;
import java.lang.instrument.IllegalClassFormatException;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.security.ProtectionDomain;
import java.util.List;

import org.objectweb.asm.ClassReader;
import org.objectweb.asm.tree.ClassNode;
import org.objectweb.asm.tree.MethodNode;

public class StatisticsClassTransformer implements ClassFileTransformer{

	public byte[] transform(ClassLoader    loader,
            String              className,
            Class            classBeingRedefined,
            ProtectionDomain    protectionDomain,
            byte[]              classfileBuffer)
			throws IllegalClassFormatException {

		System.out.println();
		System.out.println("Processing class " + className);

		String normalizedClassName = className.replaceAll("/", ".");

		ClassReader classReader = null;
		try {
			classReader = new ClassReader(normalizedClassName);
		} catch (IOException e1) {
			e1.printStackTrace();
		}

		ClassNode classNode = new ClassNode();
		classReader.accept(classNode, ClassReader.SKIP_DEBUG);

		@SuppressWarnings("unchecked")
		List allMethods = classNode.methods;
		for (MethodNode methodNode : allMethods){
			System.out.println(methodNode.name);
		}
		return classfileBuffer;
	}

	private static void processBizMethods(Class classObject) {
		if (MyBusinessClass.class.equals(classObject)){
			Method[] allMethods = classObject.getDeclaredMethods();
			for (Method aMethod : allMethods){
				System.out.println(aMethod.getName());
				int modifiers = aMethod.getModifiers();
				if (Modifier.isPrivate(modifiers)){
					System.out.println("Method " +
                                        aMethod.getName() + " is private");
				}
			}
		}
	}

	public static void main(String[] args) {
		processBizMethods(MyBusinessClass.class);
	}
}

The content of the manifest file for the above agent is given below.

Manifest-Version: 1.0
Premain-Class: net.javabeat.articles.javaagent.statistics.StatisticsAgent

The content of the application that triggers the agent class is given below.

package net.javabeat.articles.javaagent.statistics;
public class StatisticsMain {
	public static void main(String[] args) {
		MyBusinessClass object = new MyBusinessClass();
		System.out.println("Biz Object " + object);
	}
}

The output of the application is given below,

Processing class net/javabeat/articles/javaagent/statistics/StatisticsMain
<init>
main

Processing class net/javabeat/articles/javaagent/statistics/MyBusinessClass
<init>
bizMethod1
bizMethod2
Biz Object net.javabeat.articles.javaagent.statistics.MyBusinessClass@a59698

Conclusion

Download Source Code: Java Agents (360)

This article provides introductory concepts about Java agents which are introduced from 5.0. It provides a good starter about the usage of agents by providing lot of examples. Hope the readers will be benefited after reading this article.