Package prompto.utils

Class JarLoader

java.lang.Object

prompto.utils.JarLoader

public class JarLoader
extends Object

Adds JAR files to the class path dynamically. Uses an officially supported API where possible. To ensure use of the official method and compatibility with Java 9+, your app must be started with -javaagent:path/to/jar-loader.jar.

Author:

Chris Jennings <https://cgjennings.ca/contact.html>

Constructor Summary

Constructors

Constructor	Description
JarLoader()

Method Summary

Modifier and Type	Method	Description
static void	addToClassPath(File jarFile)	Adds a JAR file to the list of JAR files searched by the system class loader.
static void	addURL(URL url)
static void	addURLs(Collection<URL> urls)
static void	agentmain(String agentArgs, Instrumentation instrumentation)	Called by the JRE.
static String	getStrategy()	Returns a string that describes the strategy being used to add JAR files to the class path.
static boolean	isSupported()	Returns whether the extending the class path is supported on the host JRE.
static void	premain(String agentArgs, Instrumentation instrumentation)	Called by the JRE.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JarLoader

public JarLoader()

Method Detail

addURLs

public static void addURLs(Collection<URL> urls)
                    throws Exception

Throws:

Exception

addURL

public static void addURL(URL url)
                   throws Exception

Throws:

Exception

addToClassPath

public static void addToClassPath(File jarFile)
                           throws IOException

Adds a JAR file to the list of JAR files searched by the system class loader. This effectively adds a new JAR to the class path.

Parameters:

jarFile - the JAR file to add

Throws:

IOException - if there is an error accessing the JAR file

isSupported

public static boolean isSupported()

Returns whether the extending the class path is supported on the host JRE. If this returns false, the most likely causes are:

• the manifest is not configured to load the agent or the -javaagent:jarpath argument was not specified (Java 9+);
• security restrictions are preventing reflective access to the class loader (Java ≤ 8);
• the underlying VM neither supports agents nor uses URLClassLoader as its system class loader (extremely unlikely from Java 1.6+).

Returns:

true if the Jar loader is supported on the Java runtime

getStrategy

public static String getStrategy()

Returns a string that describes the strategy being used to add JAR files to the class path. This is meant mainly to assist with debugging and diagnosing client issues.

Returns:

returns "none" if no strategy was found, otherwise a short describing the method used; the value "reflection" indicates that a fallback not compatible with Java 9+ is being used

premain

public static void premain(String agentArgs,
                           Instrumentation instrumentation)

Called by the JRE. Do not call this method from user code.

This method is automatically invoked when the JRE loads this class as an agent using the option -javaagent:jarPathOfThisClass.

For this to work the MANIFEST.MF file must include the line Premain-Class: prompto.utils.JarLoader.

Parameters:

agentArgs - agent arguments; currently ignored

instrumentation - provided by the JRE

agentmain

public static void agentmain(String agentArgs,
                             Instrumentation instrumentation)

Called by the JRE. Do not call this method from user code.

This method is called when the agent is attached to a running process. In practice, this is not how JarLoader is used, but it is implemented should you need it.

For this to work the MANIFEST.MF file must include the line Agent-Class: prompto.utils.JarLoader.

Parameters:

agentArgs - agent arguments; currently ignored

instrumentation - provided by the JRE