As a quick review, the project is a web service that allows accessing peanut butter & jelly sandwiches over HTTP. It has a primitive “stats” resource to allow you to see how many sandwiches have been made and how much peanut butter & jelly was used. This stats facility is more of demo of how to wire stuff together with Guice and how requests are routed to JAX-RS resources than a useful way to monitor usage, though.

We’re going to do two things to improve the situation. First, we’ll re-implement the number of sandwiches and amount of PB&J tracking using individual Counters and Gauges. Second, we’ll add code to automatically create various useful metrics for every resource method via Jersey ResourceFilter, ResourceFilterFactory, ContainerFilterResponseFilter, ResourceMethodDispatchAdapter, and ResourceMethodDispatchProvider implementations. Fun! :)

As before, I’ll outline the code changes in this article, but the complete code is in the repo for your browsing pleasure.

Reimplementing Sandwich stats

The SandwichStats object (a singleton) keeps track of the number of sandwiches and the amount of PB & J used to make them. This data is exposed through SandwichStatsResource, which response to GET of /sandwich/stats with data like {"sandwichesMade":2,"gramsOfJam":200,"gramsOfPeanutButter":400}. We want to keep track of those three numbers with metrics now as well. Metrics (the library) offers many different types of metrics (the concept). For these three numbers, there are two ways we could do it. We could use a Gauge to expose the numbers that SandwichStats is already tracking internally, or we could use a Counter that we increment whenever we increment the fields that SandwichStats already has. To demonstrate the use of Gauges and Counters, we’ll do some of both.

When creating a metric object, you can use a MetricsRegistry instance or the static method on the Metrics class. If you have multiple applications running inside the same JVM, or need that separation of metrics for other reasons, use MetricsRegistery. If you aren’t doing that, you can use the static methods on Metrics, but we’ll go ahead and use a MetricsRegistry because it’s just as easy as using the Metrics class when we have Guice to help us.

First, add a binding for MetricsRegistry in a Guice module:

    bind(MetricsRegistry.class).toInstance(Metrics.defaultRegistry());

We’ll inject a MetricsRegistry into the SandwichStats ctor:

private final Counter jamCounter;
private final Counter pbCounter;
 
@Inject
SandwichStats(MetricsRegistry metricsRegistry) {
    metricsRegistry.newGauge(SandwichStats.class, "sandwich-count", new Gauge<Integer>() {
	@Override
	public Integer value() {
	    return sandwichesMade;
	}
    });
    jamCounter = metricsRegistry.newCounter(SandwichStats.class, "grams-of-jam");
    pbCounter = metricsRegistry.newCounter(SandwichStats.class, "grams-of-pb");
}

Then, we can update the existing recordSandwich method:

synchronized void recordSandwich(Sandwich sandwich) {
    sandwichesMade++;
    gramsOfJam += sandwich.getGramsOfJam();
    gramsOfPeanutButter += sandwich.getGramsOfPeanutButter();
 
    jamCounter.inc(sandwich.getGramsOfJam());
    pbCounter.inc(sandwich.getGramsOfPeanutButter());
}

We don’t have to do anything for the “sandwich-count” metric because it’s a Gauge that references the existing field. The other two metrics are Counters, and therefore need to be updated separately.

Start up the service’s main method and open JConsole. When you connect to your process, open the MBeans tab and look in the com.teamlazerbeez.http.sandwich package. You should see some SandwichStats MBeans. Expand the grams-of-jam MBean, select the attribute and double click the numeric value to open a graph. Re-run the /sandwich/create request a few times and note that the graph will periodically update.

Automatic Jersey Request Metrics

Using and creating metrics by hand is already useful, but we can do better. We’re going to hook into the Jersey request dispatch mechanism to automatically create metrics for per-status code counts, etc. for every JAX-RS resource method.

In Jersey, resource methods are represented by subclasses of AbstractMethod. AbstractMethod is an abstract class representing a method that is invoked by Jersey. This could be a setter that’s invoked by Jersey’s IoC mechanism or a resource method or other types of methods. We only care about two subclasses: AbstractResourceMethod and AbstractSubResourceMethod (a subclass of AbstractResourceMethod). In JAX-RS, a resource method is one that uses the @Path annotation of its containing class, and a sub-resource method is one that has a @Path annotation of its own.

There are two mechanisms that we’re going to use in the Jersey request invocation pipeline to do this. We’ll do the the simpler one first.

Per-resource method counters with ResourceFilterFactory

Think of a Jersey ResourceFilter as filling a subset of the role of a javax.servlet.Filter. It can observe and modify the input and the output of a JAX-RS method invocation, but it does not wrap the actual invocation the way a servlet Filter does. This is still useful, though, since we can observe the HTTP status codes being output and create metrics to expose them.

A ResourceFilter itself doesn’t do much of anything except provide getters for ContainerRequestFilter and ContainerResponseFilter. Those two do the actual work. In our case (observing status codes) we only care about the latter. However, ResourceFilter objects are created by ResourceFilterFactory implementations, so we’ll start there. Here’s part of an implementation of a ResourceFilterFactory (check the source for the full details):

@Override
public List<ResourceFilter> create(AbstractMethod am) {
    // documented to only be AbstractSubResourceLocator, AbstractResourceMethod, or AbstractSubResourceMethod
    if (am instanceof AbstractSubResourceLocator) {
	// not actually invoked per request, nothing to do
	logger.debug("Ignoring AbstractSubResourceLocator " + am);
	return null;
    } else if (am instanceof AbstractResourceMethod) {
	String metricBaseName = getMetricBaseName((AbstractResourceMethod) am);
	Class<?> resourceClass = am.getResource().getResourceClass();
 
	return Lists.<ResourceFilter>newArrayList(
		new HttpStatusCodeMetricResourceFilter(metricBaseName, resourceClass));
    } else {
	logger.warn("Got an unexpected instance of " + am.getClass().getName() + ": " + am);
	return null;
    }
}

What we see here is that if the AbstractMethod is an AbstractResourceMethod, we generate a ‘metricBaseName’ (a prefix common to all metrics tied to that resource method) and return a list of ResourceFilter objects containing a HttpStatusCodeMetricResourceFilter, which is one of our classes. Here’s what that class does (again, check the source).

final class HttpStatusCodeMetricResourceFilter implements ResourceFilter, ContainerResponseFilter {
 
    ....
 
    @Override
    public ContainerResponse filter(ContainerRequest request, ContainerResponse response) {
        Integer status = response.getStatus();
 
        Counter counter = counters.get(status);
        if (counter == null) {
            // despite the method name, this actually will return a previously created metric with the same name
            Counter newCounter = metricsRegistry.newCounter(resourceClass, metricBaseName + " " + status + " counter");
            Counter otherCounter = counters.putIfAbsent(status, newCounter);
            if (otherCounter != null) {
                // we lost the race to set that counter, but shouldn't create a duplicate since Metrics.newCounter will do the right thing
                counter = otherCounter;
            } else {
                counter = newCounter;
            }
        }
 
        counter.inc();
 
        return response;
    }
}

This filter doesn’t modify the response; instead, it just gets the HTTP status, gets the appropriate Counter (creating it if need be), and increments it.

We have enough now to be able to hook our status-code-counting filter into Jersey. This is a little ungainly, but basically we’re informing GuiceContainer (the Jersey code that interacts with Guice and Guice Servlet) the ResourceFilterFactory to use. You can specify more than one (comma-separated strings, Class[], etc — check the docs on ResourceConfig.PROPERTY_RESOURCE_FILTER_FACTORIES) but we have just one here.
Before:

serve("/*").with(GuiceContainer.class);

After:

Map<String, String> guiceContainerConfig = new HashMap<String, String>();
guiceContainerConfig.put(ResourceConfig.PROPERTY_RESOURCE_FILTER_FACTORIES,
    HttpStatusCodeMetricResourceFilterFactory.class.getCanonicalName());
serve("/*").with(GuiceContainer.class, guiceContainerConfig);

Start up the service and check the MBeans. You’ll see SandwichStats, but nothing for the SandwichMakerResource until you use the “/sandwich/create” endpoint. Once you do that, you’ll see a metric named “/sandwich/create GET 200 counter” appear, and it will update appropriately as you make more requests.

Per-resource method timing with ResourceMethodDispatchAdapter and friends

Status code counters are great, but we really want to be able to generate timing info for request invocation, and to get timing information we’d have to use a ThreadLocal in a ContainerRequestFilter/ContainerResponseFilter pair, and that’s not how we roll.

The Metrics library has built-in support for timing method invocations if you annotate the methods you wish to be timed with @Timed. This uses Guice AOP under the hood, which has a few limitations (no non-final classes, must instantiate via Guice, etc.), so let’s see if we can do it a little less invasively.

We’ll hook into the Jersey method invocation mechanism via ResourceMethodDispatchAdapter and ResourceMethodDispatchProvider. A ResourceMethodDispatchProvider is responsible for creating RequestDispatcher objects for AbstractResourceMethods, and a ResourceMethodDispatchAdapter is a Jersey extension mechanism to allow us to control what ResourceMethodDispatchProvider gets used. Therefore, by registering our ResourceMethodDispatchAdapter, we can wrap the default ResourceMethodDispatchProvider with one that gathers timing info. The code you’ll see here does timing for all resource methods, but you could trivially make it conditional on an annotation on the resource method or class or anything you wish.

We’ll start with our custom RequestDispatcher implementation TimingRequestDispatcher. We want to use whatever dispatcher Jersey provides under the hood, so we wrap that dispatcher and just capture timing info.

@Override
public void dispatch(Object resource, HttpContext context) {
    final TimerContext time = timer.time();
 
    try {
	wrappedDispatcher.dispatch(resource, context);
    } finally {
	time.stop();
    }
}

We then can use this RequestDispatcher in TimingResourceMethodDispatchProvider. If you wanted to have conditional logic to sometimes not create timers, this would be a good place to do it.

@Override
public RequestDispatcher create(AbstractResourceMethod abstractResourceMethod) {
    String metricBaseName = getMetricBaseName(abstractResourceMethod);
    Timer timer = metricsRegistry.newTimer(abstractResourceMethod.getResource().getResourceClass(),
	metricBaseName + " timer");
    return new TimingRequestDispatcher(wrappedProvider.create(abstractResourceMethod), timer);
}

We can use that ResourceMethodDispatchProvider in a TimingResourceMethodDispatchAdapter.

@Override
public ResourceMethodDispatchProvider adapt(ResourceMethodDispatchProvider provider) {
    return new TimingResourceMethodDispatchProvider(metricsRegistry, provider);
}

And then bind your Adapter class (which must also be annotated with com.google.inject.Singleton and javax.ws.rs.ext.Provider):

bind(TimingResourceMethodDispatchAdapter.class);

Start up the service and you should see Timer metrics being generated for all endpoints. It’s a little bit more convoluted to use the ResourceMethodDispatchAdapter approach, but it’s probably only really needed for timing; the ResourceFilterFactory approach should work for most everything else. Either way, now you know how to use the basics of the Metrics library, and how to execute custom logic before (ContainerRequestFilter), after (ContainerResponseFilter), and around (ResourceMethodDispatchAdapter) Jersey resource method invocation.

Basic terminology

Certificate or cert

The public half of a public/private key pair, though it’s not generally referred to as a key. This part is freely given to anyone.

Private key

A private key is never given out publicly. It is used to sign or encrypt data. A private key can be used to verify that its corresponding certificate was used to sign or encrypt things and vice versa.

Certificate Signing Request or CSR

A file that you generate with your private key. You can send just the CSR to your CA and they will create a signed certificate for you.

Certificate Authority or CA

These are places like Thawte that you pay in order to get a certificate that browsers will accept. You can also use someone like CACert.org to get a free certificate that browsers will not accept. You can also generate your own simple CA using openssl. A CA uses its private key to digitally sign a CSR and create a signed cert so that browsers can use the CA’s cert to tell that your cert is approved by that CA.

Distinguished Name or DN

This is defined by LDAP. It’s a grouping of RDNs (Relative Distinguished Names). A RDN is something like “CN=your name”. This one means that the Common Name is set to the string “your name”. A DN would be something like “CN=your name,OU=Engineering,O=Initech”. In this case, OU means Organizational Unit and O means Organization.

A specification governing the format and usage of certificates.

How client certs are supposed to work

This is a greatly simplified explanation of the TLS 1.0 protocol. Check out the RFC for more details at around section 7.4. (There are newer versions of TLS, but 1.0 is what Java 6 supports.) I’m showing the case where client certificates have been configured on the server side, so this isn’t exactly what happens when you do normal server-only TLS.

1. ClientHello: client informs server what ciphers and compression methods it supports
2. ServerHello
   • Server picks a cipher and compression that both it and the client support and tells the client about its choices, as well as some other things like a session id
   • It presents its certificate (this is what the client needs to validate as being signed by a trusted CA)
   • It presents a list of certificate authority DNs that client certs may be signed by
3. Client response
   • The client continues the key exchange protocol necessary to set up a TLS session
   • The client presents a certificate that was signed by one of the CAs described in the Server hello
4. The server accepts the cert that the client presented and all is well

Note that the ServerHello does not ask for specific client certificates. It just provides info about CAs (in the form of DNs) and expects the client to figure out an appropriate cert that was signed by one of those CAs.

File formats for certs and keys

There are many different formats used for storing keys and certs on-disk, but the most common ones are probably PEM, PKCS12, and JKS. The formats are not treated equally by Java, so it’s important to understand the different formats. It’s not obvious how to manipulate these formats, so I’ve also included sample commands for working them them.

PEM

PEM is just DER that’s been Base64 encoded. It looks like this for a certificate:

-----BEGIN CERTIFICATE-----
(base 64 encoded stuff)
-----END CERTIFICATE-----

or for a private key:

-----BEGIN PRIVATE KEY-----
(base 64 encoded stuff)
-----END PRIVATE KEY-----

Sometimes PEM files will have a human-readable block of text above the Base64 encoded block. You can safely remove this human-readable text. (It confuses Java’s keytool.)

Some applications prefer the cert PEM and the private key PEM to be in one file. (Apache httpd is one, if I remember correctly.) Since PEM files are just plain text, you can do that with cat: cat cert.pem key.pem > cert-with-key.pem. While you could arbitrarily combine as many PEM blocks as you wanted into one file, typically they are kept separate except for this one case.

You can get a human-readable description of a cert in PEM format with openssl x509 -in cert.pem -noout -text. (Certs are X509 formatted, hence the ‘x509′ subcommand to openssl.) For keys, the command is openssl rsa -in key.pem -text -noout.

Private keys can also be encrypted, in which case the marker block will say BEGIN ENCRYPTED PRIVATE KEY. You can create the decrypted form of the key with openssl rsa -in key-encrypted.pem -out key-decrypted.pem.

PKCS12

PKCS12 is a password-protected format that can contain multiple certificates and keys.

You can view the contents of a PKCS12 file (typically .p12 is used for PKCS12 files) with openssl pkcs12 -in file.p12. Add -info for a little bit more metadata. Note that if the file includes a private key, openssl will ask you for another password after asking for the decryption password for the PKCS12 file. This second password is used to encrypt the private key before displaying its PEM data to you. You could put this data in a separate file and decrypt it as shown above if you want the decrypted form.

You can create PKCS12 files with or without private keys or CA certs.
Cert and key:
openssl pkcs12 -export -out cert-and-key.p12 -in cert.pem -inkey key.pem
Cert and key that includes the CA cert that signed the cert:
openssl pkcs12 -export -out cert-and-key-with-ca.p12 -in cert.pem -inkey key.pem -CAfile /path/to/cacert.pem -chain
Cert without key (useful for CA certs):
openssl pkcs12 -export -out cacert.p12 -in cacert.pem -nokeys

JKS

A JKS keystore stores multiple certs and keys like PKCS12, but it’s just a Java thing, not a widespread standard like PKCS12. The tool to manage JKS files is ‘keytool’ which ships with the JDK. Entries in a JKS file have an “alias” that must be unique. If you don’t specify an alias, it will use “mycert” by default. This is fine if you’re only putting one thing in a keystore, but if you add another thing you’ll get an error because it will try to use the same (default) alias twice. JKS keystores also have a password, just like PKCS12.

You can use keytool to add PEM and PKCS12 files.
Create JKS with cert, key and CA cert from PKCS12:
keytool -importkeystore -destkeystore cert-and-key-with-ca.jks -srckeystore cert-and-key-with-ca.p12 -srcstoretype PKCS12
Add a CA cert, then add the cert without a key:
keytool -keystore cacert-added-then-cert-nokey.jks -import -file cacert.pem -alias cacert (Say yes when it asks if you want to trust the CA)
keytool -keystore cacert-added-then-cert-nokey.jks -import -file cert.pem -alias cert
Add a CA cert, then add the cert with a key:
keytool -keystore cacert-added-then-cert-withkey.jks -import -file cacert.pem -alias cacert (Say yes when it asks if you want to trust the CA)
keytool -destkeystore cacert-added-then-cert-withkey.jks -importkeystore -srckeystore cert-and-key.p12 -srcstoretype PKCS12

TLS with Java

There are going to be a lot of certs involved in configuring TLS, so let’s first decide on some names.

• server-cert: the cert that the server presents to clients
• server-key: the private key that corresponds to server-cert
• server-ca-cert: the cert of the CA that signed server-cert
• client-cert: the cert that the client presents to the server (if asked to)
• client-key: the private key that corresponds to client-cert
• client-ca-cert: the cert of the CA that signed client-cert

When client certs aren’t enabled, the server presents server-cert to the client. If the client has server-ca-cert designated as a trusted CA, the connection can proceed. When client certs are enabled, the server presents server-cert as its cert and also sends the DN of client-ca-cert. The client checks server-cert against its trusted CA certs as before. It then looks for any certs that it has that are signed by client-ca-cert, finds client-cert, and sends that back. The server-key and client-key keys are used in other parts of the TLS protocol. To be as general as possible, I’m going to assume that client-ca-cert and server-ca-cert are not the same cert and are also not in the system-wide set of trusted CAs.

Oracle’s JSSE Reference Guide is useful when figuring out how all these crypto classes fit together, so you may want to have that open as a reference.

If you want to examine the internals of the SSLSocket/SSLServerSocket implementation, set the system property javax.net.debug to “all” for maximum verbosity. You can download the OpenJDK code and step through it by looking for where the debug statements are printed. It’s not as good as a debugger, but there’s not much code and the debug statements are frequent enough that it’s not hard to follow. Wireshark is also extremely useful.

In Java, you use SSLSocketFactory to get SSLSockets and and SSLServerSocketFactory to get SSLServerSocket instances. The simplest usage looks like this:

/* 
 * The static getDefault() methods return the non-SSL
 * factory classes, so they have to be cast.
 */
SSLServerSocketFactory serverSocketFactory = 
    (SSLServerSocketFactory) SSLServerSocketFactory.getDefault();
SSLServerSocket serverSocket = 
    (SSLServerSocket) serverSocketFactory.createServerSocket(8443);
 
SSLSocketFactory socketFactory = 
    (SSLSocketFactory) SSLSocketFactory.getDefault();
SSLSocket socket = 
    (SSLSocket) socketFactory.createSocket("localhost", 8443); 
 
// do the standard socket stuff with byte streams, etc.

This isn’t really going to work, though, since we haven’t told the server socket what cert to use. Time for more terminology!

• A keystore has certs and keys in it and defines what is going to be presented to the other end of a connection.
• A truststore has just certs in it and defines what certs that the other end will send are to be trusted. You could put keys in a truststore, but they wouldn’t be used for anything.

Confusingly, the Java class java.security.KeyStore is used in the process of creating both keystores and truststores. I will be careful to capitalize as KeyStore when I mean the class as opposed to the conceptual items.

For the server socket, we need to specify a keystore containing server-cert and server-key. We also need a truststore containing client-ca-cert. For the client socket, we need a keystore containing the client cert and key and a truststore containing the server-ca-cert.

To get these keystores and truststores, we need to construct KeyStore instances with the appropriate certificate and key data. KeyStores can be created for JKS or PKCS12 files. This code creates a KeyStore and loads data from an input stream. After load() has been called, the KeyStore is ready for use.

// keyStoreType is either "JKS" or "PKCS12"
KeyStore keyStore = KeyStore.getInstance(keyStoreType);
keyStore.load(inputStream, keyStorePassword.toCharArray());

A KeyStore is just an intermediate step, though. Once we have a KeyStore with the keystore data and a KeyStore with the truststore data, the next step is a TrustManager (for a truststore) and a KeyManager (for a keystore).

TrustManagerFactory trustManagerFactory = 
    TrustManagerFactory.getInstance("PKIX", "SunJSSE");
trustManagerFactory.init(trustStore);

Now we have a TrustManagerFactory instance. JSSE is fairly agnostic towards cryptosystems, so it can, at least in theory, support things beyond X509. In practice, X509 is all we care about, and looking in the OpenJDK source code will give the impression that X509 is all it’s built to support anyway. The “PKIX” algorithm implements cert-chain validation for X509 certs. A TrustManagerFactory can create an array of TrustManagers, one for each type of “trust material”. We only care about the X509TrustManager instance.

X509TrustManager x509TrustManager = null;
for (TrustManager trustManager : trustManagerFactory.getTrustManagers()) {
    if (trustManager instanceof X509TrustManager) {
	x509TrustManager = (X509TrustManager) trustManager;
	break;
    }
}
 
if (x509TrustManager == null) {
    throw new NullPointerException();
}

Now we have the X509TrustManager instance we want. A similar approach will get you the X509KeyManager.

KeyManagerFactory keyManagerFactory = 
    KeyManagerFactory.getInstance("SunX509", "SunJSSE");
keyManagerFactory.init(keyStore, password.toCharArray());
 
X509KeyManager x509KeyManager = null;
for (KeyManager keyManager : keyManagerFactory.getKeyManagers()) {
    if (keyManager instanceof X509KeyManager) {
	x509KeyManager = (X509KeyManager) keyManager;
	break;
    }
}
 
if (x509KeyManager == null) {
    throw new NullPointerException();
}

Now you can construct an SSLContext. Here’s the code to create a SSLServerSocket.

// load in the appropriate keystore and truststore for the server
// get the X509KeyManager and X509TrustManager instances
 
SSLContext sslContext = SSLContext.getInstance("TLS");
// the final null means use the default secure random source
sslContext.init(new KeyManager[]{keyManager}, 
    new TrustManager[]{trustManager}, null);
 
SSLServerSocketFactory serverSocketFactory = 
    sslContext.getServerSocketFactory();
SSLServerSocket serverSocket = 
    (SSLServerSocket) serverSocketFactory.createServerSocket(PORT);
 
serverSocket.setNeedClientAuth(true);
// prevent older protocols from being used, especially SSL2 which is insecure
serverSocket.setEnabledProtocols(new String[]{"TLSv1"});
 
// you can now call accept() on the server socket, etc

And here’s how to construct an SSLSocket. Make sure you don’t use the same keystore and truststore that you did for the server! They almost certainly need to be different.

// load in the appropriate keystore and truststore for the client
// get the X509KeyManager and X509TrustManager instances
 
SSLContext sslContext = SSLContext.getInstance("TLS");
 
sslContext.init(new KeyManager[]{keyManager}, 
    new TrustManager[]{trustManager}, null);
 
SSLSocketFactory socketFactory = sslContext.getSocketFactory();
SSLSocket socket = 
    (SSLSocket) socketFactory.createSocket("localhost", SslServer.PORT);
 
socket.setEnabledProtocols(new String[]{"TLSv1"});
 
// read from the socket, etc

It should now work. Unfortunately, Java’s default KeyStore implementation has some bugs, so depending on how you set up your server-side trust store, it may or may not work.

But it doesn’t work when I try that!

There’s a bug in the way cert chains are handled for X509TrustManager objects in the Sun/Oracle implementation. A quick look in the OpenJDK code in sun.security.ssl.X509TrustManagerImpl and sun.security.validator.KeyStores shows that the logic used to get issuers is simply wrong. In the case where the KeyStore entry in a KeyStore is a key entry (not a bare cert), it unconditionally uses the first cert in the chain of certs for that key, regardless of whether or not it is even a CA cert or the actual issuing cert in the chain. In fact, the documentation for KeyStore.getCertificateChain() says that the root cert is the last cert in the chain, not the first. This code was probably tested using self-signed certs (which only have one cert in the chain, so it will always work) and not using separate CA certs.

There’s also a separate bug in the way PKCS12 files are loaded. It looks like maybe the PKCS12 parsing code can’t figure out what to do when there isn’t a private key. I haven’t looked into the source of that bug yet. The SunJSSE description in the JSSE Reference Guide has this terse note: “Storing trusted anchors in PKCS12 is not supported. Users should store trust anchors in JKS format and save private keys in PKCS12 format.” It’s unfortunate that this isn’t broadcast more clearly in the documentation.

If you load a PKCS12 file containing just client-ca-cert, you get nothing in the server’s X509TrustManager KeyStore. This is the PKCS12 loading bug. When you connect a client, you get java.net.SocketException: Broken pipe on the client side and javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: No trusted certificate found on the server. This happens because the server has sent a CertificateRequest in the ServerHello, but has not included any DNs for the client to look up certs by.

Construct a PKCS12 file containing client-cert, client-key, and client-ca-cert and then import that in one step (using the -importkeystore option to keytool). If you load that PKCS12 file or the resulting JKS, you get a chain of client-cert and client-ca-cert in the KeyStore. This is correct. However, X509TrustManager.getIssuers() mistakenly returns client-cert as an issuer (which it is not) and does not return client-ca-cert. The correct behavior would be to return only client-ca-cert. (An “issuer” is a CA.) In this case, you get javax.net.ssl.SSLHandshakeException: Received fatal alert: bad_certificate on the client and javax.net.ssl.SSLHandshakeException: null cert chain on the server. The server sends the DN of client-cert in the CertificateRequest part of the ServerHello. The client (correctly) does not find any certs signed by that cert, so it returns no certificates. The server rejects the connection with error code 42 for “bad certificate” (see the TLS RFC section A.3 for error codes) and dies with its own error that (accurately) says there is a null certificate chain from the client.

If you load a JKS file that was created by separately adding client-ca-cert in step 1 (using -import -file client-ca-cert.pem) and then the client-cert (with -import -file client-cert.pem or -importkeystore with a p12 containing client-cert and client-pem) in step 2, the JKS will have two separate entries instead of one entry containing a chain of certs. This will lead to getIssuers() returning both client-cert and client-ca-cert, so both certs will have their DNs in the ServerHello. This is technically incorrect (client-cert is not a CA cert) but does work.

The good news

Fortunately, the JKS implementation of KeyStore is not suffering from the same bug as the PKCS12 code. A KeyStore loaded from a JKS containing only client-ca-cert does end up with a cert in it. Since it’s just a cert, not a cert in a chain attached to a key, it avoids the buggy code path in KeyStores, so the correct DN gets sent to the client in the ServerHello and all proceeds normally.

The result of all this analysis:
For your SSLServerSocket’s TrustManager’s KeyStore, use a JKS containing only the CA cert for the client certs. If you us a PKCS12, you’ll get no certs. If you include the cert and key that you’re looking for as well as the CA cert and you create the JKS keystore from one PKCS12 containing all three entities, you’ll get the wrong cert. If you create a JKS keystore using the CA cert and then add the client cert (with or without key) later, you’ll get too many certs.

This sounds great for spinning up an instance of mysqld for testing, but there are a few issues to be solved. MySQL hasn’t published any recent versions of MXJ to the central Maven repository, so you’ll have to install the files by hand into your local ~/.m2 (or repo server, if you have one set up). Also, they don’t include 64-bit Linux binaries.
Update: I have submitted artifacts for Connector/MXJ 5.0.12 to Maven Central and they have been approved, so you need only add the following dependency to your code and you’re good to go.

<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-mxj</artifactId>
  <version>5.0.12</version>
  <scope>test</scope>
</dependency>

If you’d like to build the artifacts yourself, carry on with the instructions…

Download the zip distribution yourself from MySQL’s download page (5.0.12 is current as of this article). When unzipped, you’ll find two jars: mysql-connector-mxj-gpl-5-0-12-db-files.jar (the ‘db-files’ jar) and mysql-connector-mxj-gpl-5-0-12.jar (the ‘mxj’ jar). The mxj jar is quite small and just contains some Java classes. The db-files jar is pretty hefty because it contains the actual binaries for x86 32-bit FreeBSD, Linux, Mac OS X, Windows and Solaris (as well as Solaris on SPARC in case anyone still uses that…).

Alas, no 64-bit Linux… If this doesn’t affect you, skip to the end of the article to see how to install the jars correctly into your local ~/.m2 repo. You’ll know that you’re hitting this problem if you get output like this:

[MysqldResource] launching mysqld (driver_launched_mysqld_1)
/tmp/test-mxj/bin/mysqld: error while loading shared libraries: libaio.so.1: cannot open shared object file: No such file or directory

This is (correctly) saying is that the 32-bit mysqld binary cannot find libaio. You should have libaio installed since the 64-bit version we’ll be building will need it, though!

Adding 64-bit Linux binaries to the db-files jar

Fortunately, MySQL provides instructions on how to modify the db-files jar. If you’d rather use my pre-built jar with Linux 64-bit binaries, go to the end of the article. Download the mysql 5.5.9 source tarball from the MySQL archives. 5.5.9 isn’t the latest version, but all the other binaries in MXJ 5.0.12 were built with 5.5.9 so we’ll use that to stay consistent. The source installation manual shows the steps necessary to perform a complete installation. We don’t need to do all of that since we just need the compiled code.

cmake .
make

The mysql binary is in client/mysql and the mysqld binary is in sql/mysqld.

Extract mysql-connector-mxj-gpl-5-0-12-db-files.jar into a directory of your choosing so we can add in proper 64-bit versions of mysql and mysqld.

The actual binaries that are run is determined by the platform-map.properties file in the root of db-files jar. Replace the following section

Linux-x86_64=Linux-i386
Linux-amd64=Linux-i386

with

Linux-x86_64=Linux-x86_64
Linux-amd64=Linux-x86_64

This means that when x86_64 or amd64 are seen in the os.arch Java system property, the contents of the Linux-x86_64 directory will be used. First, we’ll need the directory to exist inside the 5-5-9 directory:

mkdir 5-5-9/Linux-x86_64

Copy your newly compiled mysql and mysqld binaries into the Linux-x86_64 directory, and add a version.txt file containing appropriate contents. I followed the template of the Linux-i386 version, modifying for my newer kernel (3.0.4) and platform (x86_64).

mysql-5.5.9-linux3.0.4-x86_64/bin/mysqld

Go back to the root of the extracted jar, then create a new jar.

jar -cf ../mysql-connector-mxj-gpl-5-0-12-db-files.jar *

Installing the Maven artifacts

Now we’ve constructed a mysql-connector-mxj-gpl-5-0-12-db-files.jar. To use it, you’ll need to install it into your ~/.m2 repo. I’ve built a very simple pom.xml for it to save you the trouble. Download the pom and put it in the same directory as your newly built jar. Or, if you’d rather not go to the trouble of building your own db-files jar, download mine.

mvn install:install-file -Dfile=mysql-connector-mxj-gpl-5-0-12-db-files.jar -DpomFile=mysql-connector-mxj-gpl-5-0-12-db-files.pom

You still need the mxj jar, though, so I built a pom for that jar as well.

mvn install:install-file -Dfile=mysql-connector-mxj-gpl-5-0-12.jar -DpomFile=mysql-connector-mxj-gpl-5-0-12.pom

MXJ will re-use a deployment of mysql that it has made previously, so make sure to remove any temporary directories left over by mysql. Otherwise, you’ll keep on using the old (broken) mysqld binaries. This will clear both the default mxj directory and the one used by ConnectorMXJUrlTestExample, in case you ran that previously. Make sure to add also include any directories you’ve configured yourself (e.g. by setting server.basedir in the JDBC url).

rm -rf /tmp/mysql-c.mxj
rm -rf /tmp/test-mxj

MXJ should now be ready to use. To depend on it from a Maven project, this is the dependency you need (you probably don’t want to use MXJ for production deployments, so it’s set to test scope). If you’re using Maven 3, you will also need to put the artifacts in your repo server since Maven 3 complains if it can only find artifacts in the local ~/.m2 repo.

<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-mxj</artifactId>
  <version>5.0.12</version>
  <scope>test</scope>
</dependency>

There are dozens of web technologies for Java (Struts, Stripes, Tapestry, Wicket, GWT, Spring MVC, Vaadin, Play, plain old servlets and JSP, Dropwizard, etc.) and they all have their advantages and disadvantages. This article isn’t about comparing frameworks. Instead, I’ll describe how to serve HTTP requests from Java without using a monolithic framework in a way that’s a lot more pleasant than using just HttpServletRequests: Jetty for handling low-level HTTP things, Jersey for request routing, Jackson for serialization and Guice to tie it all together.

Update: If you actually want to write something quickly using stuff shown in this article, Dropwizard has since come out, and looks like a solid choice. If you want to learn more about how to build such a stack, check out the second article in this series.

If you want to write your web UI on the server side (whether it’s translated to JavaScript ala GWT or simply HTML markup like you might put in a JSP), this probably isn’t an approach that will be very attractive. You won’t have a web framework already there to provide pre-canned view helpers or login forms or “is this a phone number” validation or any of that.

If you are transitioning towards making the server be more of a data store and putting display logic entirely in the client (regardless of whether the client is a browser or a native mobile app), the no-big-framework approach can make a lot of sense. You don’t need portlets or JavaScript components when you’re simply shoving JSON or XML or what-have-you over HTTP.

I’ll be including code samples as new concepts are introduced, but if you want to browse the finished example project, it’s on the Team Lazer Beez GitHub site.

Jetty

Jetty is a HTTP server and servlet container that’s been designed expressly for easy embedding. I think it’s easier to do the edit-restart-test cycle with a simple main method that starts a Jetty server (no IDE I’ve used has ever had integration with a servlet container that works as fast or as reliably as running a main method). If you prefer to run and debug inside a separate container, or if you need container-managed security or JTA or XA or any of that stuff, feel free bundle your code as a war instead of using Jetty.

Here’s how you start a Jetty server listening on localhost:8080.

Server server = new Server(8080);
// handlers go here
server.start();

Pretty easy! But, this server doesn’t do anything since we haven’t told it what to do for incoming requests. So, before we call start(), we need to give the server a Handler. Handlers are a Jetty concept that can do pretty much anything in response to a HTTP request. You might have a Handler that only gathers performance metrics or only does logging. In this case, we want a Handler that can invoke servlets.

ServletContextHandler handler = new ServletContextHandler();
handler.setContextPath("/");
// set up handler
server.setHandler(handler);

One odd thing about Jetty’s ServletContextHandler is that it likes to have one servlet always, even though in our case we won’t actually end up needing any to run our business logic. So, we’ll give the handler a servlet:

// jetty always needs one servlet
handler.addServlet(new ServletHolder(new InvalidRequestServlet()), "/*");

InvalidRequestServlet is a simple HttpServlet that always 404s.

@Override
protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
    resp.setStatus(HttpServletResponse.SC_NOT_FOUND);
    resp.setContentType("text/plain");
    resp.setContentType("UTF-8");
    resp.getWriter().append("404");
}

If you create a main method with the code to start up Jetty and run it, you should now be able to go to http://localhost:8080 in your browser and see the result of your InvalidRequestServlet. Before we can start adding some actual logic, though, I’ll need to explain Guice and its servlet layer.

Guice

Guice is a dependency injection framework. Though it accomplishes more or less the same job that Spring does, it has a slightly different philosophy. Whereas Spring tends to think in terms of bean ids when gluing code together, Guice tends to think in terms of types. They’re both good tools with different strengths, but I am only going to show how to use Guice (or this article will never end!). I’ll give a whirlwind tutorial in Guice and Guice Servlet and then we’ll get back to building our stack.

Making some PB&J Sandwiches

One of the problems (but not the only one) that DI/IoC frameworks like Guice and Spring are trying to solve is the problem of passing an instance through many layers of constructors just because some deep-down class is structured to take an instance of some interface. No doubt you’ve seen this anti-pattern: Class1 instantiates Class2 which instantiates Class3, but Class3 takes a Foo instance in its constructor, so somewhere higher up (perhaps in Class1, or even higher up than that) you create the correct Foo instance and then it gets passed around for a while until it’s finally used in Class3. This sucks, but it’s a worthy goal to have Class3 take a Foo instance in its constructor rather than directly instantiating some concrete implementation: this benefits testability, separation of concerns, etc. Guice can help make this easier.

As an example, let’s suppose that you have a SandwichMaker class that takes a PeanutButter implementation in its constructor. For testing your SandwichMaker, you may wish to use a mock PeanutButter implementation, but in an actual deployment you might wish to use an OrganicCrunchyValenciaPeanutButter (OCVPB for short).

class SandwichMaker {
// ...
    SandwichMaker(PeanutButter peanutButter) {
        this.peanutButter = peanutButter;
    }
// ...
}
interface PeanutButter {
    void applyToSandwich(Sandwich sandwich, int grams);
}

Now the question is where in your actual app do you instantiate your OCVPB? It’s not ideal to do it in the class that creates a SandwichMaker since that class will now be using actual peanut butter when it’s run during tests as it’s hardcoded the concrete implementation. It’s also not ideal to create the OCVPB in the top-level main method and pass the instance around through however many levels of constructors are needed to get to the SandwichMaker. To explain how we can use Guice to solve this problem, there are a few concepts to explain.

Guice concepts

Rather than explicitly creating instances with the new keyword, Guice lets you define how classes depend on each other and takes care of wiring things together for you. In our case, we want our SandwichMaker to have a PeanutButter implementation provided to it. We inform Guice of this by annotating the ctor with @Inject. (There are versions of Inject and some other classes from both com.google.inject and from the standardized JSR 330 javax.inject packages. They work almost exactly the same; check the Guice documentation for details. Just pick one and stick with it.)

class SandwichMaker {
// ...
    @Inject
    SandwichMaker(PeanutButter peanutButter) {
        this.peanutButter = peanutButter;
    }
// ...
}

Now that we’ve said that SandwichMaker needs a PeanutButter, we need to say which PeanutButter to use. We do this with a binding in a module. Modules are intended to represent functional boundaries in your application. The decision of when to put things in separate modules is like learning when to put things in separate packages: you’ll simply need to get a feel for it by trying it out. For now, let’s create a module that sets up everything you need to make sandwiches.

class SandwichModule extends AbstractModule {
    @Override
    protected void configure() {
        bind(PeanutButter.class).to(OrganicCrunchyValenciaPeanutButter.class);
    }
}

This informs Guice to create a new instance of OCVPB whenever it sees a request to inject a PeanutButter instance. PeanutButter seems like the sort of thing that should be a singleton since it represents a real-life resource, though, so let’s go ahead and fix that:

bind(PeanutButter.class).to(OrganicCrunchyValenciaPeanutButter.class).in(Scopes.SINGLETON);

We could also have annotated our OCVPB implementation class with @Singleton to achieve the same effect. Now, no matter how many SandwichMakers we get, only one PeanutButter will be used.

We create an Injector with all of the modules necessary (in this case, just the one module) and use it to get an instance of SandwichMaker. It will inspect the bindings and injection targets and create a OCVPB and pass it to the SandwichMaker ctor. We don’t actually need to get a standalone SandwichMaker instance, but if we did, this is how we would do it.

Injector injector = Guice.createInjector(new SandwichModule());
 
SandwichMaker maker = injector.createInstance(SandwichMaker.class);
// use the maker

This is just the very most basic usage of Guice. Check out their documentation for more details.

Guice Servlet

Now that we know how to bind instances (whether as singletons or new-one-every-time) and inject them, we can move on to Guice Servlet. This extension to Guice allows us to get rid of web.xml entirely (if embedding Jetty) or make it much simpler (if using a war).

Suppose you have a FooServlet servlet. In the old days of web.xml, there would be servlet tags and servlet-mapping tags to wire it up. Here’s how it is with Guice Servlet:

class FooServletModule extends ServletModule {
    @Override
    protected void configureServlets() {
        bind(FooServlet.class);
        serve("/foo").with(FooServlet.class);
 
        // other servlets
    }
}

Since Guice is instantiating your FooServlet class intead of relying on the servlet container to invoke the 0-args ctor, this also means that you can use @Inject on the ctor and get the objects you need that way instead of pulling them out of init params or servlet context.

To feed incoming requests into the servlets you’ve laid out with Guice Servlet, you need to set up GuiceFilter as a filter for all requests. You can do this in web.xml if you’re using a war (it’s the only thing you’ll actually need in web.xml) or just configure Jetty directly.

Injector injector = Guice.createInjector(new SandwichModule(), new AbstractModule() {
    @Override
    protected void configure() {
        binder().requireExplicitBindings();
        bind(GuiceFilter.class);
    }
});
 
FilterHolder guiceFilter = new FilterHolder(injector.getInstance(GuiceFilter.class));
handler.addFilter(guiceFilter, "/*", EnumSet.allOf(DispatcherType.class));

Now, you can stop here and bind your servlets in a ServletModule and get the benefits of being able to initialize your servlets with Guice, but it gets even easier with Jersey.

Jersey and Jackson

Jersey is the reference implementation of JAX-RS. It lets you do things like POST the url “http://localhost:8080/foo?bar=baz&quux=1234″ and handle the request with this class:

@Path("/foo")
@Produces(MediaType.APPLICATION_JSON)
class FooResource {
    @POST
    public String handleFooPost(@QueryParam("bar") String bar, @QueryParam("quux") int quux) {
       return "{\"yay\":\"hooray\"}"; 
    }
}

The class, method and parameter names are not magic; only the annotations are what ties this code to handling that request. Jersey will set the status code, content length, etc. appropriately. It can also do void methods (returns status 204 for you), streaming responses, and entirely custom responses (pick the status code, the entity, etc), so check the documentation for the details.

If you use Jersey to handle actually calling your business logic instead of writing plain old servlets directly, you only need to have one servlet binding in your Guice Servlet module:

public class SandwichServletModule extends ServletModule {
    @Override
    protected void configureServlets() {
        // bind resource classes here
 
        // hook Jersey into Guice Servlet
        bind(GuiceContainer.class);
 
        // hook Jackson into Jersey as the POJO <-> JSON mapper
        bind(JacksonJsonProvider.class).in(Scopes.SINGLETON);
 
        serve("/*").with(GuiceContainer.class);
    }
}

GuiceContainer is a class that ships with Jackson. When you use GuiceContainer, all you need to do is bind the resource classes (like FooResource above) with Guice. The JacksonJsonProvider binding to make it easier to return objects as JSON; you’ll see what it does a bit later. To go back to our sandwich example, let’s suppose we have two resources: one to make sandwiches and one to say how many sandwiches have been made.

Let’s start with the stats one (at /sandwich/stats) since it is simpler (doesn’t need to modify state). Supposing I have a SandwichStats class that can provide StatSnapshot objects that represent the total amount of jam, peanut butter and sandwiches, the resource is very simple:

@Singleton
@Produces(MediaType.APPLICATION_JSON)
@Path("/sandwich/stats")
public class SandwichStatsResource {
 
    private final SandwichStats sandwichStats;
 
    @Inject
    SandwichStatsResource(SandwichStats sandwichStats) {
        this.sandwichStats = sandwichStats;
    }
 
    @GET
    public SandwichStats.StatsSnapshot getStats() {
        return sandwichStats.getStats();
    }
}

You’ll also need to bind the resource class so that GuiceContainer can find it. When you have a lot of resources, you might want to put their bindings in a module just for that purpose, but for now just add a binding in SandwichServletModule:

bind(SandwichStats.class);

The resource requests a SandwichStats object in its ctor so that it can ask it for the latest info every time a request is made. The SandwichStats object should also be a singleton since we want it to live as long as the app is up. (Guice is easy to use for non-singletons too — it just happens that in this contrived example I seem to be ending up with lots of singletons.)

Note that the @GET method returns an object, not a string. This is where the ImmutableMap.of(JSONConfiguration.FEATURE_POJO_MAPPING, "true") comes in. It tells Jersey to attempt to map the POJO returned from the method to JSON. To do this, we use the Jackson JSON library.

Jackson is a fast JSON serialization/deserialization library, and one of its features is easy annotation-based configuration for POJO mapping. It’s probably easiest to just show what it looks like in practice:

public class StatsSnapshot {
    // ...
    @JsonProperty
    public int getSandwichesMade() {
        return sandwichesMade;
    }
 
    @JsonProperty
    public int getGramsOfJam() {
        return gramsOfJam;
    }
 
    @JsonProperty
    public int getGramsOfPeanutButter() {
        return gramsOfPeanutButter;
    }
}

When serialized by Jackson, an object of that class will end up as a JSON object with three keys (“gramsOfJam”, “gramsOfPeanutButter” and “sandwichesMade”). Since Jersey has been configured to automatically use Jackson to serialize objects, you can go to /sandwich/stats in your browser and get something like this: {"gramsOfJam":150,"gramsOfPeanutButter":200,"sandwichesMade":1}

Now let’s add a resource that lets you make sandwiches. Normally I wouldn’t have something that modifies state be a GET but I want this to be easy to test in a browser, so let’s say that a GET to http://localhost:8080/sandwich/create will make a sandwich (with optional jam and peanutButter query parameters to specify how many grams of jam and peanut butter to use) and that the sandwich created should be returned as JSON. This is what such a resource might look like:

@Singleton
@Produces(MediaType.APPLICATION_JSON)
@ThreadSafe
@Path("/sandwich/create")
public class SandwichMakerResource {
 
    private final SandwichMaker sandwichMaker;
 
    private final SandwichStats sandwichStats;
 
    @Inject
    SandwichMakerResource(SandwichMaker sandwichMaker, SandwichStats sandwichStats) {
        this.sandwichMaker = sandwichMaker;
        this.sandwichStats = sandwichStats;
    }
 
    @GET
    public Sandwich makeSandwich(@QueryParam("jam") @DefaultValue("100") int gramsOfJam,
                                 @QueryParam("peanutButter") @DefaultValue("200") int gramsOfPeanutButter) {
        Sandwich sandwich = sandwichMaker.makeSandwich(gramsOfPeanutButter, gramsOfJam);
        sandwichStats.recordSandwich(sandwich);
 
        return sandwich;
    }
}

The resource (yet another singleton) gets SandwichMaker and SandwichStats instances injected, and whenever it makes a sandwich it updates the SandwichStats object. Try accessing it via your browser a few times and check the stats page to see that the counts do update correctly.

I’ve only scratched the surface of what these libraries can do with this simple example. Let me know if you think there’s some cool feature I missed (as long as it won’t complicate things too much to work it in).

Features

• Easy-to-use wrappers around the APIs. The classes that tools generate for the SOAP APIs are clumsy and unintuitive (and not thread safe), so I’ve written better versions.
• Limits concurrent API calls for Partner, Metadata and Apex connectors. This helps you avoid ‘concurrent request limit exceeded’ errors. (The REST API is harder to hit the limit with. I will add it to the request limiting system in the future.)
• Transparent handling of INVALID_SESSION_ID for the Partner API. If someone else has closed the session ID you were using, the library will automatically re-login as needed.
• Designed to be used with many different organizations simultaneously. If your app needs to talk to the orgs of many different customers all at the same time, it’s easy to do so. Of course, it’s also easy to work with just one org if that’s what you need.
• Connections are reconfigurable at any time. You can update the login and password (for SOAP connections) or OAuth token (for REST connections) and the next API call you make will seamlessly use the updated information, even if it’s in another thread.
• Designed with thread-safety in mind. Where practical, classes are thread-safe or immutable.
• HTTP communication is gzip-compressed.
• Well-tested, robust code.
• Business-friendly Apache License (no GPL issues)

Getting started

First you’ll need to check out and build the code.

% git clone git://github.com/teamlazerbeez/sf-api-connector.git
% cd sf-api-connector
% mvn clean install -DskipTests

Maven will probably need to download a bunch of plugins if you’re not a Maven user yet. Once it’s done, you’ll have installed the jars into your local maven repository. The reason tests are skipped is that some of the tests actually use Salesforce’s real API and are therefore restricted to only come from certain blocks of IP addresses, so those tests will fail unless you happen to be using my ISP. Also, the tests take quite some time to run.

The SOAP-based APIs (Partner, Metadata and Apex) are in the sf-soap-api-connector module and the REST API is in the sf-rest-api-connector module. The dependencies to use for your pom.xml are shown below. You only need to include the dependency for the API that you’ll be using (that is, you don’t need both unless you’re using both). The dependencies are both SNAPSHOT versions because that’s what’s declared in the project’s pom.xml right now.

<dependency>
  <groupId>com.teamlazerbeez</groupId>
  <artifactId>sf-soap-api-connector</artifactId>
  <version>trunk-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>com.teamlazerbeez</groupId>
  <artifactId>sf-rest-api-connector</artifactId>
  <version>trunk-SNAPSHOT</version>
</dependency>

Using the REST API

Most people can probably do what they need with the REST API, so I’ll start with that since it’s simpler. RestConnectionPool is the starting point for using the REST API. The class has a generic parameter to allow you to use any class you want to identify organizations. You might use the Salesforce organization id (the id that starts with ’00D’) or perhaps the primary key for a table in your DB that has a row for each organization. Make sure you use an immutable class with a useful hashCode()/equals() implementation since these objects will be used as keys in a Map. In this example I’ll use Integer.

// in your app setup, create a pool that's shared for the whole app
RestConnectionPool<Integer> pool = new RestConnectionPoolImpl<Integer>();

Before you can use the pool to get a connection for a specific org, you need to inform the pool about that org.

pool.configureOrg(orgId, host, oauthToken);

The host is the HTTP endpoint to use. Different orgs may be on different Salesforce clusters, so this is a per-org setting. You can extract the host from the partner server URL (see ConnectionBundle.getBindingConfig() in the SOAP API module or the tip later on in this article) if you don’t already have it. The OAuth token is something you’ll get by following the steps outlined in Salesforce’s OAuth docs. You can also use a session Id from the SOAP API as the OAuth token.

You can configure a pool with as many orgs as you want. The pool is shared between all of them for efficiency. You can also reconfigure the data for an org in a pool at any time.

Now that the pool is configured, let’s actually use a connection.

RestConnection connection = pool.getRestConnection(orgId);
 
SObject contact = connection.retrieve("Contact", new Id("0035000000kmAZJ"),
    Arrays.asList("FirstName", "LastName", "Email"));
 
System.out.println("Got a " + contact.getType() + 
    " object with id " + contact.getId());
 
for (Map.Entry<String,String> entry: contact.getAllFields()) {
    System.out.println("Field <" + entry.getKey() + "> has value <" + 
        entry.getValue() + ">");
}
 
SObject newLead = RestSObjectImpl.getNew("Lead");
newLead.setField("LastName", "Smith");
newLead.setField("Company", "FooCorp");
 
SaveResult result = connection.create(newLead);
 
if (result.isSuccess()) {
    System.out.println("Created a lead with id " + result.getId());
} else {
    System.out.println("Creation failed with errors " + result.getErrors());
}

Check the RestConnection interface to see what else you can do with it.

Using the SOAP APIs

The SOAP APIs are a little more complicated because there are three different WSDLs that share some common configuration. First you’ll need to pick a “partner key” or “client id”. This is a fairly arbitrary identifier that will be used to identify what application made an individual API call. Choose something at least mildly human-readable.

As with RestConnectionPool, you can choose any class you like to be your org identifier. Here I’ll use Integer again.

ConnectionPool<Integer> pool = new ConnectionPoolImpl<Integer>(yourPartnerKey);
 
pool.configureOrg(orgId, username, password, maxConcurrentApiCalls);

Username and password are the Salesforce username and password of the person you want to log in as. The last parameter sets the max number of concurrent calls you want to happen per org. Fortunately in a recent update (API version 19 or 20, I think) Salesforce greatly relaxed the limits on concurrent connection usage to only apply to calls that take longer than 20 seconds, so you can set this limit fairly high unless you’re going to be doing long-running calls. See Salesforce’s API Usage Metering docs for more details.

You can now get a ConnectionBundle for an org. A ConnectionBundle represents the per-org configuration needed for all SOAP connections.

ConnectionBundle bundle = pool.getConnectionBundle(orgId);
 
PartnerConnection partnerConn = bundle.getPartnerConnection();
ApexConnection apexConn = bundle.getApexConnection();
MetadataConnection metadataConn = bundle.getMetadataConnection();
 
// partner connection
System.out.println("User id is " + partnerConn.getUserInfo().getUserId());
System.out.println("First contact's email is " + 
    partnerConn.query("SELECT Email FROM Contact LIMIT 1")
        .getSObjects().get(0).getField("Email"));
 
// metadata connection
List<FileProperties> fileProps = metadataConn
    .listMetadata(Arrays.asList(new ListMetadataQuery("CustomField")));
for (FileProperties fp: fileProps) {
    System.out.println("Custom field " + fp.getFullName() + " has id " + fp.getId());
}
 
// apex connection
ExecuteAnonResult result = 
    apexConn.executeAnonyous("System.debug('test debug statement');");
 
System.out.println("Compile succeeded: " + result.isCompiled());
System.out.println("Debug log output: " + result.getDebugLog());

Note that the Metadata API example shows how to get custom field Ids, something that is impossible via the Partner API.

The ConnectionBundle interface also lets you get the current configuration data for an org. You can use this to get the hostname that you need for RestConnectionPool. Using OAuth to get the token is recommended if that’s an option, but if not you can also get the current session Id from the configuration data and use that as the OAuth token.

BindingConfig bindingConfig = soapPool.getConnectionBundle(orgId).getBindingConfig();
String host = new URL(bindingConfig.getPartnerServerUrl()).getHost();
String token = bindingConfig.getSessionId();
restPool.configureOrg(orgId, host, token);

The library doesn’t support every single possible call in all of the APIs, but it does support most of them. I only implemented the calls I had occasion to use, so the Partner, Metadata and REST APIs have fairly complete support while the Apex API only supports a fraction of the available calls. If there’s a call that you use that the library doesn’t support, let me know and I’ll see what I can do. Similarly, if the library’s API doesn’t seem intuitive or doesn’t fit well with what you’re doing, I’d like to hear about that as well.

In /var/lib/puppet/lib/puppet/parser/functions lives the file webcontent.rb which has the following contents:

require 'open-uri'
module Puppet::Parser::Functions
    newfunction(:webcontent, :type => :rvalue) do |args|
        server = args[0]
        configpath = args[1]
        config = ""
        begin⋅
            open( "http://#{server}/#{configpath}/" ) do |f|
             f.each_line do |line|
                 config = "#{config}#{line}"
             end
            end⋅
        rescue OpenURI::HTTPError => e
            raise Puppet::ParseError, "404 for http://#{server}/#{configpath}/"
 
        rescue Exception => e
            raise Puppet::ParseError, "content string is http://#{server}/#{configpath}/ #{e}"
        end
        return config
    end
end

Using the Ruby module open-uri content is grabbed by the puppetmaster and placed into the catalog. Using the following Django model, view and template a config file is easily generated and passed along to Puppet

class SupervisorProgram(models.Model):
    name = models.CharField(max_length=128)
    command = models.CharField(max_length=512)
    autostart = models.BooleanField(default=True)
    autorestart = models.CharField(max_length=32,choices=(('false','false'),('true','true'),('unexpected','unexpected')))
    startsecs = models.IntegerField(default=10)
    startretries = models.IntegerField(default=3)
    exitcodes = models.CharField(max_length=64,default="0,2")
    stopsignal = models.CharField(max_length=5,choices=(('TERM','TERM'),('HUP','HUP'),('INT','INT'),('QUIT','QUIT'),('KILL','KILL'),('USR1','USR1'),('USR2','USR2')),default="TERM")
    stopwaitsecs = models.IntegerField(default=10)
    user = models.CharField(max_length=16 ,default="nagios")
    redirect_stderr = models.BooleanField(default=False)
    stdout_logfile = models.CharField(max_length=256,default="AUTO")
    stdout_logfile_maxbytes = models.CharField( max_length = 8,default="50MB")
    stdout_logfile_backups = models.IntegerField(default=10)
    stderr_logfile = models.CharField(max_length=256,default="AUTO")
    stderr_logfile_maxbytes = models.CharField( max_length = 8,default="50MB")
    stderr_logfile_backups = models.IntegerField(default=10)
    environment = models.CharField( max_length=512,blank=True,null=True)
    directory = models.CharField(max_length=128,default="/")
    umask = models.IntegerField(blank=True,null=True)
    priority = models.IntegerField(default=999)
 
    def __unicode__(self):
        return self.name
    class Meta:
        ordering = ('name',)
 
class SupervisorProgramAdmin(admin.ModelAdmin):
    list_display = ('name','command','autorestart','stopsignal','exitcodes','user','stdout_logfile','stderr_logfile')

The following is the view used:

def getSupervisorConfig(request,service):
    print "getSupervisorConfig has been called for %s" % service
    service = get_object_or_404(SupervisorProgram,name=service)
    directives = {}
    directives["command"] = str(service.command)
    directives["process_name"] = str(service.name)
    directives["priority"] = int(service.priority)
    directives["autostart" ] = service.autostart
    directives["autorestart"] = service.autorestart
    directives["startsecs"] = int(service.startsecs)
    directives["startretries"] = int(service.startretries)
    directives["exitcodes"] = str(service.exitcodes)
    directives["stopsignal"] = str(service.stopsignal)
    directives["stopwaitsecs"] = int(service.stopwaitsecs)
    directives["user"] = str(service.user)
    directives["redirect_stderr"] = service.redirect_stderr
    directives["stdout_logfile"] = str(service.stdout_logfile)
    directives["stdout_logfile_maxbytes"] = str(service.stdout_logfile_maxbytes)
    directives["stdout_logfile_backups"] = int(service.stdout_logfile_backups)
    directives["stderr_logfile"] = str(service.stderr_logfile)
    directives["stderr_logfile_maxbytes"] = str(service.stderr_logfile_maxbytes)
    directives["stderr_logfile_backups"] = int(service.stderr_logfile_backups)
    directives["directory"] = str(service.directory)
    if service.environment:
        directives["environment"] = str(service.environment)
 
    return render_to_response("sock/supervisor.conf",directives)

With the 20 configuration options per supervisord controlled process there are far too many options that should be sanely passed to puppetmaster from the external node classifier.

Here is the Django template:

#generated config
[program:{{ process_name }}]
command={{ command }}
process_name=%(program_name)s
priority={{ priority }}
autostart={{ autostart }}
autorestart={{ autorestart }}
startsecs={{ startsecs }}
startretries={{ startretries }}
exitcodes={{ exitcodes }}
stopsignal={{ stopsignal }}
stopwaitsecs={{ stopwaitsecs }}
user={{ user }}
redirect_stderr={{ redirect_stderr }}
stdout_logfile={{ stdout_logfile }}
stdout_logfile_maxbytes={{ stdout_logfile_maxbytes }}
stdout_logfile_backups={{ stdout_logfile_backups }}
stderr_logfile={{ stderr_logfile }}
stderr_logfile_maxbytes={{ stderr_logfile_maxbytes }}
stderr_logfile_backups={{ stderr_logfile_backups }}
{% if environment %}
environment={{ environment }}
{% endif %}

Finally all of this can be referenced with a custom define as follows:

define supervisorconfig(
        $program,
        $server = "${rserver}"
) {
    file {
        "${name}.conf":
            owner => root,
            group => root,
            mode => 0644,
            path => "/etc/supervisord.d/${name}.conf",
            content => webcontent( $server, "dpuppet/sock3/getsupervisorconfig/$program")
    }
}

Here is a simple example from our Fixture package:

<?php
// Include the Genius config file
require_once dirname(dirname(__FILE__)) . '/Core/gosConfig.inc.php';
 
/**
 * A function to get single values from a database table
 */
function getThingFromDB($id) {
    $db = gosDB_Helper::getDBByName('main');
 
    return $db->getOne("SELECT s1 FROM fixture_test WHERE i1 = " . $id);
}

In a nearby test file:

<?php
// Include the Genius fixture configuration. This geneartes a database
// and applies the schema to it.  See fixtureTestConfig.inc.php
// for more details.
require_once(GOS_ROOT . 'Fixture/fixtureTestConfig.inc.php');
 
function testGetThingFromDB() {
    // Create a fixture
    $fixture = gosTest_Fixture_Controller::getByDBName('main');
 
    // Load the fixture into the database
    $fixture->parseFixtureFile(GOS_ROOT . 'Fixture/example_fixture.yaml');
 
    // Directly access the fixture, which is identical to what the database contains
    $idToGet = $fixture->get('fixtureName.fixture_test.i1');
 
    // Pull the value we want directly from the fixture
    $fixtureThing = $fixture->get('fixtureName.fixture_test.s1');
    // Pull the value we want from the DB via the function we're testing
    $thing = getThingFromDB($idToGet);
 
    echo "The fixture put $fixtureThing into the DB.\n";
    echo "Our function selected $thing from the DB.\n";
}
 
// Run the test
testGetThingFromDB();

The first magical line here is that require_once—fixtureTestConfig.inc.php uses the database connection information defined in Fixture/fixtureConfig.yaml to create a database is used for the duration of this PHP process only. Subsequent test runs (or invocations of this example script) will generate an entirely new database. See gosDB_AutoDBGenerator for details on these ephemeral databases. The takeaway is that you must have a user listed in that fixture config YAML file that can create databases.

In the test function itself, we create a fixture on the appropriate database, in this case our main database, and load the data from our fixture file, a simple YAML file defining what data we want in the database:

# The name of this fixture
fixtureName:
    # A table we will insert data into
    fixture_test:
        i1: 11
        s1: str1

At this point, we’re ready to start testing. First we get the ID that we need to pass to getThingFromDB, which we simply pull from the fixture. Next, we get the value that we are expecting from the same table in the fixture. Now that we have the ID we want to give to the function we’re testing, and the value we expect to get back, we can execute that function and compare the results. Go ahead and try this all for yourself; the above example works all on its own. The easiest way is to download the example.php and the necessary YAML file.

The gosFixture class automatically cleans up the database tables that it touched (see Core/lib/gosTest/Framework/TestCase.acls.php), so you need to re-apply the fixture for every test. The easiest way to do this is to put the fixture initialization in the setUpExtension() of a test class, giving you completely fresh fixture data for each and every test.

So go forth and test your code with better isolation and known clean data.

The first step in setting up an external node classifier is developing what will be generating the YAML for the puppetmaster to read. In this situation Django chosen as a web framework as the built in admin interface saved a bit of development time for management. Additional thought behind using an ORM framework was cutting down on development time on other projects that might need access to the truth database and could simply pull YAML from it. Within the Django application there are classes describing hosts, environments, server class, puppet classes, hard drive and filesystem layout. Here is the class describing a host:

class Host(models.Model):
    hostname = models.CharField(null=True,blank=False,max_length=128)
    basename = models.CharField(null=True,blank=True,max_length=128)
    maintenance = models.BooleanField(default=False)
    datacenter = models.CharField(max_length=5,choices=(('sjc','san jose'),
        ('smc','server room')),blank=True,null=True)
    environment = models.CharField(max_length=5,choices=(('app','production'),
        ('stg1','staging 1'),('stg2','staging 2'),('dev','development')),blank=True,null=True)
    env = models.ForeignKey(Environment)
    ostype = models.CharField(max_length=32,choices=(('linux','linux'),
        ('windows','windows'),('mac','mac')),blank=True,null=True)
    info = models.TextField(blank=True,null=True)
    bit = models.CharField(blank=True,null=True,max_length=5,choices=(('32','32 bit'),('64','64 bit')))
    puppetrun = models.IntegerField(default=1800)
    serverclass = models.ForeignKey(SvrClass)
 
    classes = models.ManyToManyField(PuppetClass,blank=True,null=True)
    drives = models.ManyToManyField(Drive,blank=True,null=True)
    interfaces = models.ManyToManyField(NetInterface,blank=True,null=True)
    script = models.ManyToManyField(Script,blank=True,null=True)
    osver = models.ManyToManyField(Osversion,blank=True,null=True)
    services = models.ManyToManyField(Service,blank=True,null=True)
    supervisors = models.ManyToManyField(SupervisorProgram,blank=True,null=True)
 
    def getBranch(self):
        return self.env.branch.name
 
    def getEnvironment(self):
        return self.env.name
 
    def __str__(self):
        return self.__repr__()
 
    def __repr__(self):
        return "hostname: %s environment: %s" % (self.hostname,self.env.name)
 
class HostAdmin(admin.ModelAdmin):
    list_display    =   ('hostname','environment','bit','ostype','datacenter','maintenance')
    list_filter     =   ('environment','datacenter')
    ordering        =   ('hostname','datacenter','environment')
    search_fields   =   ('hostname',)

and now the code for the Puppet class in Python, the Puppet class class:

class PuppetClass(models.Model):
    name = models.CharField(max_length=128)
    def __unicode__(self):
        return self.name
    class Meta:
        ordering = ('name',)
 
class PuppetClassAdmin(admin.ModelAdmin):
    list_display = ('name',)

With these two classes a host and what Puppet classes it has assigned to it can readily be described and the following code will output YAML describing the host as the puppetmaster understands:

import yaml
 
def hostinfo(request,hostname):
    host = get_object_or_404(Host,hostname=hostname)
    classlist = []
    [classlist.append(str(x.name)) for x in host.classes.all()]
    #if a host's classlist is empty at this point pull from the default list
    if not classlist:
        #default list is simply a list of puppet class objects
        defaultlist = DefaultList.objects.get(name="standard")
        [classlist.append(str(x.name)) for x in defaultlist.classes.all()]
    #add in some extra parameters
    params = {'datacenter':str(host.datacenter),'machine':str(host.basename),'serverclass':str(host.serverclass.name),'env':str(host.env.name),'branch':'%s' % str(host.env.branch.name),'envmaint':str(host.env.maintenance),'hostmaint':str(host.maintenance)}
    params['rserver'] = str(host.env.rserver)
    yamlsrc = yaml.dump({'classes':classlist,'parameters':params})
    return  render_to_response("sock/hostinfo.yaml",{'hostname':hostname,'yaml':yamlsrc})

One issue that was encountered with exporting data from django to yaml was the usage of utf for strings, hence the continual usage of str(). The result of the function is dumped out through the following incredibly complex template

---
{{ yaml }}

At the end of all of this we finally get data that comes out as something similar to the following:

---
classes: [bots, puppet-classes, puppet-master, repos, yamlsvn]
parameters: {branch: '33', datacenter: sjc, env: app, envmaint: '0', hostmaint: '0',
  machine: repo, rserver: sjc-repo.genops.net, serverclass: none}

Next we need a command that the puppetmaster can run to get the YAML, here is the current script:

#!/bin/sh
curl http://example.genius.com/dpuppet/sock3/hostinfo/$1/ 2>/dev/null | \
sed "s/'/'/g"
exit 0;

Finally the puppetmaster needs to be configured to pull from the external node classifier:

[main]
    # Where Puppet stores dynamic and growing data.
    # The default value is '/var/puppet'.
    vardir = /var/lib/puppet
 
    # The Puppet log directory.
    # The default value is '$vardir/log'.
    logdir = /var/log/puppet
 
    # Where Puppet PID files are kept.
    # The default value is '$vardir/run'.
    rundir = /var/run/puppet
 
    # Where SSL certificates are kept.
    # The default value is '$confdir/ssl'.
    ssldir = $vardir/ssl
    # use external nodes ftw
    external_nodes = /usr/local/bin/puppetinfo.sh
    node_terminus = exec
 
[puppetd]
    # The file in which puppetd stores a list of the classes
    # associated with the retrieved configuratiion.  Can be loaded in
    # the separate ``puppet`` executable using the ``--loadclasses``
    # option.
    # The default value is '$confdir/classes.txt'.
    classfile = $vardir/classes.txt
 
    # Where puppetd caches the local configuration.  An
    # extension indicating the cache format is added automatically.
    # The default value is '$confdir/localconfig'.
    localconfig = $vardir/localconfig
    server =  puppetmaster.genius.com
    runinterval = 300

The masters act as their own clients, syncing against themselves with a puppet class that controls checkouts of an svn repository holding all puppet classes.  All of the servers have been configured with custom defines to handle subervision checkouts and configs for supervisor, additionally a custom parser has been written to allow pulling down webpages as part a content description. All servers run on an interval of 5 minutes with clients running on a 15 minute interval, with some special exceptions for dns servers.  Additionally the web app that powers the external node classier also handles generating config files and maintaining a truth database for other tasks, like imaging.

This is the first in a series of post regarding our setup, following posts will cover our external node classifier, truth database, customer parser, custom defines.

This tutorial shows how to access HornetQ JMS resources via JNDI without needing a separate JNDI server. It also provides a test utility to run an embedded HornetQ server (perfect for unit tests that need a JMS broker running!).

Why JNDI?

Since JMS is part of Java EE, you’ll often see tutorials that have JMS resources (e.g. connection factories or queues) being provided to your code is via JNDI. This isn’t the only choice, though: you could instead manually instantiate your preferred provider’s implementations of the resources you need.

If you choose the latter approach, you might use the following to get a Queue if you were using ActiveMQ (another JMS implementation):

Queue queue = new ActiveMQQueue("queueName");

This works fine until you switch to another provider, at which point you need to change all your queues (and connection factories and topics and…) to look like this:

Queue queue = new HornetQQueue("queueName");

This is why it’s recommended to instead pull those objects out of JNDI. If you’re getting the queue out of JNDI with the following code, you wouldn’t need to change anything if you switch providers other than changing how the JNDI context gets populated.

Context context = new InitialContext();
Queue queue;
try {
    queue = (Queue) context.lookup("jndiNameForQueue");
} finally {
    // release your context's resources when you're done with it
    context.close();
}

This isn’t meant to be a JNDI tutorial, but it should be clear why getting JMS resources (as well as things like JDBC DataSource objects and other “managed” objects) out of JNDI is a good thing: it makes it easier to program to interfaces, not implementations, and maintain vendor neutrality.

HornetQ’s JNDI support

HornetQ comes with all you need to be able to connect to a JNDI server and pull JMS resources out of that server. You can set up the HornetQ server to serve JNDI in addition to JMS by enabling the appropriate bean in hornetq-beans.xml.

This approach is straightforward, but it becomes problematic if you want your HornetQ servers to be in a HA (high availability) pair. It’s hard enough to configure and test HA without also needing JNDI service to fail over as well. Though there is some documentation on how to set up HA JNDI, it would be simpler (and surely faster as well) if there was no need to talk to a server at all to get JMS resources. This approach makes sense if your deployment setup is simple enough that you know which queues and JMS servers you will be using and can put that information in a few config files and bundle it with your code during deployment. This is the case for many uses of JMS. If, on the other hand, you’re already tied to using a Java EE server that provides JNDI, then you might as well use that.

ActiveMQ provides a simple way to configure JMS resources in local JNDI, but HornetQ doesn’t come with anything similar. This tutorial provides a way to do local JNDI with HornetQ.

Local JNDI Configuration

The starting point to accessing JNDI objects is creating a new InitialContext. The specific way that the resulting Context gets populated with data is controlled by the implementation of InitialContextFactory that you’re using. You can change the implementation by specifying the java.naming.factory.initial property in jndi.properties to be the fully qualified class name of an impementation of InitialContextFactory.

We can use this mechanism to specify an implementation of InitialContextFactory that reads HornetQ’s config files. More sophisticated implementations might produce a Context that accesses data on some remote server, but our goal here is something that reads data out of config files and populates a memory-only Context. We’ll need to read the core HornetQ config file to get connection factory information and the JMS HornetQ config file to get the JNDI names to assign to queues, topics, etc. We’ll also need something to actually create a Context implementation since we don’t want to have to write that ourselves. Implementing Context requires a non-trivial amount of work to do well. simple-jndi provides a basic in-memory InitialContextFactory, so we’ll use that.

Your jndi.properties would look something like this:

java.naming.factory.initial = com.genius.hornetq.XmlHornetQInitialContextFactory
hornetq.jndi.wrapped.initialcontextfactory.impl = org.osjava.sj.memory.MemoryContextFactory
hornetq.xml.jms.path = /path-to-hornetq-jms.xml
hornetq.xml.config.path = /path-to-hornetq-config.xml

The java.naming.factory.initial tells InitialContext which class to instantiate to return the underlying Context (look at the source that comes with the JDK if you’re curious how). In this case, we want InitialContext to use our custom implementation that reads HornetQ XML files.

The other properties are only relevant to our custom InitialContextFactory. See the HornetQ documentation for more about what to put in the XML config files.
hornetq.jndi.wrapped.initialcontextfactory.impl defines what InitialContextFactory we’ll use to actually create a Context object. In this case, it’s the simple-jndi memory-only InitialContextFactory.
hornetq.xml.jms.path is the path in the classpath to the HornetQ JMS config file. This is typically “hornetq-jms.xml”.
hornetq.xml.config.path is the path in the classpath to the HornetQ core config file. This is typically “hornetq-configuration.xml”.

Now that we’ve got jndi.properties ready, I’ve added the custom InitialContextFactory source below. The only tricky part is handling HornetQ’s LogDelegateFactory selection. The LogDelegateFactory system lets you change the logging system used by HornetQ and is configurable via the core config file. (I’d link to the documentation, but this option is undocumented. See FileConfigurationParser#parseMainConfig() in the HornetQ source.) Unfortunately, a bug in the way the LogDelegateFactory instance is set causes some classes to not properly pick up your custom implementation, so if you wish to use a custom LogDelegateFactory, note the commented out call to Logger.setDelegateFactory. Other than that, it’s pretty simple. We use HornetQ’s configuration parsing code to get the information we need out of the config files, then populate the Context we get from simple-jndi with the resulting JMS objects.

The only dependency outside of HornetQ is SLF4J for logging.

package com.genius.hornetq;
 
import org.hornetq.api.core.Pair;
import org.hornetq.api.core.TransportConfiguration;
import org.hornetq.api.jms.HornetQJMSClient;
import org.hornetq.core.config.Configuration;
import org.hornetq.core.deployers.impl.FileConfigurationParser;
import org.hornetq.jms.client.HornetQConnectionFactory;
import org.hornetq.jms.client.HornetQDestination;
import org.hornetq.jms.server.JMSServerConfigParser;
import org.hornetq.jms.server.config.ConnectionFactoryConfiguration;
import org.hornetq.jms.server.config.JMSConfiguration;
import org.hornetq.jms.server.config.JMSQueueConfiguration;
import org.hornetq.jms.server.config.TopicConfiguration;
import org.hornetq.jms.server.impl.JMSServerConfigParserImpl;
import org.hornetq.spi.core.logging.LogDelegateFactory;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
 
import javax.jms.Queue;
import javax.jms.Topic;
import javax.naming.Context;
import javax.naming.NamingException;
import javax.naming.spi.InitialContextFactory;
import java.io.InputStream;
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Hashtable;
import java.util.List;
import java.util.Map;
 
/**
 * Parses hornetq jms and core configuration files and populates the resulting Context appropriately.
 *
 * The following properties are needed:
 *
 * hornetq.xml.jms.path = path in the classpath to hornetq jms xml file
 *
 * hornetq.xml.config.path = path in classpath to hornetq core config file
 *
 * hornetq.jndi.wrapped.initialcontextfactory.impl = fully qualified classname of InitialContextFactory to use to
 * provide the Context instance that will be populated with configured JMS objects. An instance of this class will be
 * created and passed an empty environment.
 */
public class XmlHornetQInitialContextFactory implements InitialContextFactory {
 
    private static final String JMS_XML_PATH_KEY = "hornetq.xml.jms.path";
    private static final String CONFIG_XML_PATH_KEY = "hornetq.xml.config.path";
    private static final String INTERNAL_ICF_IMPL_KEY = "hornetq.jndi.wrapped.initialcontextfactory.impl";
    private static final Logger logger = LoggerFactory.getLogger(XmlHornetQInitialContextFactory.class);
 
    public XmlHornetQInitialContextFactory() {
        logger.trace("Instantiated");
    }
 
    @Override
    public Context getInitialContext(Hashtable<?, ?> environmentHashtable) throws NamingException {
        logger.trace("Creating InitialContext");
        Map<string, String> env = new HashMap<string, String>();
        for (Map.Entry<?, ?> entry : environmentHashtable.entrySet()) {
            if (entry.getKey() instanceof String && entry.getValue() instanceof String) {
                env.put((String) entry.getKey(), (String) entry.getValue());
            }
        }
 
        this.checkKeys(env, JMS_XML_PATH_KEY, INTERNAL_ICF_IMPL_KEY, CONFIG_XML_PATH_KEY);
 
        Context ctx = this.getContext(env);
 
        populateContext(env, ctx);
 
        return ctx;
    }
 
    private void populateContext(Map<string, String> env, Context ctx) throws NamingException {
        final InputStream configXmlStream = getStream(env.get(CONFIG_XML_PATH_KEY));
 
        /*
        * A bug in HQ 2.1.2 means that the log delegate factory will not be applied to any classes that use static
        * loggers and were loaded before the config-specified delegate factory is applied. A fix is scheduled for 2.2.0.
         * Until then, we'll hardcode the delegate factory to slf4j for the first few loggers.
        */
        //org.hornetq.core.logging.Logger.setDelegateFactory(new YourCustomLogDelegateFactory());
 
        final Configuration config;
        try {
            config = new FileConfigurationParser().parseMainConfig(configXmlStream);
        } catch (Exception e) {
            throw getNamingException("Couldn't get configuration from xml", e);
        }
 
        final LogDelegateFactory logDelegateFactory =
                (LogDelegateFactory) instantiate(config.getLogDelegateFactoryClassName());
        org.hornetq.core.logging.Logger.setDelegateFactory(logDelegateFactory);
 
 
        final InputStream jmsXmlStream = getStream(env.get(JMS_XML_PATH_KEY));
        final JMSServerConfigParser jmsServerConfigParser = new JMSServerConfigParserImpl();
        JMSConfiguration jmsConfig;
        try {
            jmsConfig = jmsServerConfigParser.parseConfiguration(jmsXmlStream);
        } catch (Exception e) {
            throw getNamingException("Couldn't get jms info from xml", e);
        }
 
        for (ConnectionFactoryConfiguration cfConfig : jmsConfig.getConnectionFactoryConfigurations()) {
            final HornetQConnectionFactory hqcf =
                    getHornetQConnectionFactory(cfConfig, config.getConnectorConfigurations());
            for (String jndiName : cfConfig.getBindings()) {
                ctx.bind(jndiName, hqcf);
            }
        }
 
        for (JMSQueueConfiguration queueConfiguration : jmsConfig.getQueueConfigurations()) {
            Queue queue = HornetQDestination.createQueue(queueConfiguration.getName());
            for (String jndiName : queueConfiguration.getBindings()) {
                ctx.bind(jndiName, queue);
            }
        }
 
        for (TopicConfiguration topicConfiguration : jmsConfig.getTopicConfigurations()) {
            Topic topic = HornetQDestination.createTopic(topicConfiguration.getName());
            for (String jndiName : topicConfiguration.getBindings()) {
                ctx.bind(jndiName, topic);
            }
        }
    }
 
    private InputStream getStream(String xmlPath) throws NamingException {
        final InputStream xmlStream = this.getClass().getResourceAsStream(xmlPath);
        if (xmlStream == null) {
            throw new NamingException("Cannot find resource at <" + xmlPath + ">");
        }
        return xmlStream;
    }
 
    private Context getContext(Map<string, String> env) throws NamingException {
        final String icfClassName = env.get(INTERNAL_ICF_IMPL_KEY);
 
        InitialContextFactory icf = (InitialContextFactory) instantiate(icfClassName);
 
        //noinspection UseOfObsoleteCollectionType
        return icf.getInitialContext(new Hashtable<object, Object>());
    }
 
    /**
     * Instantiate the supplied class name via its 0-arg ctor.
     *
     * @param className class name to instantiate
     *
     * @return instance of className
     *
     * @throws NamingException if the class cannot be instantiated
     */
    private Object instantiate(String className) throws NamingException {
        Object obj;
        try {
            final Class<?> klass = Class.forName(className);
            final Constructor<?> ctor = klass.getConstructor();
            obj = ctor.newInstance();
        } catch (ClassNotFoundException e) {
            throw getNamingException("Couldn't find class " + className, e);
        } catch (NoSuchMethodException e) {
            throw getNamingException("Couldn't find 0-arg constructor for " + className, e);
        } catch (InvocationTargetException e) {
            throw getNamingException("Couldn't instantiate " + className, e);
        } catch (InstantiationException e) {
            throw getNamingException("Couldn't instantiate " + className, e);
        } catch (IllegalAccessException e) {
            throw getNamingException("Couldn't instantiate " + className, e);
        }
        return obj;
    }
 
    private static NamingException getNamingException(String message, Exception e) {
        final NamingException ne = new NamingException(message);
        ne.initCause(e);
        return ne;
    }
 
    /**
     * @param env  the env to look in
     * @param keys the keys to check for
     *
     * @throws NamingException if any key is not found in the env or if the value is null
     */
    private void checkKeys(Map<string, String> env, String... keys) throws NamingException {
        for (String key : keys) {
            if (env.get(key) == null) {
                throw new NamingException("Couldn't find " + key + " property in " + env);
            }
        }
    }
 
    static HornetQConnectionFactory getHornetQConnectionFactory(ConnectionFactoryConfiguration cfConfig,
            Map<string, TransportConfiguration> connectorConfigurations) throws NamingException {
 
        /*
         * Implementation largely lifted from JMSServerManagerImpl
         */
 
        List<pair<transportConfiguration, TransportConfiguration>> connectorConfigs =
                new ArrayList<pair<transportConfiguration, TransportConfiguration>>();
 
        for (Pair<string, String> configConnector : cfConfig.getConnectorNames()) {
            String connectorName = configConnector.a;
            String backupConnectorName = configConnector.b;
 
            TransportConfiguration connector = connectorConfigurations.get(connectorName);
 
            if (connector == null) {
                throw new NamingException("No configured connector with name <" + connectorName + ">");
            }
 
            logger.debug("Found connector config for <" + connectorName + ">");
            TransportConfiguration backupConnector = null;
 
            if (backupConnectorName != null) {
                backupConnector = connectorConfigurations.get(backupConnectorName);
 
                if (backupConnector == null) {
                    throw new NamingException("No configured backup connector with name <" + connectorName + ">");
                }
 
                logger.debug("Found backup connector config for <" + backupConnectorName + ">");
            } else {
                logger.debug("Not using a backup connector for main connector <" + connectorName + ">");
            }
 
            connectorConfigs.add(new Pair<transportConfiguration, TransportConfiguration>(connector, backupConnector));
        }
 
 
        HornetQConnectionFactory cf = HornetQJMSClient.createConnectionFactory(connectorConfigs);
        cf.setClientID(cfConfig.getClientID());
        cf.setClientFailureCheckPeriod(cfConfig.getClientFailureCheckPeriod());
        cf.setConnectionTTL(cfConfig.getConnectionTTL());
        cf.setCallTimeout(cfConfig.getCallTimeout());
        cf.setCacheLargeMessagesClient(cfConfig.isCacheLargeMessagesClient());
        cf.setMinLargeMessageSize(cfConfig.getMinLargeMessageSize());
        cf.setConsumerWindowSize(cfConfig.getConsumerWindowSize());
        cf.setConsumerMaxRate(cfConfig.getConsumerMaxRate());
        cf.setConfirmationWindowSize(cfConfig.getConfirmationWindowSize());
        cf.setProducerWindowSize(cfConfig.getProducerWindowSize());
        cf.setProducerMaxRate(cfConfig.getProducerMaxRate());
        cf.setBlockOnAcknowledge(cfConfig.isBlockOnAcknowledge());
        cf.setBlockOnDurableSend(cfConfig.isBlockOnDurableSend());
        cf.setBlockOnNonDurableSend(cfConfig.isBlockOnNonDurableSend());
        cf.setAutoGroup(cfConfig.isAutoGroup());
        cf.setPreAcknowledge(cfConfig.isPreAcknowledge());
        cf.setConnectionLoadBalancingPolicyClassName(cfConfig.getLoadBalancingPolicyClassName());
        cf.setTransactionBatchSize(cfConfig.getTransactionBatchSize());
        cf.setDupsOKBatchSize(cfConfig.getDupsOKBatchSize());
        cf.setUseGlobalPools(cfConfig.isUseGlobalPools());
        cf.setScheduledThreadPoolMaxSize(cfConfig.getScheduledThreadPoolMaxSize());
        cf.setThreadPoolMaxSize(cfConfig.getThreadPoolMaxSize());
        cf.setRetryInterval(cfConfig.getRetryInterval());
        cf.setRetryIntervalMultiplier(cfConfig.getRetryIntervalMultiplier());
        cf.setMaxRetryInterval(cfConfig.getMaxRetryInterval());
        cf.setReconnectAttempts(cfConfig.getReconnectAttempts());
        cf.setFailoverOnInitialConnection(cfConfig.isFailoverOnInitialConnection());
        cf.setFailoverOnServerShutdown(cfConfig.isFailoverOnServerShutdown());
        cf.setGroupID(cfConfig.getGroupID());
 
        return cf;
    }
}

Testing JMS code

As a bonus for reading this far, here’s JmsTestServerManager. This class makes it easy to start and stop an embedded HornetQ server. This is ideal for testing code that reads from or writes to JMS queues or topics, for instance. You should create one instance per test class (via @BeforeClass if you’re using JUnit 4) and call start() in setup (@Before) and stop() in teardown (@After). This means you’ll have a fresh server instance for each test. No more needing to clean up leftover messages in queues between each test! Fortunately, HornetQ stops and starts quite quickly so this is unlikely to be a performance problem for your tests.

 
package com.genius.testutil.jms;
 
import net.jcip.annotations.NotThreadSafe;
import org.hornetq.api.core.TransportConfiguration;
import org.hornetq.core.config.Configuration;
import org.hornetq.core.config.impl.ConfigurationImpl;
import org.hornetq.core.remoting.impl.invm.InVMAcceptorFactory;
import org.hornetq.core.server.HornetQServer;
import org.hornetq.core.server.HornetQServers;
import org.hornetq.jms.server.JMSServerConfigParser;
import org.hornetq.jms.server.JMSServerManager;
import org.hornetq.jms.server.config.JMSConfiguration;
import org.hornetq.jms.server.config.JMSQueueConfiguration;
import org.hornetq.jms.server.config.TopicConfiguration;
import org.hornetq.jms.server.impl.JMSServerConfigParserImpl;
import org.hornetq.jms.server.impl.JMSServerManagerImpl;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
 
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import java.io.InputStream;
import java.util.HashSet;
import java.util.Set;
 
/*
 * See org.hornetq.tests.util.JMSTestBase
 */
 
/**
 * Runs an embedded HornetQ server suitable for use in unit tests that need JMS. It should be re-used across test
 * methods; just call start() in @Before and stop() in @After.
 */
@NotThreadSafe
public class JmsTestServerManager {
    private static final Logger logger = LoggerFactory.getLogger(JmsTestServerManager.class);
 
    private static final String INVM_ACCEPTOR_FACTORY = InVMAcceptorFactory.class.getCanonicalName();
 
    private static final String DEFAULT_HORNETQ_TEST_JMS_XML = "/hornetq-test-jms.xml";
 
    /**
     * Queues to add when the server is started
     */
    @NotNull
    private final Set<string> queueNames;
 
    /**
     * Topics to add when the server is started
     */
    @NotNull
    private final Set<string> topicNames;
 
    /**
     * The context passed to the jms server (proxied to prevent close()). No objects are registered in it; it is simply
     * provided to the server so that the server doesn't try to create its own.
     */
    @NotNull
    private final Context context;
 
    /**
     * null if the server is stopped
     */
    @Nullable
    private JMSServerManager jmsServer;
 
    /**
     * null if the server is stopped
     */
    @Nullable
    private HornetQServer server;
 
    /**
     * @param context    the context to give to the server.
     * @param queueNames set of queue names to create in the server
     * @param topicNames set of topic names to create in the server
     */
    private JmsTestServerManager(@NotNull Context context, @NotNull Set<string> queueNames,
            @NotNull Set<string> topicNames) {
        this.queueNames = queueNames;
 
        // avoid having the server initialize its own InitialContext, and don't let it close the InitialContext
        // since we want to keep it open across invocations
 
        this.context = new ReadOnlyContextProxy(context);
        this.topicNames = topicNames;
    }
 
    /**
     * @param context      The JNDI context to pass to the server
     * @param pathToJmsXml The classpath path to the hornetq jms file to read topics and queues from
     *
     * @return a configured JmsTestServerManager in the stopped state
     */
    static JmsTestServerManager getNew(@NotNull Context context, @NotNull String pathToJmsXml) {
        final JMSConfiguration configuration = getJmsConfiguration(pathToJmsXml);
        return new JmsTestServerManager(context, getQueueNames(configuration), getTopicNames(configuration));
    }
 
    /**
     * Create a new InitialContext and read queues & topics from the default xml path.
     *
     * @return a configured JmsTestServerManager in the stopped state
     *
     * @throws NamingException if an InitialContext can't be created
     * @see JmsTestServerManager#getNew(Context, String)
     */
    static JmsTestServerManager getNew() throws NamingException {
        // It's ok to not close this context since we want it to be left open
        //noinspection JNDIResourceOpenedButNotSafelyClosed
        return getNew(new InitialContext(), DEFAULT_HORNETQ_TEST_JMS_XML);
    }
 
    /**
     * Provides access to the context used by this object to avoid needing to re-create it.
     *
     * @return the context used by this reader
     */
    @NotNull
    public Context getContext() {
        return this.context;
    }
 
    /**
     * Start the server and add all queues to it.
     */
    public void start() {
        if (this.server != null) {
            throw new IllegalStateException("Server already started");
        }
 
        this.server = HornetQServers.newHornetQServer(createDefaultConfig());
        try {
            this.jmsServer = new JMSServerManagerImpl(this.server);
            this.jmsServer.setContext(this.context);
            this.jmsServer.start();
        } catch (Exception e) {
            throw new YourCustomTestException("Couldn't start JMS server", e);
        }
 
        try {
            for (String queue : this.queueNames) {
                logger.debug("Adding queue " + queue);
                this.jmsServer.createQueue(false, queue, null, false);
            }
            for (String topicName : this.topicNames) {
                logger.debug("Adding topic " + topicName);
                this.jmsServer.createTopic(false, topicName);
            }
        } catch (Exception e) {
            throw new YourCustomTestException("Couldn't create destination", e);
        }
    }
 
    /**
     * Shut down the server.
     */
    public void stop() {
        if (this.server == null) {
            throw new IllegalStateException("Server not started");
        }
 
        try {
            this.jmsServer.stop();
            this.server.stop();
        } catch (Exception e) {
            throw new YourCustomTestException("Couldn't stop JMS server", e);
        }
 
        this.jmsServer = null;
        this.server = null;
    }
 
    private static JMSConfiguration getJmsConfiguration(String pathToJmsXml) {
        final InputStream xmlStream = JmsTestServerManager.class.getResourceAsStream(pathToJmsXml);
        if (xmlStream == null) {
            throw new YourCustomTestException("Couldn't find hornetq jms xml");
        }
 
        final JMSServerConfigParser jmsServerConfigParser = new JMSServerConfigParserImpl();
        JMSConfiguration jmsConfig;
        try {
            jmsConfig = jmsServerConfigParser.parseConfiguration(xmlStream);
        } catch (Exception e) {
            throw new YourCustomTestException("Couldn't get jms info from xml", e);
        }
 
        return jmsConfig;
    }
 
    private static Set<string> getTopicNames(JMSConfiguration jmsConfig) {
        Set<string> topicNames = new HashSet<string>();
        for (TopicConfiguration topicConfiguration : jmsConfig.getTopicConfigurations()) {
            topicNames.add(topicConfiguration.getName());
        }
 
        return topicNames;
    }
 
    private static Set<string> getQueueNames(JMSConfiguration jmsConfig) {
        Set<string> queueNames = new HashSet<string>();
        for (JMSQueueConfiguration jmsQueueConfiguration : jmsConfig.getQueueConfigurations()) {
            queueNames.add(jmsQueueConfiguration.getName());
        }
 
        return queueNames;
    }
 
    private Configuration createDefaultConfig() {
        Configuration configuration = new ConfigurationImpl();
        configuration.setSecurityEnabled(false);
        configuration.setJMXManagementEnabled(true);
        configuration.setPersistenceEnabled(false);
 
        configuration.setFileDeploymentEnabled(false);
 
        configuration.getAcceptorConfigurations().add(new TransportConfiguration(INVM_ACCEPTOR_FACTORY));
 
        // avoid the log about using the default cluster password
        configuration.setClusterPassword("asdf");
        configuration.setLogDelegateFactoryClassName(SLF4JLogDelegateFactory.class.getCanonicalName());
 
        return configuration;
    }
}

You may have noticed ReadOnlyContextProxy being used in JmsTestServerManager. That’s a rather boring Context implementation that proxies all read-only method calls to an internal Context instance and has a no-op close() implementation. This is to prevent HornetQ from closing the Context since we want to keep the Context open through all test method invocations to prevent pointlessly re-creating an InitialContext every time.

The rather uninteresting source of ReadOnlyContextProxy follows to save you from writing your own.

package com.genius.testutil.jms;
 
import net.jcip.annotations.NotThreadSafe;
 
import javax.naming.Binding;
import javax.naming.Context;
import javax.naming.Name;
import javax.naming.NameClassPair;
import javax.naming.NameParser;
import javax.naming.NamingEnumeration;
import javax.naming.NamingException;
import java.util.Hashtable;
 
/**
 * Proxies Context methods to let us control what happens to a Context that we pass in to the embedded JMS server.
 */
@NotThreadSafe
class ReadOnlyContextProxy implements Context {
 
    private final Context context;
 
    ReadOnlyContextProxy(Context context) {
        this.context = context;
    }
 
    @Override
    public void close() throws NamingException {
        // no op
    }
 
    /*
     * State-change methods not allowed. Could also no-op them if the exception becomes problematic, but
     * org.hornetq.tests.unit.util.InVMContext UOEs on many operations.
     */
 
    @Override
    public void bind(Name name, Object obj) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public void bind(String name, Object obj) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public void rebind(Name name, Object obj) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public void rebind(String name, Object obj) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public void unbind(Name name) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public void unbind(String name) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public void rename(Name oldName, Name newName) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public void rename(String oldName, String newName) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public void destroySubcontext(Name name) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public void destroySubcontext(String name) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public Object addToEnvironment(String propName, Object propVal) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public Object removeFromEnvironment(String propName) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public Context createSubcontext(Name name) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    @Override
    public Context createSubcontext(String name) throws NamingException {
        throw new UnsupportedOperationException();
    }
 
    /*
     * Read-only methods left alone.
     */
 
    @Override
    public NamingEnumeration<nameClassPair> list(Name name) throws NamingException {
        return context.list(name);
    }
 
    @Override
    public NamingEnumeration<nameClassPair> list(String name) throws NamingException {
        return context.list(name);
    }
 
    @Override
    public NamingEnumeration<binding> listBindings(Name name) throws NamingException {
        return context.listBindings(name);
    }
 
    @Override
    public NamingEnumeration<binding> listBindings(String name) throws NamingException {
        return context.listBindings(name);
    }
 
    @Override
    public Object lookupLink(Name name) throws NamingException {
        return context.lookupLink(name);
    }
 
    @Override
    public Object lookupLink(String name) throws NamingException {
        return context.lookupLink(name);
    }
 
    @Override
    public NameParser getNameParser(Name name) throws NamingException {
        return context.getNameParser(name);
    }
 
    @Override
    public NameParser getNameParser(String name) throws NamingException {
        return context.getNameParser(name);
    }
 
    @Override
    public Name composeName(Name name, Name prefix) throws NamingException {
        return context.composeName(name, prefix);
    }
 
    @Override
    public String composeName(String name, String prefix) throws NamingException {
        return context.composeName(name, prefix);
    }
 
    @Override
    public Hashtable<?, ?> getEnvironment() throws NamingException {
        return context.getEnvironment();
    }
 
    @Override
    public Object lookup(Name name) throws NamingException {
        return context.lookup(name);
    }
 
    @Override
    public Object lookup(String name) throws NamingException {
        return context.lookup(name);
    }
 
    @Override
    public String getNameInNamespace() throws NamingException {
        return context.getNameInNamespace();
    }
}

With these classes, you’ve got all you need to get started writing JMS code (and testing it, too).