This is an interesting JEP as it proposes no Java consumer-oriented APIs; the only changes would be on the sun.misc.Unsafe class - which is already a fascinating pivot point for many of the advanced concurrency features of Java. Here is a Stack Overflow article that recaps many of them better than I could: StackOverflow.com: “Interesting Uses of sun.misc.Unsafe”. This class (as you can guess from the package) is not intended for regular Java devs to access; it’s an implementation-specific class, and is really only meant for internal use by class library devs on the JDK. (That said, many folks have taken this class by the horns to wrangle the most out of the JVM anyway.)

What is proposed instead is to make ordering fences with memory a first-class citizen in the implementation layer of the JDK so that the various core APIs for concurrency can leverage fencing without having to resort on side-effects of other lower-level intrinsics (something that is done regularly today).

You may be asking why memory fencing is important. Modern CPUs can easily re-order memory accessing and storing when it can see via the upcoming instruction set that re-ordering will not impact the overall outcome of the program as considered by a single thread in the CPU. When you start throwing multiple threads or CPUs at a problem, out-of-order operations on memory that would otherwise go un-noticed could instead cause all kinds of data corruption and confusion. That’s why effectively all of the core synchronization and atomic operations in Java today implicitly carry a memory fence along with them; it’s part of the larger equation of protecting memory access.

This JEP includes three operations in the proposal:

• Unsafe.loadFence() - Prevent reordering of load operations before this call with loads and stores after this call.
• Unsafe.storeFence() - Prevent reordering of store operations before this call with loads and stores after this call.
• Unsafe.fullFence() - Prevent reordering of all memory operations before this call with loads and stores after this call.

You can read more about memory fences in the Wikipedia Memory Barrier article.

It’s worth noting that the JEP does consider potentially surfacing memory fence operations to full devs at some point in the future given that sun.misc.Unsafe is already platform specific (making it risky for external libs to access), and may become impossible to access given the efforts of Jigsaw:

Adding these methods at the VM level permits use by JDK libraries in support of JDK 8 features, while also opening up the possibility of later exporting the base functionality via new java.util.concurrent APIs. This may become essential to allow people developing non-JDK low-level libraries if upcoming modularity support makes these methods impossible for others to access.

MBeans give us a tremendous amount of access into the running system, and are a good standardized way to publish the management tools. Unfortunately, they are a tremendous pain in the ass to get access to in a secure system.

Generally what I am given for any system we connect to is my own SSH key or SSH credentials, and possibly one or two ports popped open with pinholes for my IP address. The latter I can provide for myself with SSH tunnelling if I need to. Unfortunately, this isn’t enough for JMX.

JMX runs on top of RMI, and as such, there are two ports that JMX utilizes:

• The JMX connect port.
• The (infamously) roaming RMI data port.

In all recent builds of Oracle Java, you can affix the first port via this system property when starting the Java program:

-Dcom.sun.management.jmxremote.port=1099

Unfortunately, the second port has no mechanism for assignment. This means that you either need (a) the entire firewall cracked wide open for your IP address, or (b) you need to run a dynamic socks proxy and route your particular JMX tool through the proxy. The latter is generally the only real option. You then have the added complexity that the hostname you connect to needs to match the value of java.rmi.server.hostname, which in cloud solutions that do complex things with IP addresses (I’m looking at your EC2), only makes it even harder to get right.

Thankfully (and I do mean thankfully), not anymore for systems running Java 7u4 or higher. Marcus Hirt has blogged about the new RMI binding property that has come to Java since the merger with JRockit.

Now, one handy but often overlooked feature that entered the 7u4 JDK as part of the JRockit convergence, was the ability to specify the port of the RMI server. By setting the port used by the RMI registry and the RMI server to the same port, tunneling will be much easier. Now, the name of the property for setting the port of the RMI Server was slightly changed from the JRockit implementation, and is now called com.sun.management.rmi.port, instead of com.sun.management.rmiserver.port. Here is an example of how to enable the external management agent with the same RMI registry and RMI server port on the command line, in JDK 7u4 and later:

java -Dcom.sun.management.jmxremote.port=7091 -Dcom.sun.management.jmxremote.rmi.port=7091 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false

I cannot stress enough how much this should help those of us dealing with firewalled systems and JMX. Kudos!

There are a number of enhancements being proposed in this JEP, so I’ll probably tackle it in a few blog posts. For today, we’ll talk numbers!

Atomic-ish Numbers

It’s very very common to use atomic values in metrics gathering capacities in Java application. Applications everywhere (if they know what is good for them) are doing things like tracking total execution time, # of executions, and max execution time for as many data points as they can stomach.

Compared to the “olden days” of Java, atomics (particularly java.util.concurrent.atomic.AtomicLong) are a huge boon for this as they get rid of the overhead caused by contention when you’re dealing with synchronization. A particular code-flow will be much more concurrent when updating an atomic value than trying to fence through a synchronization boundary in heavy traffic.

However, all is not well in atomic land. While they are much better than everything that has come before them, they can still be quite disruptive. Updating an atomic value is, by definition, still fully shared between threads. While it’s a narrow operation, the guarantee is that after the operation is done, all CPU active on the system will see the same value in that memory location. To do this, the CPU core doing the work has to ensure that the value of that atomic is pushed back out to main memory; not just retained in the CPU cache. And in so doing, it has to keep trying to update the core memory until the incremental is what is expected (via a CAS - compare and swap operation). This CAS and memory fence ensures that staleness does not happen due to the CPU keeping data in local cache only, and not dumping out to slow system memory constantly.

However, this inherently means that, for this value, we are writing out to slow system memory constantly. So it’s not free. Additionally, what often can happen is that the atomic changing invalidates a line of cache shared by multiple values. This is fairly common because the contiguous cache blocks the CPU is designed to invalidate are generally large enough to hold multiple numeric values. This means that the CPU is forced to (unintentionally) re-fence multiple atomics; often atomics that are allocated together for the same data structure.

This lack of cache coherence and affinity can be a very real, and very hidden cost with all fence operations. Martin Thompson and Michael Barker (the wizards behind the much discussed LMAX Architecture and the disruptor stream processing framework) have a talk that covers this problem (and many others) in detail titled Lock-Free Algorithms.

Thompson and Barker show exactly how much this cache issue can impact performance, and how with a little adjusting, the atomic classes can be designed with what they call “mechanical sympathy” in mind; in other words, built to avoid sharing cache regions with other atomic values. So instead of this:

cache line 1 . . . . <atomic int val A> . . . . . <atomic int val B> . . .
cache line 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

You ideally would get this:

cache line 1 . . . . <atomic int val A> . . . . . . . . . . . . . . . . .
cache line 2 . . <atomic int val B> . . . . . . . . . . . . . . . . . . .

Now the two values are isolated from each other, reducing cache damaging significantly.

While I’m listing interesting related reads, another article just popped up in the past couple days that shows some very real metrics for the problems you can hit with Atomics in terms of program throughput. Marc Brooker just posted how atomics and volatiles in Java work on x86, and it shows exactly what a lack of mechanical sympathy can mean to your cache hit performance. The perf stat output he shows with the significant increase of LLC-load-misses is exactly what this padded cache is meant to mitigate as much as possible - of course, it can only do so much; the entire idea of an atomic implies there is some shared memory involvement, which is simply going to be slower. The goal is to narrow that slowness to specific values, as much as possible.

So mechanical sympathy changes help, but only get you so far. The work in JEP-155 doesn’t stop by exploring this idea. There is another issue with atomics as it pertains to being used for metrics-like monitoring in large scale Java systems. Their atomic requirement may actually be too stringent. Often times when you’re looking at something like an “average” execution time or “max” execution time, it’s acceptable to say the value can be eventually consistent across multiple updates. If there is a little margin for error (like you might miss one recent update on a read), it’s not going to impact your analysis in any real way.

Knowing this, the JSR166 folks have taken one of the ideas that are common in highly concurrent programming, and applied them to these types: striping, or segmenting.

If you’ve ever looked into the internals of the ConcurrentHashMap class, you may be familiar with the constructs it uses to minimize contention and avoid locking. Internally, the CHM uses a series of segments which represent sub-sections of the map, and can be worked with independently. By using multiple segments, the data structure is able to immediately divide the potential contention, at the expense of a little more memory used.

(Incidentally, the fastest JDBC connection pool I’ve ever benchmarked at scale uses this same mechanic to avoid pool contention - see BoneCP.)

This same idea is in place for a number of new atomic classes. There is an abstract Striped64 super-class that holds a collection of Cell objects, which are really just Atomics with special padding to help with mechanical sympathy. The cells are created lazily as CAS updates fail due to contention. What this means is that a single instance of this may have several internal atomics representing the value in the aggregate. Since this class doesn’t just sit on the CAS wall until it updates successfully, it doesn’t have the same repeated crawling down into shared memory from the CPU cache. Instead it will retry a set number of times, and if it can’t get the first cell to update, it creates another one. The next one is a fully separate atomic in memory, and is bound by its own memory fencing and contention.

What’s interesting about this is since the atomics are intentionally written to avoid cache collisions, each one can be independently represented on a CPU, and since the class will try to balance the cells to individual threads, it will avoid causing the painful contentious updates altogether, making the most valuable use of the atomics. Each thread can say “If I created a new cell because a previous cell was contentious, I’ll keep using that new cell” - this means that CAS collisions can theoretically be eliminated over time, with the expense of potentially creating a larger memory footprint for a single number.

Since the cells are all independently update-able and create-able, and based on multiple iterative passes, the process of calculating a value over them involves iterating each cell and getting a snapshot value from them independently. Because of that, it’s possible that during the iteration, some of the cells may be slightly out of date or non existent on my local thread.

Additionally, since this is all based on combining the values out of multiple cells together, it immediately implies that there are only certain accumulative operations where this segmentation can be used.

There are several new classes that extend Striped64 to provide relaxed-consistency classes for cases where you want to accumulate values in this way:

• LongAdder; DoubleAdder - Classes that allow threads to accumulate values into a long or double in a thread-safe, and extremely low-contention path. Example Usage: Accumulating total execution time for a particular call so you can calculate average execution time.
• LongMaxUpdater; DoubleMaxUpdater - Classes that allow threads to calculate the “max” value seen up to a point, again in a very low-contention implementation. Example Usage: Tracking the max execution time for a particular method call.
• LongAdderTable - A handy extrapolation of long adder into a hash table form. This is an optimized map of LongAdders (although it doesn’t implement the Map interface for a number of reasons) that is specifically designed to be as efficient as possible in the use of long adder values per key, and allows for decrementing, incrementing, and adding by key. It also will create the adders for you automatically simply as an operation of you incrementing. Example Usage: Tracking several call execution times for an application all in one data structure.

Let’s look at how these classes work internally to bring home the idea of cells for contention management. If we look at the LongAdder class as an example - let’s say we have a simple counter value we’re tracking for some method call, and it looks like this at one point:

LongAdder
|
*-- Cell[0] = 51352

Our thread comes in to increment the first cell and we keep getting a CAS collision. So, based on the collision heuristics, we decide to create a new cell and increment there:

LongAdder
|
*-- Cell[0] = 51494
|
*-- Cell[1] = 1

Note that Cell[0] has incremented several times outside of our control (other threads), and we also created Cell[1] to hold our new value.

To calculate the sum total for this long adder, we simply sum all of the cells together, returning 51495.

The internal documentation on the Striped64 draft class has phenomenal notes on the algorithm).

While discussing atomic numbers, it should also be noted that there are implementations of AtomicDouble and AtomicDoubleArray laid out in the extras package of this draft work as well. These would ideally bring true atomic floating point to Java for the first time, but as indicated on the draft group site, the extras folder is probably not going to make it into Java 8 directly. They do show how these can be implemented, however, which is a feat in and of itself.

What’s Next?

There’s a good bit more in the JEP-155 bundle, including stamped locks and some nifty fork join improvements. Those are for another time, however.

One of the recently announced JEPs is JEP 169 - Value Objects. Value objects are a number of tools for expicitly declaring that a Java object represents a raw set of vectorize-able values, rather than a composite set of memory values linked via pointers, and dynamically allocated on the heap.

As Java programmers, most of us are comfortable with (even if not entirely happy with) the distinction between primitives and objects. It’s one of those ugly, very un-academic pragmatics that you deal with because of the benefits it brings. Unfortunately, as the aforementioned JEP mentions, it’s also an ugly dividing line. You find yourself choosing between very low-level and hard-to-manage data structures and value types, or choosing more manageable high-level types, sacrificing the performance gains you would see otherwise:

In modern JVMs, object allocation is inexpensive, with a cost comparable to out-of-line procedure calling. But even this cost is often a painful overhead when compared to individual operations on primitive values. Thus, Java programmers face a binary choice between existing primitive types (which avoid allocation) and other types (which allow data abstraction and other benefits of classes). When they need to define small composite values such as complex numbers, pixels, or pairs of return values, neither approach serves. This dilemma often has no good solution, and the workarounds distort Java programs and APIs. Consider, for example, the lack of a good complex number type for those who program numeric algorithms in Java.

The general idea is allow programmers to give the JVM more knowledge about objects that are already designed to be immutable and simply represent a value, so that it can be treated in a more efficient way; much like primitives.

The example that is used repeatedly in the JEP is a class that represents a Complex number; call it java.lang.Complex. As you may or may not know, Java today doesn’t have a complex number value type. There are a number of open-source and academic examples of creating one, with the commonality between them being that they are written as a Java object. Usually, they are represented as a couple double values internally, and they have a numbef of methods for doing things like adding, subtracting, dividing, calculating cosine, and so forth. Apache-Commons Math has a perfect example.

However, if you think about it, there is really no reason this Complex value has a full heap allocated object. It’s really just a couple primitives that are bound together inextricably. But the only way to do this with pure primitives would be to juggle multiple primitive values manually, and that’s not exactly a pretty API: hard to explain to implementors, and very hard to add functionality around. Sadly, a lot of APIs that have to deal with quickly shuffling numeric values (such as rendering APIs) fall into the trap of having to deal with buckets o’ numbers.

This JEP is an attempt at tackling this problem. Once an object has been declared a value object, it can now be scalarized by the VM into a compact binary representation that can be propagated on the stack, and can even be interned in memory. In other words, the VM can treat the Complex class exactly like two double values held in a single memory vector; but the developer code can still handle it like an object, with all of the encapsulation and behavioral binding that implies.

Because the value object is being treated like a primitive, it now has no surrogate identity (no pointer location), and as such, it can’t be used for operations like synchronization and reference equality checks.

Boxing Benefits

One of the interesting notes about this proposal is the fact that it changes the cost and complexity of boxing and unboxing of values from primitive types and back. Consider this contrived example:

public void someMethod() {
	int val1 = 5;
	int val2 = 10;
	int result = sumofsquares(a, b));
	// ...
}

public Integer sumofsquares(Integer a, Integer b) {
	return square(a) + square(b);
}

public Integer square(Integer val) {
	int val = val.intValue();
	return val * val;
}

In this case, we have two primitive values in someMethod(), but immediately pass them into a method that expects boxed types. As such, the compiler is going to secretly inject code like this: sumofsquares(Integer.valueOf(val1), Integer.valueOf(val2)).

What this new value objects support would allow the compiler and runtime to do is defer any of boxing all the way until some complex behavior is invoked on the type - in this case that would be the intValue() invocation within the square method. However, since the compiler can determine it’s simply calling a method that returns the value component contained there-in, it can actually completely eliminate the boxing altogether.

The method tree then turns around and returns a boxed value again, but the compiler and runtime can again eliminate any boxing, as the method tree never deals with them in a complex way.

Therefore, somewhat surprisingly, the boxing to a reference style java.lang.Integer above can in fact be eliminated completely. The other exciting benefit is that your own value types can be treated this same way, even though (unlike int and Integer) there is no native primitive value directly representing your type. This opens a whole new opportunity for expressive and clean APIs that have to deal with primitives, closing many of the difficult “performance vs. readable” problems Java developers have faced.

Class vs Object

Several months ago I watched a presentation from Brian Goetz (can’t find the specific talk) where he discussed the potential for value objects in Java’s future, and at the time the thought was that it could be a new keyword or annotation on the type that indicated it was a value type. This proposal, however, discusses using a per-instance locking mechanism similar to:

Integer x = new Integer(123456);
// Not yet a value object...
x = x.lockPermanently();
// Now a value object...

There are some benefits to this manual locking:

• You can use some objects as reference types; if you’re synchronizing on Integer somewhere in your code (Why?) this would allow you to continue to do so.
• Initialization of objects that will eventually be value types can be done in multiple steps.
• Even if your code (or some library you use) doesn’t mark the object as a value type explicitly, the JIT can still analyze the usage of the object, and transliterate it to a value type internally as a form of runtime optimization.

This idea of value objects becomes a huge benefit when exploring expressive sophisticated functional programming models. Since one of the main tenants of functional programming is immutable types - if Java can in turn represent those immutable types as primitive values, it helps ensure that functional programming models don’t pay a penalty for their expressivity and immutability.

The answer, in fact, is straightforward: Multibindings.

What is particularly neat about multi-bindings (aside from the fact they can inject a set of objects) is that they will accept bindings from multiple modules into the final aggregate set that is injected. Both sets and maps can be injected in this way. This example will use the MapBinder, as the base Guice example for Sets is fairly straightforward in its own right. Consider a music decoding application, for example. You might have simple decoder API that looks like this:

public interface AudioDecoder {
    String getAudioTypeName();
    void decode(InputStream encodedIn, OutputStream pcmOut);
}

Individual modules can inject their own audio decoding algorithm:

public class Mp3AudioDecoder {
  public String getAudioTypeName() { "MP3"; }
  public void decode(InputStream mp3In, OutputStream pcmOut) {
    // Run through LAME (or similar Fraunhofer) decoding here.
  }
}

// ...

public class Mp3AudioModule extends AbstractModule {
  public void configure() {
    Multibinder<String,AudioDecoder> decoderBinder
      = MapBinder.newMapBinder(binder(), AudioDecoder.class);
      decoderBinder.addBinding("mp3").to(Mp3AudioDecoder.class);
  }
}

What this does is register a binding with the multibinder from AudioDecoder to Mp3AudioDecoder; effectively registering that type as part of the total set of audio decoders. Consuming these via injection requires no special sauce; simply declaring you want to receive the map is all that is required:

public class RootModule extends AbstractModule {
  public void configure() {
    bind(AudioDecodingThingy.class);
  }
}
        
public class AudioDecodingThingy {

  private final Map<String,AudioDecoder> decoders;
    
  @Inject
  public AudioDecodingThingy(Map<String,AudioDecoder> decoders) {
    this.decoders = decoders;
  }

  public void run(String inputFile, String outputFile) {
    // Basic error handling.
    File in = new File(inputFile);
    File out = new File(outputFile);
    String extension = getExtension(inputFile);

    if(!in.exists()) throw new IllegalArgumentException("File " + inputFile + " not found.");
    if(!decoders.containsKey(extension)) throw new IllegalArgumentException("No decoder found for extension: " + extension);
    if(!out.exists() && !out.createNewFile()) throw new IllegalArgumentException("Unable to create output file: " + outputFile);

    AudioDecoder decoder = decoders.get(extension);

    // Do the decoding.
    try(
      InputStream in = new FileInputStream(in);
      OutputStream out = new FileOutputStream(out)) {
        decoder.decode(in, out);
    }
  }
}
        
public class Main {
  public static void main(String[] args) {
    Injector i = Guice.createInjector(
      new RootModule(), new Mp3Module(), new OggModule());

    AudioDecodingThingy thingy
      = i.getInstance(AudioDecodingThingy.class);

    thingy.run(args[0], args[1]);
  }
}

While this particular example (and the example on the Guice site) have the modules to snap-in defined directly in the code, it is not a stretch of the imagination to envision the possible modules to install coming from:

• A configuration file
• The built-in JAR service-provider and ServiceLoader facilities.
• A scan for all particular annotated types; something like @PluginModule

As a final disclaimer (one that is reiterated on the Guice site) Multibindings are not a replacement for a full modular architecture, like that which can be achieved with OSGi (in fact, Guice has support for OSGi as well). However, sometimes OSGi can be a power-drill, when sometimes all you need is a plain ol’ screwdriver.

Multibindings, which are an extension to Guice, are shipped as a separate integration JAR file. All of the official extensions are available in the core Maven repositories under com.google.inject.extensions.

private Map<String,List<Something>> stuff = new HashMap<String,List<Something>>();

// ...

public void add(String key, Something item) {
  if(!stuff.containsKey(key)) {
    stuff.put(key, new ArrayList<Something>());
  }
  stuff.get(key).add(item);
}

public List<Something> get(String key) {
  return new ArrayList<Something>(stuff.get(key));
}

Google’s Guava Libraries provide a few collections to help with this common case: com.google.common.collect.Multimap, and the more specific variants ListMultimap, SetMultimap, and SortedSetMultimap.

The above code can be re-written with Guava like this:

private ListMultimap<String,Something> stuff = ArrayListMultimap.create();

// ...

public void add(String key, Something item) {
  stuff.put(key, item);
}

public List<Something> get(String key) {
  // might as well use the Lists convenience API while we're at it.
  return Lists.newArrayList(stuff.get(key));
}

The multi-map has a variety of fancy features that can be used as well. Here are just a few examples:

// returns a composite of all values from all entries.
Collection<Something> allSomethings = stuff.values(); 

// A more traditional map that can be edited.
Map<String, Collection<Something>> mapView = stuff.asMap();

// remove an individual entry for a key.
boolean removed = stuff.remove(key, someVal);

// remove all for a key
List<Something> removedSomethings = stuff.remove(key);

// One for each value in the map. Updating this collection updates the map.
Collection<Map.Entry<String,Something>> allEntries = stuff.entries();

All of the collections returned by the various API are views of the multimap. This can make it particularly easy to work with the map in a variety of ways. It does mean you should probably perform defensive copying anywhere you might be exposing these APIs (generally good practice in most cases, anyway).

It’s no surprise Java developers are trying to branch out: Java 7, which was nearly five years in the making, barely evolves the language features at all; most of the promised game-changers for the language (lambdas, extension methods, modules) were deferred to Java 8 due to lack of consensus and time. Java has become stagnant, too verbose, and too crufty for developers that have seen the greener grass on the other side.

Unfortunately, most JVM developers in the wild are still using the Java language in some capacity, and it seems to be fairly common in companies that there is a distinct reason that an alternative VM language hasn’t been adopted in its place. The reasons may not satiate the idealists of the JVM-based community, but they do exist. Just to name a few:

• Corporate restrictions
• Concerns about code maintainability
• Team skill-sets and strengths
• Stability and performance of the various language platform
• Lack of top-grade IDE support

Frameworks, on the other hand, often seem to be an easier pill to swallow. The barrier to entry for developers is often lower, the scope of impact on your application can be less pervasive, and your tools and team skill-sets are not stretched nearly so far. In reality, some frameworks (coughSpringcough) actually add more complexity than any language shift would, but this is unfortunately a game of perception. As it pertains to frameworks in the post-Java JVM world, those of you that follow my blog or Twitter account know that I’m a big fan of the Play! Framework, as it re-imagined what it means to write a Java web application, and it also provides an easy gateway into Scala. It shows that while Java the language is falling behind, it isn’t a complete wasteland for developers craving more.

A co-worker recently pointed out another intriguing Java framework that, while not being as full-featured or targeted for large applications as Play!, has a lot to offer to this neo-Java world: enter Spark.

Those of you who have worked with (or at least seen) Ruby’s Sinatra framework will instantly feel home (and perhaps vaguely disgruntled) with Spark. Spark is effectively the Sinatra-style of web-binding, using Java syntax. Here is an example from their home-page:

import static spark.Spark.*;
import spark.*;

public class HelloWorld {

   public static void main(String[] args) {
      
      get(new Route("/hello") {
         @Override
         public Object handle(Request request, Response response) {
            return "Hello World!";
         }
      });

   }

}

The general idea behind Spark is to make the binding between a URL to the actual code being run as thin as possible - allowing you to focus on servicing the request. When compared to many frameworks, the list of features it doesn’t have may be disconcerting; but, there is a certain power and portability in the simplicity. The self-coined term “micro-web-framework” is really only true due to the sheer volume of complexity and features that Java web frameworks have decided to provide (or impose) in the last few years.

Like Play!, Spark focuses on using very human-readable API design. The central component of Spark is the callback which handles the request. As seen in the above example, this is provided by the developer via a subclass of “Route”. What happens inside the callback to build the result is entirely up to you.

While Spark doesn’t get involved in the “manipulating data” part, there are a handful of features and utilities available to help with the control of HTTP-level web-flow. Some of these include:

• Filters - These are callbacks just like the routes that can be run based on certain URL patterns, allowing for functionality to be applied orthogonal to a set of requests.
• Request/Response Wrappers - The servlet request and response classes are well known (and often loathed) for their design. Spark, like many frameworks, wraps these to help conceal the suck.
• Halt Commands - This is an increasingly popular API design in web frameworks: methods that set an HTTP status code, and fail with an exception immediately.
• Redirects - Browser redirects are made particularly simple.

All of these features are shown in more detail on the Spark Readme Page.

Spark’s main facility for running is to start up an embedded Jetty server to automatically handle requests. This is right in-line with how Sinatra functions by default, and provides a quick and easy process for developers to get their application going to test and do development. While not documented on the site, Spark does support a deployed mode where it can be run inside of an already-deployed application server as a WAR with a web.xml file. This is done via the spark.servlet.SparkFilter class, which is a servlet filter that can route requests to your application.

In summary: it’s unlikely you would want to implement your entire enterprise on Spark, but that’s not really its goal. Spark is really targeted for quick-to-live “scrapplications”; getting something together in a short amount of time, and in the hands of users, without the pomp and circumstance of importing 900 JARs, and creating 35 configuration files. It explicitly avoids imposing a particular application model, data model, or really any dependencies at all on the developer, instead offering a small expressive Java API (as expressive as Java gets anyway), that allows you to quickly map blocks of Java code to RESTful HTTP routes. Overall - definitely worth checking out.

Earlier this week, the folks over at Packt Publishing were kind enough to forward me a copy of the Apache Wicket Cookbook for review, and given my previous positive experiences with Wicket, I was excited to dive in, and see what the book has to offer.

Overview

Apache Wicket Cookbook is a dense collection of recipes for working with the various Wicket features, and is written by Igor Vaynberg, one of the main Wicket committers, who is also a contributing author to Wicket in Action. While “Wicket in Action” is targeted at understanding the “what and why” of Wicket, this new cookbook is all about the “how”. To re-summarize from the preface of the book itself:

A straightforward Cookbook with over 70 highly focused practical recipes to make your web application development easier with the Wicket web framework.

The book is composed in a repeating format, showing different solutions to problems using the same rough outline for each recipe:

• Overview - To start each recipe, a short introductory set of paragraphs are provided that explain the problem at hand, and why it might be important to have a solution.
• Getting Ready - This section sets up the example for the recipe, providing the necessary code snippets to try the recipe out for yourself.
• How to do it - After prepping the example, this section jumps right in with highlighted code changes, showing how to solve this particular problem with Wicket.
• How it works - Now that the reader has seen what to do to fix the problem, this section explains how Wicket uses the code provided to handle the particular problem, and provides more detail for people who like to understand what’s going on under the covers.
• There’s more - Because these examples are so focused, they don’t touch on all facets of a particular API. This section provides highlights of other features to explore on your own.
• See also - A lot of the recipes are inter-related, solving similar, but different problems. This section points you to other recipes in the book that compliment the one you just read.

Review

Overall, I’ve been quite impressed with the “Apache Wicket Cookbook”. Having been quite familiar with Wicket over the years from writing a number of tutorial articles about it, and applications with it, I found the previously released “Wicket in Action” to be a bit of a redundant read; most of the code and APIs were familiar enough to me in concept, that I didn’t feel that book was the right target for me. This book, on the other hand, is very no-nonsense, and hits on a lot of detailed problems that even a seasoned “Wicketeer” would probably have to really dig to solve in a novel and clean way.

This book touches on many of the “hard” problems, including:

• The nuances of safe, attractive, and error-free form handling - the web is all about this, of course, but it seems like most people don’t do it right. Wicket has the tools, but you’ve got to know how to apply them - and there are enough recipes here to train your brain!
• Internationalization - Who hasn’t struggled with this in one fashion or another?
• Data Tables - Paging, Sorting, Filtering tables are another “hard to implement” cornerstone of the web, and an area where Wicket really shines.
• Security - Wicket’s security model is intense; that’s both good and bad, and this section really hits on some sticky (get it? Sticky wicket?) topics, like cross-site request forgery protection.

Other topics touched on by the book include AJAX and Rich UIs (another Wicket “wow” feature), middleware integration (e.g. Spring), and, interestingly enough, charting and graphing.

Being very familiar with Wicket, I didn’t feel the need to try most of these examples for myself, and so despite the book being over 300 pages in ebook form, I found myself finishing my read-through in short order. I wouldn’t say the book is short, but for me, it was over quickly.

Some of the sections, like the aforementioned chapter on charting, were new to me, and gave me a better feel of how this book would be received by someone less familiar. Others covered problems I have previously solved myself with Wicket, and I was happy to see solutions that I felt were both cleaner and more complete than the solutions I had “cooked up” myself.

Most of the examples are based in reality; not having the overly contrived feel of an author searching for a problem to solve; and many of the chapters focus on a particular example, and build upon it in several stages - providing a good picture on how to take a bare implementation and layer on features until it is “complete”.

If you are already familiar with Wicket, but would like to better understand how to use it effectively to build robust, feature-rich, and pretty applications, then this book is for you.

On the other hand, if you’ve never used Wicket before, you will be lost the moment you hit the first chapter. It just so happens, that Wicket in Action is already available for novices, as are a number of online resources (some by yours truly; albeit a little out of date).

For those of you that would like to try this new book out, I have been given access to a free chapter that you can download in PDF format: Chapter 5: Displaying Data Using DataTable.

In concept I have no problem with this sort of support. There are innumerable examples on the web of absurd Java try/catch/finally block hierarchies to properly managing input streams and output streams; something that is the norm, not the exception to the rule.

InputStream in;
try {
  in = loadInput(...);
    OutputStream out;
  try {
    out = createOutput(...);
    copy(in, out);
  }
  finally {
    if(out != null) {
      try {
        out.close();
      }
      catch(IOException ioe) {
        // Problem closing the output stream.
      }
    }
  }
}
catch(IOException e) {
  // Problem reading or writing with streams.
  // Or problem opening one of them.
}
finally {
  if(in != null) {
    try {
      in.close();
    }
    catch(IOException ioe) {
      // Problem closing the input stream.
    }
  }
}

I’m not even showing here how you handle the situation where reading/writing caused an error, and closing one or both of the streams caused an error. You want a way to cleanly collect all of these up into one exception bundle that can be properly logged/handled, but short of rolling your own wrapper exception to potentially hold all conditions, there simply is no way.

This abhorrent pile of braces can be cleanly tightened up with the new facilities in Java 7 like so:

try (InputStream in = loadInput(...); 
     OutputStream out = createOutput(...) ){
  copy(in, out);
}
catch (Exception e) {
  // Problem reading and writing streams.
  // Or problem opening one of them.
  // If compound error closing streams occurs, it will be recorded on this exception 
  // as a "suppressedException".
}

Java will know how to close items in the try parenthesis by those elements implementing the “AutoCloseable” interface. This is much like the “Iterable” interface that was added to support the enhanced-for loops in Java 5. Clearly this code is much cleaner, and automatic resource management is a facility that Java has needed (for a lonnnnnngg time) - so why am I miffed?

This feature, which is consuming a non-trivial amount of draft specification time and development time to get right, is being implemented as a language feature via the use of compiler changes - again, much in the same way as enhanced-for was implemented. For the record, I was miffed about enhanced-for as well (although I do use it regularly).

Adding this as a language feature, rather than a library feature, bloats the compiler specification and implementation, and completely hides the real implementation in generated code. It’s functional to a point, but is not extensible by developers. Sadly, none of this would be necessary at all if Java 7 shipped with lambda/closure support, and I think the syntax is more natural. Here is a naive Ruby file copy/transform algorithm.

begin
  File.open("myInput.txt", "r") do |in|
    File.open("myOutput.txt", "w") do |out|
      in.each_line do |line|
        out << line.upcase << "\n"
      end
    end
  end
rescue exc
  # Exception occurred reading/writing!
end

Now, admittedly the syntax is very different than the Java version - the most notable difference is that the Ruby version is actual three nested lambas, where as the Java version is sort-of two lambdas (one to open the resources, one to work with them). I say sort-of, because the first is this special quasi-code-block that also magically accumulates opened resources for later closure.

I find the lambda version to be much less hand-wavy - the syntax is naturally intuitive and more flexible. I should also note that the inner-most lambda, which iterates over lines in the file, shows that the enhanced for loop in Java is completely unnecessary as well if you have lambdas.

Using one of the proposed syntaxes for Java lambda support (as ugly as they can be), let’s take a shot at this same idea with Java:

try {
  File.read("myInput.txt", { in ->
    File.write("myOutput.txt", { out ->
      in.eachLine( { line ->
        out.write(line.toUpperCase() + "\n");
      });
    });
  });
}
catch(IOException e) {
  // handle as appropriate. Can still have suppressed exceptions on it.
}

This is just one way this could be implemented; because it only relies on functions, how expressive the APIs are is up to the library designer, not the language designer. An important distinction. Why build special scenarios into the compiler when one language feature can provide the flexibility you need?

Now - is this as short and tab-friendly as the Java 7 feature? Admittedly no. However, the goal of the try-with-resources is not to save on typing, but rather, to ensure resource management is as accurate as possible, relying as little as possible on the developer to dial-in boilerplate, and error-prone exception management.

Here is a short run-down of the library changes that would be required to support this particular code:

• java.io.File needs a new method called read which takes a String file name, and also takes a function that accepts a java.io.FileReader, and returns nothing. The code block may throw an IOException. This method does all of the resource management for the FileReader it provides to the function. If the code block throws an exception and closing the file reader also throws an exception, the method would add the close exception to the main exception as a suppressedException (just like the language feature would). java.io.File also needs a new method called write which takes a String file name, and also takes a function that accepts a java.io.FileWriter, and again, returns nothing. This can also throw and IOException, and just like the read method, it handles all of the minutia of exception suppression and resource-closing. java.io.FileReader needs a new method called eachLine that simple scans for line-terminators and lets a provided function see the string representation of each line. The function may throw IOException, and the method simply lets IOException propagate.

Just to circle back around - Java today could support the “eachLine” method on FileReader via enhanced-for loop, if the “eachLine” method returned an Iterable<String> (as opposed to accepting a block of code) - it could look something like this:

for(String line : in.eachLine()) {
  out.write(line.toUpperCase() + "\n");
}

Sadly, this feature will be here with Java 7, and lambdas will not. As such, it’s yet another way to buy time without lambdas, and look a little better next to the C# features list.

Because of my interest in the development of Mirah, I’ve decided to begin spelunking into the implementation as it stands today, sharing with you what is going on internally. Many of you are probably familiar with my ”Distilling JRuby” series, and while these articles will likely read similarly, I suspect they will be more brief and hand-wavy. This is partially out of a desire to cover more topics over a short period of time, but also because the implementation for Mirah is very fluid, and is likely to change, rendering these articles invalid or at least out-dated.

Without further ado - let’s kick this pig. On to Mirah’s type-inferencing!

Mirah Overview

There are a few key concepts that need to be discussed regarding Mirah before we get started:

• Mirah is not Ruby! Mirah looks like Ruby at first glance, but that is only superficial in nature. We will see why over the next series of topics.
• Unlike JRuby, Mirah is not implemented in Java (well, mostly not). It is actually implemented in Ruby - this is going to make the way we traverse the code in these articles very different than the JRuby series.
• While I say that Mirah borrows the Ruby syntax, it has to modify and add certain structures to fit the mold which has been carved for it. So while it is possible to write some programs that are almost true Ruby syntax, most Mirah programs will have a few extra sprinkles.
• Mirah is statically typed, and compiles to standard Java bytecode. This is one of the key reasons that Mirah is not 100% Ruby-grammar compatible.
• Mirah is designed from the ground up to be a language specification that can be implemented on several platforms (.NET is a perfect example). This introduces indirection in the code that may, at first, seem confusing.
• One of the key principals of Mirah is to avoid runtime encumbrances if at all possible. What this means is that all features in Mirah as it currently stands are implemented by either a compiler plug-in, or by using existing core libraries of the underlying platform (or a combination, of course). This goal is to hopefully avoid the 3-5 MB ball-and-chain that many languages (i.e. Scala, Clojure, JRuby) hang around your neck to run deployed code. The idea being that, if you want runtime features, you can bring Mirah modules in per your own decision, but if you want to fit a Mirah program on a micro-controller that can run Java bytecode (or Dalvik cough), you should be able to by forgoing some of those features that require large runtime libraries.

The Mirah site can be found at http://www.mirah.org, and the official Mirah ‘master’ repo is available at github: http://github.com/mirah/mirah. Feel free to checkout and follow along, although one last disclaimer - the code is changing quickly, so my articles are bound to fall out of the times.

I’d suggest before proceeding you familiarize yourself with the language syntax - I don’t plan to stop along the way.

A Background on Type Inference

Most JVM language replacements that are garnering attention right now in one way or another avoid explicit typing in the syntax to some degree. Languages that are compiled to normal byte-code with some degree of implicit typing, must involve some form of type inference. This is the process of statically analyzing code to determine the runtime types the code is using by inferring from the use of variables and parameters. Statically compiled languages on the VM must do this, because Java bytecode (and the VM) expects to work with types - and if the compiler can’t figure it out, it can’t compile the bytecode.

Consider this Java statement:

HashMap<String,String> myMap = new HashMap<String,String>();

There is really no reason you need to define the left-hand side (the declaration) so explicitly, considering that the right-hand side (the assignment) has already told you exactly what the variable is. Surely this should be sufficient:

var myMap = new HashMap<String,String>();

Anyone familiar with C# will likely recognize this syntax convenience. Of course, this is simple example, because you only have to examine this one line to infer the variable type. Things get much more complex when there are control structures, methods, and other language features in the way.

That being said, type inferencing is a well-tread path - it’s certainly not unique to JVM languages; far from it. There are different levels of type inference, with the most complete often using something like Hindley-Milner to deduce types recursively (excellent description of Hindley-Milner by Daniel Spiewak on his blog).

Mirah’s Type Inferencing

As it stands today, Mirah currently implements a variant of type inference somewhere between true “local” type inference, and fully recursive type inference like Hindley-Milner. Mirah’s inference uses a multi-pass infer process, where the first phase does simple local inference (or line-by-line inference), and then subsequent passes are made, looking for new type resolutions from those higher constructs. For example, consider these two Mirah methods:

def method_a()
  return method_b(5) + method_b(6)
end

def method_b(x:int)
  return x * -1
end

In this case, ‘method_a’ is obviously dependent upon ‘method_b’ - but if ‘method_a’ is inferred first, it will have no way to know what it’s return type is, because method_b hasn’t been inferred yet. In this case, ‘method_a’ is ‘deferred’ for a later inference pass. Shortly thereafter, ‘method_b’ will be processed, and since it can be completely analyzed through local inference, it will resolve to return an int. At that point, method_a can look at the two invocations that are involved in the return statement, and can in turn determine that it should also return an int.

The Algorithm

From an implementation standpoint, Mirah does this inference by utilizing the ASTs generated from the source. Each AST knows individually how to infer itself based on its recursive contents - this is something we’ll investigate in more detail shortly.

Mirah defines a namespace and class called Typer that is used to orchestrate this entire process. The Typer is asked to analyze each AST tree parsed by Mirah individually, and then to iteratively resolve:

typer = Typer.new
asts.each { |ast| typer.infer(ast) }
typer.resolve

The infer method for an individual AST node is pretty straightforward:

class Typer
  def infer(node)
    node.infer(self)
    # error handling business
  end
end

Notice that the typer passes itself into the node - this allows the nodes to callback into the typer for a variety of reasons. For example, each node has to decide for itself whether or not it has enough information to infer. If it doesn’t, it will tell the typer that it needs to be ‘deferred’, meaning it doesn’t yet have enough information. All this effectively does is record the node for later:

class Typer
  def defer(node)
    @deferred_nodes << node
  end
end

So the typer calls infer on the top level AST node, at which point the AST hierarchy will recurse, inferring and deferring nodes as appropriate. After the first recursive inference pass, the typer is then asked to resolve AST nodes iteratively until all nodes are inferred, or until no progress is made:

class Typer
  def resolve
    old_len = @deferred_nodes.length
    while true
      @deferred_nodes.each do |node|
        type = infer(node)
        if type != nil
          @deferred_nodes.remove(node)
        end
      end
    
      if @deferred_nodes.length == 0
        break
      elsif old_len == @deferred_nodes.length
        raise # can't infer error!
      end
    end
  end
end

AST Working Together

Understanding the concept of the AST recursively inferring is the key component to understanding the typer. Consider, for example, the statement x = method_b(5) - this is represented by a tree of AST nodes. For those of you with experience in parsers, or experience with my previous JRuby articles, it probably won’t be too hard to derive the types of nodes involved - it’s basically this:

LocalDeclaration
|
.-- LocalAssignment (type_node)
    |
    .-- FunctionalCall (value)
        |
        .-- Fixnum (parameters)
            |
            .-- "5" (literal)

The idea is that the declaration will ask the assignment, which will in turn ask the call being made with the parameter types in play, and will then return the type of the call return type. Here is a sketch of the various infer methods for these nodes:

class LocalDeclaration
  def infer(typer)
    type = @type_node.infer(typer)  #type_node is the local assignment
    if(!type)
      typer.defer(self)
    end
    return type
  end
end

class LocalAssignment
  def infer(typer)
    type = @value.infer(typer) #value is the "functional" call.
    if(!type)
      typer.defer(self)
    end
    return type
  end
end

class FunctionalCall
  def infer(typer)
    @parameters.each { |param| param.infer(typer) }
    if #all parameters inferred, and method with params and scope is known
      return typer.method_type(@method_name, method_scope, @parameters)
    else
       typer.defer(self)
       return nil
    end
  end
end

class FixNum
  def infer(typer)
    return typer.fixnum_type(@literal) #literal is '5'
  end
end

A few things to note here:

• This is totally pseudo code - the actual code has all kinds of branches for caching and other good bits.</li>
• The one literal we have, Fixnum, calls back into the typer to get the actual fixnum type - we’ll see this come in to play momentarily.
• The typer has the ability to look up a method type by a signature - when methods are scanned during type inference, they record themselves in the typer for other nodes, like this one, to use when inferring since they are one case of node “hopping”, where one AST can be linked to another by reference.
• We’re dodging how the functional call determines things like ‘method scope’ for now.

Resolving Literals

As noted above, the Fixnum node is asking the typer to give it back a fixnum type. This is done for all of the literal types. It’s done this way so that the platform implementation (in this particular case, Java) can plug in a particular type. So in this particular case, the Java implementation, in the JVM::Types module, provides a FixnumLiteral that looks at the provided value, and determines where in the hierarchy it belongs (for you Java folks, that’s byte, short, int, long, etc). When asked to actually compile, these AST nodes actually know how to generate the ultra-fast JVM bytecode-ops for primitives.

Type Annotations

As seen in one of the snippets above, Mirah supports type definitions for places where typing is either required (due to a lack of inference) or desired (widening a type, for example). Forgoing the fact this is a contrived implementation for a moment, consider this method:

import java.util.Map
import java.util.HashMap
class SomeClass 
  def singleton_map(a:string, b:string):Map
    map = HashMap.new
    map.put(a,b)
    return map  
  end
end

Here we are declaring both variable types so we can control inputs, and then we are declaring the return type. The reason you might want to declare a return type like this is so that the compiled method doesn’t expose too narrow of an implementation. Remember, we’re compiling to Java class files here - so if the compiled type inferred that the method returned a HashMap, that is a contraint we may never be able to change in the future. By changing it to ‘Map’, we can adjust the API like we would in the Java world to avoid tying ourselves to an implementation. To see this in action, here’s the output from mirahc when asked to generate Java code for this with and without the return type:

// With:
public class SomeClass extends java.lang.Object {
  public java.util.Map singleton_map(java.lang.String a, java.lang.String b) {
    java.util.HashMap map = new java.util.HashMap();
    map.put(a, b);
    return map;
  }
}

// Without:
public class SomeClass extends java.lang.Object {
  public java.util.HashMap singleton_map(java.lang.String a, java.lang.String b) {
    java.util.HashMap map = new java.util.HashMap();
    map.put(a, b);
    return map;
  }
}

Individual AST nodes know about these definitions (sometimes known as forced types), and will respect those over the corresponding inferred types. That’s not to say that it will just take them for granted; the type inference still occurs. In the example above, the method body is still inferred to ensure it returns a type that can be widened to ‘java.util.Map’ - otherwise the code will cause runtime errors in the VM. Here’s a snippet of the method definition AST analysis:

class MethodDefinition
  def infer(typer)
    forced_type = @return_type
    inferred_type = @body.infer(typer)
    actual_type = if forced_type.nil?
      inferred_type
    else
      forced_type
    end

    if !actual_type.is_parent(inferred_type)
      raise "inference error"
    end
    return actual_type
  end
end

The return_type field will be set by the parser if provided, and takes precedent so long as it’s still able to be used in place of the actual inferred type of the method body.

Uncovered Topics

So this was a quick spin through Mirah-land, but even for the inference engine, a lot was left on the table if you’d like to explore from here:

• Finding “native” types (in this case, calls into and returning Java types)
• Tracking class/method scope when inferring
• Inferring against intrinsics (such as ’+’, and ‘||’)
• Dealing with multi-node inference - several nodes, like ‘MethodDefinition’ are expected to infer several parts, including arguments, return type, throws types, etc. This increases the complexity of the implementation, but doesn’t have much impact on concept.
• Superclasses, invocation of ‘super’, overriding, overloading, etc.
• Framework vs. Implementation (i.e. JVM) Responsibilities

Stay tuned as the Mirah story unfolds!