premain

Premain is a special entry point used by Java agents in the Java Instrumentation API. When a Java agent is packaged as a JAR and started with the -javaagent option, the JVM loads the agent before the application code and invokes the agent's premain method. This early execution allows the agent to instrument bytecode during class loading or to install transformers that modify classes as they are loaded.

Required manifest and signatures: The agent JAR must declare the Premain-Class attribute in its manifest, pointing to the class that contains the premain method. The premain method must be public, static, and void. There are two valid signatures: public static void premain(String agentArgs, Instrumentation inst) and public static void premain(String agentArgs). If the agent needs to perform instrumentation, the version with the Instrumentation parameter should be used.

Instrumentation and usage: The premain method receives an Instrumentation instance, which can be used to register ClassFileTransformer implementations via inst.addTransformer(transformer). The transformer can modify the bytecode of classes as they are loaded, enabling profiling, monitoring, or weaving. The Instrumentation interface also provides methods to redefine or retransform classes at runtime, subject to JVM support.

Relation to agentmain: premain runs at startup, before the application’s main method. In contrast, agentmain is invoked to attach to a running JVM after startup, typically via the attach API. Dynamic attachment requires additional setup (such as an Agent-Class in the manifest and appropriate tooling) to load the agent after the JVM has begun execution.