To enable ALPN support, start the JVM as follows:

java -Xbootclasspath/p:<path_to_alpn_boot_jar> ...

Where path_to_alpn_boot_jar is the path on the file system for the ALPN Boot Jar file,such as the one at the Maven coordinates org.mortbay.jetty.alpn:alpn-boot.

Be certain to get the ALPN Boot Jar version which matches the version of your JRE.

Applications need to interact with ALPN TLS extension protocol negotiations. For example, server applications need to know whether the client supports ALPN, and client applications needs to know whether the server supports ALPN.

To implement this interaction, Jetty’s ALPN implementation provides an API to applications, hosted at Maven coordinates org.eclipse.jetty.alpn:alpn-api. You need to declare this dependency as provided, because the alpn-boot jar already includes it (see the previous section), and it is therefore available from the boot classpath.

The API consists of a single class, org.eclipse.jetty.alpn.ALPN, and applications need to register instances of SSLSocket or SSLEngine with a ClientProvider or ServerProvider (depending on whether the application is a client application or server application). Refer to ALPN Javadocs and to the examples below for further details about client and server provider methods.

SSLContext sslContext = ...;
final SSLSocket sslSocket = (SSLSocket)context.getSocketFactory().createSocket("localhost", server.getLocalPort());

ALPN.put(sslSocket, new ALPN.ClientProvider()
{
    @Override
    public boolean supports()
    {
        return true;
    }

    @Override
    public List<String> protocols()
    {
        return Arrays.asList("h2", "http/1.1");
    }

    @Override
    public void unsupported()
    {
        ALPN.remove(sslSocket);
    }

    @Override
    public void selected(String protocol)
    {
        ALPN.remove(sslSocket);
        System.out.println("Protocol Selected is: " + protocol);
    }
});

The ALPN implementation calls ALPN.ClientProvider methods supports(), protocols(), unsupported() and selected(String), so that the client application can:

The example for SSLEngine is identical, and you just need to replace the SSLSocket instance with an SSLEngine instance.

final SSLSocket sslSocket = ...;
ALPN.put(sslSocket, new ALPN.ServerProvider()
{
    @Override
    public void unsupported()
    {
        ALPN.remove(sslSocket);
    }

    @Override
    public String select(List<String> protocols);
    {
        ALPN.remove(sslSocket);
        return protocols.get(0);
    }
});

The ALPN implementation calls ALPN.ServerProvider methods unsupported(), and select(List<String>), so that the server application can:

It is important that implementations of ALPN.ServerProvider and ALPN.ClientProvider remove the sslSocket or sslEngine when the negotiation is complete, like shown in the examples above.

Failing to do so will cause a memory leak.

You can write and run unit tests that use the ALPN implementation. The solution that we use with Maven is to specify an additional command line argument to the Surefire plugin:

<project>

<properties>
    <alpn-boot-version>8.1.4.v20150727</alpn-boot-version>
</properties>

<build>
    <plugins>
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <argLine>
                    -Xbootclasspath/p:${settings.localRepository}/org/mortbay/jetty/alpn/alpn-boot/${alpn-boot-version}/alpn-boot-${alpn-boot-version}.jar
                </argLine>
            </configuration>
        </plugin>

        ...

    </plugins>
</build>

...

</project>

You can enable debug logging for the ALPN implementation in this way:

ALPN.debug = true;

Since the ALPN class is in the boot classpath, we chose not to use logging libraries because we do not want to override application logging library choices; therefore the logging is performed directly on System.err.

The ALPN implementation relies on modification of a few OpenJDK classes and on a few new classes that need to live in the sun.security.ssl package. These classes are released under the same GPLv2+exception license of OpenJDK.

The ALPN class and its nested classes are released under same license as the classes of the Jetty project.

The ALPN implementation, relying on modifications of OpenJDK classes, updates every time there are updates to the modified OpenJDK classes.

This section is for Jetty developers that need to update the ALPN implementation with the OpenJDK versions.

Clone the OpenJDK repository with the following command:

$ hg clone http://hg.openjdk.java.net/jdk7u/jdk7u jdk7u # OpenJDK 7
$ hg clone http://hg.openjdk.java.net/jdk8u/jdk8u jdk8u # OpenJDK 8
$ cd !$
$ ./get_source.sh

To update the source to a specific tag, use the following command:

$ ./make/scripts/hgforest.sh update <tag-name>

The list of OpenJDK tags can be obtained from these pages: OpenJDK 7 / OpenJDK 8.

You will then need to compare and incorporate the OpenJDK source changes into the modified OpenJDK classes at the ALPN GitHub Repository, branch openjdk7 for OpenJDK 7 and branch master for OpenJDK 8.