Several months ago I put up a tutorial on using Jetty, Jersey, Jackson and Guice to make a small JSON web service stack. The code is more of a proof of concept than anything else, but we’re going to be giving it a few more real-world features today by adding the use of the Metrics library. 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());

Read on →

There’s some confusion on the Internet about how to control which certificates are used for server (and non-server) TLS sockets and why client certs just don’t seem to work right (see here, here, here, here, etc.). I’ll explain how the process is supposed to happen, explain why it doesn’t necessarily work easily with Java, and how to work around the problem. Though this article generally applies to SSL as well as TLS, I’ll refer to just TLS from now on. Also, the testing and bug hunting in this article were done against Sun/Oracle’s JDK 6u25. I have not confirmed whether or not these issues are fixed in Java 7.

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.

X509

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.

Read on →

MySQL’s Connector/MXJ is a tool that exposes the ability to start and stop an embedded MySQL server through a Java API. You can have the MySQL JDBC driver start up a server just by appropriately configuring your JDBC url or you can programmatically control the server through the MysqldResource class. It does this by bundling precompiled versions of the mysql (client) and mysqld (server) binaries and invoking the correct ones based on the os.name and os.arch system properties. 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!

Read on →

Another Java web framework? Not really…

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();

Read on →