Let's say you have one or more JAR files that contain classes that you want to make available to the applications deployed to one of your Tomcat application servers. If one and only one application needs to use the JAR, it probably makes sense to include the JAR in the applications /WEB-INF/lib folder.

When two or more applications need to use the JAR, then you will want to include the JAR in the <tomcat home>/bin/setenv.sh file.

The JAR file can either be static or dynamic. With static, the Tomcat application servers that are using the setenv.sh file will need to be restarted to use the JAR file. With dynamic, a restart is not always needed.

Static Java Agent (premain)

A static JAR uses the premain method.

public class PreMain {
  public static void premain(String agentArgument, Instrumentation instrument) {
    System.out.println("Premain Java Agent Loaded");
  }
}

The MANIFEST.MF file in the JAR file contains Premain-Class.

Premain-Class: PreMain

Let's say foo.jar is using premain. In this scenario, setenv.sh should have the -javaagent option followed by the path to the JAR file. In this example, the classes in foo.jar will be available to the applications deployed to the Tomcat application server.

export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/usr/local/tomcat/jars/foo.jar"

Restart Tomcat for this change to take effect.

/opt/tomcat/bin/shutdown.sh
/opt/tomcat/bin/startup.sh

The ps command can be used to confirm that Tomcat is using the JAR file.

ps -ef | grep -i tomcat

Dynamic Java Agent (agentmain)

A dyanmic JAR uses the agentmain method.

public class AgentMain {
  public static void agentmain(String agentArgument, Instrumentation instrument) {
    System.out.println("Agentmain Java Agent Loaded");
  }
}

The MANIFEST.MF file in the JAR file contains Agent-Class.

Agent-Class: AgentMain

The tools.jar file will need to be made available, as tools.jar provides the com.sun.tools.attach class, which is needed for a dynamic JAR. The tools.jar file should be included with your installation of Java, such as at /opt/java/lib/tools.jar on a Linux system. The tools.jar can be placed in setenv.sh to be loaded into the Tomcat application servers classpath.

export CLASSPATH="$CLASSPATH /opt/tomcat/bin/tools.jar"

Restart Tomcat for this change to take effect.

/opt/tomcat/bin/shutdown.sh
/opt/tomcat/bin/startup.sh

Then you would create a class that looks something like this.

package com.foo;

import java.lang.management.ManagementFactory;
import com.sun.tools.attach.VirtualMachine;

public class DynamicAgent {
	
    private static final String jarFilePath = "/opt/tomcat/bin/tools.jar"
            + "C:\\Users\\john.doe\\eclipse-workspace\\tools.jar";
	
    public static void loadAgent() {
        System.out.println("dynamically loading javaagent");
        String nameOfRunningVM = ManagementFactory.getRuntimeMXBean().getName();
        int p = nameOfRunningVM.indexOf('@');
        String pid = nameOfRunningVM.substring(0, p);

        try {
            VirtualMachine vm = VirtualMachine.attach(pid);
            vm.loadAgent(jarFilePath, "");
            vm.detach();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}