Jetty ALPN Agent

jetty-alpn-agent is a JVM agent that enables TLS ALPN (or NPN) extension support for Java 7 and 8 by transforming relevant Java classes using the correct Jetty alpn-boot (or npn-boot) JAR file for the JVM version in use.

Starting with OpenJDK 1.8.0_252 the use of jetty-alpn-agent is not strictly required anymore since the standard ALPN APIs have been backported to OpenJDK 1.8.0_252 from Java 9.

Using jetty-alpn-agent with OpenJDK 1.8.0_252 or later performs no class transformation; the -javaagent option can be left in the command line, but it is encouraged to remove it.

Since no class transformation is performed with OpenJDK 1.8.0_252 or later, the libraries that provide the ALPN implementation must be aware of the backported standard API and use them to provide the ALPN implementation.

Usage

Specify the path to the agent JAR file with a -javaagent option:

java -javaagent:<path/to/jetty-alpn-agent.jar> ...

To use NPN instead of ALPN, specify the forceNpn=true option:

java -javaagent:<path/to/jetty-alpn-agent.jar>=forceNpn=true ...

To enable debug logs, specify the debug=true option:

java -javaagent:<path/to/jetty-alpn-agent.jar>=debug=true ...

Using with Maven

Use maven-dependency-plugin to fetch the agent JAR and add the path to the downloaded agent JAR to the command line arguments:

<project>
  <properties>
    <jetty.alpnAgent.version>2.0.0</jetty.alpnAgent.version>
    <jetty.alpnAgent.path>${settings.localRepository}/org/mortbay/jetty/alpn/jetty-alpn-agent/${jetty.alpnAgent.version}/jetty-alpn-agent-${jetty.alpnAgent.version}.jar</jetty.alpnAgent.path>
  </properties>
  
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>2.10</version>
        <executions>
          <execution>
            <id>get-jetty-alpn-agent</id>
            <phase>validate</phase>
            <goals>
              <goal>get</goal>
            </goals>
            <configuration>
              <groupId>org.mortbay.jetty.alpn</groupId>
              <artifactId>jetty-alpn-agent</artifactId>
              <version>${jetty.alpnAgent.version}</version>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.19.1</version>
        <configuration>
          <argLine>-javaagent:${jetty.alpnAgent.path}</argLine>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Additional resources

For more information, please refer to the following resources:

Jetty documentation: ALPN and NPN
Java API documentation: java.lang.instrument

Legal

This product is licensed under Apache License 2.0.

This product redistributes the original alpn-boot and npn-boot JARs, which are licensed under GPLv2 with classpath exception, whose source code is located at:

Credits

This library has been initially created by Trustin Lee. The Jetty Project took ownership in February 2016. Version 2.0.0 was the first release under the Jetty Project stewardship.

jetty-project / jetty-alpn-agent