Blake Caldwell: /dev/blog

Just for Fun: Hash Table Implementation in C

2015-01-27T00:00:00+00:00

Hash tables are cool. Like many developers, I used them for years without giving much thought to how they actually work. Just for fun, I decided to look into it - and while I was at it, brush up on C, which I hadn’t spent much time with since my first internship years ago.

TLDR: Take a look at the code on GitHub

Example: Hash Tables in Go

Hash tables (also known as “hash maps”, or “maps”) are so useful that they’re a built-in type in the arguably minimalist Go programming language. They allow you to create a simple lookup with a key/value pairing.

For example, if you forget which Wiggle wears which color, you could create a map of color (key) to Wiggle name (value), then refer to them by color through the map (try it in the Go Playground):

// map of color -> wiggle (don't judge.)
wiggle := make(map[string]string)
wiggle["purple"] = "Jeff"
wiggle["red"] = "Murray"
wiggle["blue"] = "Anthony"
wiggle["yellow"] = "Greg"

fmt.Printf("Purple: %s\n", wiggle["purple"])
fmt.Printf("Red: %s\n", wiggle["red"])
fmt.Printf("Blue: %s\n", wiggle["blue"])
fmt.Printf("Yellow: %s\n", wiggle["yellow"])

What are Hash Tables Doing?

Conceptually, hash tables are pretty simple. Under the hood, a hash table has a bunch of buckets for its values. The hash table knows in which bucket to find a value by its key, so it can quickly find anything it’s looking for. It’s much like how you’d keep track of your old baseball cards in boxes. You have a system - in this case, a box per year. You have 50 boxes, but when you’re looking for a specific card, you jump right to the correct box. Once you open that box, you rummage through it until you find the right card. As the number of buckets increases, hash table lookups approach constant time, O(1).

But… How Do They Work?

A hash table references a fixed number of buckets which can be represented as an array of simple linked lists. As we give the hash table a value to store, the key is fed through a a hashing algorithm which outputs a long integer called that key’s “hash code”. We mod that hash code by the number of buckets to figure out which bucket to use, then add the key and value to the end of the linked list in that bucket, creating the list if it doesn’t yet exist.

For example… Say you have 10 buckets with indexes 0 through 9, and a key with hash code equal to 223. 223 mod 10”> is 3, so we’ll append the key/value to the linked list in bucket with index 3. If you had 1,000,000 buckets, then you’d append the key/value to the linked list in bucket with index 223, since 223 mod 1000000 is 223.

When you search for a value in a hash table by key, the same hashing algorithm is used on the key to figure out which bucket to look in. That bucket’s linked list is traversed until the key is found, using an equality algorithm.

Java: hashCode() and equals()

If you’ve worked with Java, you’ve probably implemented hashCode() a bunch of times, or more likely, copied and pasted from somewhere. You’ve no doubt heard that it’s important to implement it careflly, but your program worked just fine with whatever you implemented.

How are these methods used in hash tables, and why are they important? Great questions! If you’re using one of your custom types for a hash table’s key, then your hashCode() method is used to determine which bucket to look in. Once the bucket is found, the match is determined with your equals() method, given the input key and keys in the bucket’s list.

A poor implementation of hashCode() returns the same value for every input, reducing a hash table to a single bucket: a linked list. We’d lose all the performance benefits we were looking for with this data structure. Lookups go from constant time (O(1)) to linear time (O(n)). Implementing either improperly returns invalid results. You could store something in a hash table with a key, then get the wrong value, or no value at all when you try to retrieve it with the same key.

Hash Table Implementation in C

I suppose it’s a little late in the post to finally get to my implementation, but without an understanding of how a hash table works, the code is just a bunch of marks on your screen. In my implementation, both the keys and values are strings, but it wouldn’t be too much work to make it more flexible.

My two custom types are the hashTable and the linked list that represents each bucket:

// linked list
struct hLinkedList
{
    char *key;
    char *value;
    struct hLinkedList *next;
};

// hashtable
struct hashTable
{
    unsigned int size;
    struct hLinkedList **lists;
};

Don’t let struct hLinkedList **lists; scare ya - it’s just an array that’s sized and allocated later, when we determine how many buckets we need.

Here’s my hashing function:

int hashCode(char *str)
{
    int hc;

    hc = 0;
    while('\0' != *str)
    {
        // for each character, multiply the current hashcode by 31 and add the character's ascii value
        // multiply by 31 is the same as left shift by 5 and subtract value
        hc = hc << 5;
        hc = hc - hc + *str;

        str++;
    }
    return(hc);
}

This uses the traditional multiplication by 31 scheme, which, by being prime, helps protect against losing information if the multiplication overflows.

Since we’re dealing with string functions, we use strcmp for the equality algorithm.

With my comments, and an understanding of C, the rest of the code should be fairly straightforward.

Demo

As described in README.md:

Compile and execute the binary to run the demo use case in main.c:

gcc *.c
./a.out

You should see:

Adding 'hello'=>'world', 'color'=>'blue' and printing:
-----
hello -> world
color -> blue


Changing 'hello' value to 'goodbye', then printing:
-----
hello -> goodbye
color -> blue


Removing 'hello' and printing:
-----
color -> blue


Removing 'color' and printing:
-----

Read My Codez!

Take a look at the source code on GitHub! Try modifying it to use a different type for either the keys or values.

Have your own fun!

JSON Encoding in Go: Dealing with Sensitive Fields

2015-01-20T00:00:00+00:00

JSON marshalling in Go is pretty straight-forward, but sometimes your structs contain sensitive information that you’d like to keep out of your public JSON API. Fortunately, there are a few good solutions that don’t require you to manually copy every field from one struct type to another.

Let’s start with our basic Person struct:

// Person struct that includes all fields in JSON
type Person struct {
	FirstName string
	LastName  string
	AuthToken string
}

The simplest way to prevent exposing AuthToken via JSON is with the json:"-" tag, which tells the json to always ignore this field. Let’s call this SafePerson, because you never have to worry about exposing AuthToken via JSON:

// SafePerson omits AuthToken in JSON
type SafePerson struct {
	FirstName string
	LastName  string
	AuthToken string `json:"-"`
}

This works really well, until you need to include the field some of the time, like when showing someone their own record. In that case, you could try the json:",omitempty" tag, which only includes the field if it has a value. It’d be up to you to clear it out when it doesn’t belong in the JSON. This is PrettySafePerson, because it’s safe if you’re careful:

// PrettySafePerson omits AuthToken if it doesn't have a value
type PrettySafePerson struct {
	FirstName string
	LastName  string
	AuthToken string `json:",omitempty"`
}

This is great, but… here’s the thing. That one time you forget to clear an AuthToken for someone other than the Person that it represents might give you quite the headache. I’d rather err on the side of safety, where forgetting something means not showing data that I meant to.

Here’s where we can take advantage of Go’s type embedding. By embedding a Person inside another struct, we borrow all of the Person’s fields, and can override some without affecting the Person. We’ll build our API with this pattern, which always omit sensitive fields unless told otherwise.

// PublicPerson decorates a Person, hiding AuthToken by default
type PublicPerson struct {
	*Person
	AuthToken string `json:",omitempty"`
}

// IncludeAuthToken unhides the Person's AuthToken
func (p *PublicPerson) IncludeAuthToken() {
	p.AuthToken = p.Person.AuthToken
}

PublicPerson’s AuthToken field overrides the embedded Person.AuthToken, and because of the json:",omitempty" key, it’ll be hidden from JSON unless you set it. Person.AuthToken still has the original value, you can include it in the JSON by calling IncludeAuthToken().

Try it out in the Go Playground

View Source on Github

Solving a 2014 Google I/O Secret Invite Puzzle

2014-04-23T00:00:00+00:00

I didn’t win the Google I/O ticket lottery this year, but thought I’d try to find and solve one of the secret puzzles Google was hiding, to get a chance to buy a reserved ticket.

I noticed that the Google Developers page header contained the text “I/O”, with different colors for each of the letters. Refreshing the page changed their colors, and occasionally removed them from the page. Looking at the source code, I found this:

<span style="color: #386834">I</span>/<span style="color: #317368">O</span>
<!-- Still need a hint? http://goo.gl/Eypmp -->
</li><!-- 110101 110010 110001 110011 110100 110000  -->

You might as well check out the hint url before reading on. Yep, it got me too. But… it turns out it is a hint.

The blocks of numbers in the comments on the last line were clearly binary, so I converted them to integers: 5,2,1,3,4,0. I refreshed the page several times, printing out lots of values for the hex color of the “I” and “O”, and with the resulting binary->integer conversions. I didn’t see any real pattern in the hex color values, but did notice that each of the binary->integer conversions always had exactly one of each 0,1,2,3,4,5 - this looks like a series of indexes.

Going back to our hint, I realized that the goal is to come up with the 6-character code to use as a Google shortened URL. Rather than 6 characters, it appears that we have 12 and a series of 6 indexes, but really, those color codes each have 3 hex components:

0x38, 0x68, 0x34, 0x31, 0x73, 0x68

Convert these to decimal:

56, 104, 52, 49, 115, 104

And now, convert them from decimal to ASCII characters:

8, h, 4, 1, s, h

Let’s apply the indexes (5,2,1,3,4,0) by rearranging these letters so that the 5th 0-based index character is first, then the 2nd, 1st, 3rd, 4th, and 0th:

h4h1s8

Prefix that code with the Google URL-Shortening domain, and we have:

http://goo.gl/h4h1s8

Success! Well, sort of. By the time I solved this, all of the codes seemed to be taken. Of hundreds of codes generated, only a few worked. I’m not sure if some random ones were thrown in, or if I’m missing another piece to the puzzle. In any case, the shortened link redirects you to a fun console-based game, reminiscent of the old terminal-based Zork and Hitchhiker’s Guide to the Galaxy games, but with color and simple animations.

At the time of this writing, this game link still works, so have a go at it. Take a look at my Python code that generates URLs by refreshing the Google Developers page and calculating the secret shortened URL.

TLDR: Game Link, Python Code

Here’s a screenshot with all of the different options selected.

Java: Performance Testing Hibernate Query Approaches

2013-11-10T00:00:00+00:00

I’ve known entities are expensive, but wanted to see for myself, so I built this test project to run some benchmarks. The tests aren’t complete - just a simple query with no joins, but with a lot of data. The point was to see how much overhead is introduced after we have the query results.

About the Project

This is a simple Maven Spring project that creates an in-memory HSQLDB database, populates it 500,000 records, and then uses several Hibernate query strategies to fetch every one, and report on their average execution times.

Approaches Tested

Using a JpaRepository interface’s findAll method to return a list of attached Hibernate entities.
Using Hibernate’s StatelessSession interface to return a list of detached Hibernate entities.
Selecting the specific fields of the entity, using Hibernate to return a simple List<Object[]>, and then manually converting that list to a list of detached entities (as DTOs, basically).
Selecting the specific fields of the entity, then using Hibernate’s AliasToBeanResultTransformer to build a list of detached entities (as DTOs, basically).

Changing Execution Parameters

By default, the database is loaded with 500,000 records, and each test is repeated in its own transaction 10 times. You can change both of these values in src/main/resources/application.properties.

Running Tests

This big of a database does take up over 256MB of memory, so you might have to increase your heap space. If you run the tests from Maven, you should be fine, since I increase it in the plugin’s settings.

Download the sample project and run the following command from inside its directory:

mvn clean test

The test might take several minutes to run. At the end, the test will output the results.

My Results

The results are listed slowest to fastest:

---------------------------
Testing JpaRepository query
Total # of runs: 10
JpaRepository avg time: 1073.5ms

---------------------------
Testing stateless session query
Total # of runs: 10
Stateless Session avg time: 818.5ms

---------------------------
Testing RowData query
Total # of runs: 10
RowData avg time: 317.7ms

---------------------------
Testing ResultTransformer query
Total # of runs: 10
ResultTransformer avg time: 311.9ms

The individual times will vary on different systems - the relative performance is what’s important.

The StatelessSession query was a little more efficient than returning attached entities, but still pretty slow for this big query. The AliasToBeanResultTransformer and my custom List<Object[]> -> DTO approaches tied as the best performers. I was hoping for this result, but worried that the reflective nature of AliasToBeanResultTransformer might have introduced some overhead. It did not.

Problems? Let me know!

I tried being as careful as I could with these tests:

took the average of several test runs
turned off Hibernate’s second-level cache
turned off Hibernate’s query cache
cleared the entity manager before each run
ran each test in its own transaction
ignored the first query in the transaction as to avoid any initial performance hit from opening it

I encourage you to download the project, take a look at the code, and try it out for yourself. If you see any issues with my methodology, please let me know, and I’ll correct for it.

Java: Exercising Caution With Hibernate Entities

2013-11-08T00:00:00+00:00

I heavily rely on the Hibernate framework on all of my database-driven Java projects. It’s a full-featured cross-database ORM framework capable of managing your database schema, persisting your entities to the database, populating entities from the database, caching queries, caching entities, registering entities for lifecycle events, indexing them in a search index, and just about everything else you could ask of an ORM.

When you fetch an entity from Hibernate, it remains attached to your EntityManager for the duration of that transaction. The EntityManager is responsible for all of the magic - it watches the entity for changes, persisting it and calling lifecycle methods when appropriate, makes sure to return the same instance of an entity for multiple queries to the same record, builds and executes additional queries if you access properties that point to associations in the database, and of course much more.

Take a look at my hibernate-perf-test sample project to see the relative performance of different Hibernate query strategies.

Entities are Expensive!

Entities are convenient, but if you don’t understand what they’re doing, you can get yourself into trouble. It all boils down to the fact that an entity’s getter method may run several more queries, so long as the entity is still attached to the EntityManager. A developer can be excused at first, because we’re used to getters and setters containing little to no logic besides accessing a private member variable. Hibernate is an amazing framework, but its greatest strength: being easy to use, becomes a liability: it’s too easy to use it to thrash your database.

The most common and expensive errors that I see are due to:

Accidental “eager” wiring of associated entities

When you load a Customer that has a list of Orders that are wired “eagerly”, Hibernate will build and execute a query to fetch all of those Orders, even if the code never accesses that list. The Orders can have their own eager associations, which compounds this problem. This becomes performance-crippling when your User table is eagerly self-referencing, and just about every query loads up your entire database. This is the sort of issue you might not notice during development, with 10 records in your database, but believe me, it shows itself in production.

Too many queries by accessing an association while looping over entities

When you’re displaying a table of 20 User records, and each one needs the name of their Organization, the easiest path for that developer is to loop over the list of entities and access the “organization” property on each User. This is intuitive, and makes sense with how we think about objects - you have a User, the User has an Organization, and the Organization has a name. However, with Hibernate, you need to understand that Organization isn’t loaded until you access it. By fetching each User’s Organization this way, you’re producing at least 20 more queries. Now, imagine if the user chooses a table size of 50 rows, or if Organization had some eagerly-loading associations to surprise you with (like another User record!). You’ve just killed your action.

This comes up a lot when a developer tries to do the right thing and adds a lot of logging. Even if we don’t need the Organization for the data table we’re building, the developer might think that someone that reads the logs might want to see each User’s organization. Those logs just became very expensive, and nobody will notice until your users are complaining about page load times in production.

Yes, there are better ways to use entities

If you’re familiar with the framework, you’re probably shaking your head, mumbling something about “fetch joins, closing the transaction before building your view, and other strategies for more efficiently fetching entities. My point is that as much as I love entities, they’re performance time bombs. It takes one careless moment, or one developer that doesn’t know Hibernate as well as you do, to touch the wrong property and cause a big issue to ripple through your system.

Querying Carefully

Rather than maintain constant vigilance and make sure that every member of your team has read all of the documentation, I prefer to tread lightly with Hibernate. I fully embrace it for helping me generate my schema, for updating the database in an infrequent-write system, and for the query language that bridges different databases.

There are several ways you can use Hibernate to query your database, from full-on magic entities to getting your hands dirty for better efficiency. In a system where reads are common and writes rare, my approach is typically to use as little “magic” as I can for my read-only queries. I don’t fetch attached entities from the database, but rather, select the specific fields that I need, and use the results to build detached data transfer objects (DTOs).

Aside from avoiding the big issues above, this also forces a developer to think more in terms of SQL, and where their data is coming from - it’s more explicit, and thus, more understandable. If you have a “dumb” User DTO, and want the name of that User’s Organization, you’re going to have to either run a query on each User, query them in bulk and then join the two sets of data, or add the Organization name to the original User query. It’s immediately obvious that the first option is ridiculous, and that the second one is annoying to write. The last one takes the least effort, and makes sense when you’re thinking in terms of SQL and database access.

Here’s another point to consider. Since it’s typically considered poor form to return your entities to the client or view, then why not avoid the entity-to-DTO conversion and generate the DTOs in the first place?

Coming Up: Performance Testing Different Query Approaches

There are several ways to use Hibernate to fetch data from your database, and no shortage of conversations online about the performance of these different approaches, as well as official documentation on the subject.

In my next post, I’ll walk you through a sample project that I wrote to test out different query strategies. If you’re interested, take a look for yourself.

Asserting Exceptions With JUnit Rules: IsEqual Matcher

2013-10-30T00:00:00+00:00

In my first post on asserting exceptions with JUint, I showed how to test that a specific type of exception is thrown with expected substrings in the error message. In my second post, I showed how we can write a custom [Matcher] to inspect the contents of the exception. In this post, I’ll show you how to take advantage of the stock IsEqual matcher to accomplish the same task, but with less work.

IsEqual Matcher

This Matcher is straightforward - it evaluates whether two objects are equal by calling equals(Object) on one of the objects that isn’t null, passing in the other. So, to use it with our custom exception, we’ll need to make sure that our equals(Object) method correctly evaluates two of its instances.

The default behavior of equals(Object obj) is to check if two objects are the same instance:

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

This won’t help us here, because we’ll be comparing exceptions thrown in our code with one we instantiated in our unit test. We’re going to have to implement equals(Object) ourselves.

Implementing `equals(Object)`

Here’s my simple custom exception:

/**
 * Error Code Exception - stores the error code that was generated
 * when this exception was thrown.
 */
public class ErrorCodeException extends RuntimeException
{
    private static final long serialVersionUID = 1L;

    /**
     * The error code that triggered the exception.
     */
    private int errorCode;

    /**
     * Constructor.
     * 
     * @param errorCode
     *            the error code that triggered the exception
     */
    public ErrorCodeException(int errorCode)
    {
        this.errorCode = errorCode;
    }

    /**
     * Get the error code that triggered the exception.
     */
    public int getErrorCode()
    {
        return errorCode;
    }
}

You have to be careful when implementing either equals(Object) or hashCode(). The rule is that if you implement either of these methods, then you need to implement both. Two objects that are equal must have the same hash code. If they don’t, and you try to add two distinct, but equal instances of a class to a Map, they’d both be accepted. This is because internally, the Map stores the items in ‘buckets’ based on their hash codes, and then only has to check equality within a bucket. If two objects have different hash codes, then they won’t be compared to each other.

Your IDE should have the ability to generate what we need here. If you’re using Eclipse (I recommend the STS version, right-click in the source file, select “Source”, and the select “Generate hashCode() and equals()”.

After selecting that option, choose which private members will be used in the two methods. I recommend selecting “‘Use blocks in ‘if’ statements” in order to help wrong code look wrong, should someone modify these methods down the road.

Here’s our final ErrorCodeException class with the newly generated code:

package org.blakecaldwell.tests.junitrules;

/**
 * error code exception - stores the error code that was generated
 * when this exception was thrown.
 */
public class errorcodeexception extends runtimeexception
{
    private static final long serialversionuid = 1l;

    /**
     * the error code that triggered the exception.
     */
    private int errorcode;

    /**
     * constructor.
     * 
     * @param errorcode
     *            the error code that triggered the exception
     */
    public errorcodeexception(int errorcode)
    {
        this.errorcode = errorcode;
    }

    /**
     * get the error code that triggered the exception.
     */
    public int geterrorcode()
    {
        return errorcode;
    }

    /**
     * (non-javadoc)
     * 
     * @see java.lang.object#hashcode()
     */
    @override
    public int hashcode()
    {
        final int prime = 31;
        int result = 1;
        result = prime * result + errorcode;
        return result;
    }

    /**
     * (non-javadoc)
     * 
     * @see java.lang.object#equals(java.lang.object)
     */
    @override
    public boolean equals(object obj)
    {
        if (this == obj)
        {
            return true;
        }
        if (obj == null)
        {
            return false;
        }
        if (getclass() != obj.getclass())
        {
            return false;
        }
        errorcodeexception other = (errorcodeexception) obj;
        if (errorcode != other.errorcode)
        {
            return false;
        }
        return true;
    }
}

Verifying `_equals(Object)` and `hashCode()`

Even though we generated this code, we still need to test it. Here’s the test fixture for ErrorCodeException:

package org.blakecaldwell.tests.junitrules;

import org.junit.Assert;
import org.junit.Test;

/**
 * Test fixture for ErrorCodeException.
 */
public class ErrorCodeExceptionTest
{
    /**
     * Test getErrorCode().
     */
    @Test
    public void testGetErrorCode()
    {
        ErrorCodeException exception = new ErrorCodeException(500);

        Assert.assertEquals(500, exception.getErrorCode());
    }

    /**
     * Test equals(Object) evaluates true for two equal instances.
     */
    @Test
    public void testEqualsWhenEqual()
    {
        ErrorCodeException exception1 = new ErrorCodeException(500);
        ErrorCodeException exception2 = new ErrorCodeException(500);

        Assert.assertTrue(exception1.equals(exception2));

        // another way to test
        Assert.assertEquals(exception1, exception2);
    }

    /**
     * Test equals(Object) evaluates as false for two unequal
     * instances.
     */
    @Test
    public void testEqualsWhenNotEqual()
    {
        ErrorCodeException exception1 = new ErrorCodeException(500);
        ErrorCodeException exception2 = new ErrorCodeException(501);

        Assert.assertFalse(exception1.equals(exception2));

        // another way to test
        Assert.assertNotEquals(exception1, exception2);
    }

    /**
     * Test equals(Object) evaluates as false when we pass in null.
     */
    @Test
    public void testEqualsWhenNull()
    {
        ErrorCodeException exception1 = new ErrorCodeException(500);

        Assert.assertFalse(exception1.equals(null));

        // another way to test
        Assert.assertNotEquals(exception1, null);
    }

    /**
     * Test that two equal objects have the same hash code. Note that
     * two different objects don't need to have different hash codes.
     */
    @Test
    public void testHashCodeForTwoEqualObjects()
    {
        ErrorCodeException exception1 = new ErrorCodeException(500);
        ErrorCodeException exception2 = new ErrorCodeException(500);

        // sanity check - make sure they're equal
        Assert.assertEquals(exception1, exception2);

        // make sure they have the same hash code
        Assert.assertEquals(exception1.hashCode(), exception2.hashCode());
    }
}

Using the IsEqual Matcher In Our Unit Tests

Now that we’ve implemented equals(Object) and hashCode() for our custom exception, we can use the IsEqual Matcher to setup an expectation for a specific exception.

package org.blakecaldwell.tests.junitrules;

import org.hamcrest.core.IsEqual;
import org.junit.Assert;
import org.junit.Rule;
import org.junit.Test;
import org.junit.rules.ExpectedException;

/**
 * Test fixture to demonstrate JUnit's ExpectedException @Rule with an
 * IsEqual matcher.
 */
public class ExpectedExceptionRuleIsEqualMatcherTest
{
    /**
     * ExpectedException must be public.
     */
    @Rule
    public ExpectedException exception = ExpectedException.none();

    /**
     * Assert that we're throwing the exact exception that we're
     * expecting by using an IsEqual Matcher.
     */
    @Test
    public void testErrorCode500UsingIsEqualMatcher()
    {
        ErrorCodeException expectedException = new ErrorCodeException(500);

        exception.expect(new IsEqual&lt;ErrorCodeException&gt;(expectedException));

        // Run your code that you expect will throw an
        // ErrorCodeException with error code 500. If this exception
        // is equal to our expectedException above, this test will
        // pass.
        throw new ErrorCodeException(500);
    }

    /**
     * Here's the old way of asserting a specific exception. Yuck!
     */
    @Test
    public void testErrorCode500WithoutJUnitRules()
    {
        ErrorCodeException exception = null;
        try
        {
            throw new ErrorCodeException(500);
        }
        catch (Exception ex)
        {
            exception = (ErrorCodeException) ex;
        }
        Assert.assertEquals(500, exception.getErrorCode());
    }
}

In the first test, I create an IsEqual Matcher with the exception that I want to compare the thrown exception to. No custom Matcher was required, and my custom exception is now more useful because of it.

In my second test, I include the ‘old way’ of checking exceptions to demonstrate how much easier and more readable exception tests are when using JUnit’s Rules feature.

Asserting Exceptions With JUnit Rules: Custom Matchers

2013-10-29T00:00:00+00:00

In my previous post, I demonstrated how to use JUnit’s Rules feature to assert expected assertions in your unit tests. In this post, I’ll show you how to write custom Matchers that will help give you more power when inspecting your exceptions.

Maven Dependencies

This demo uses the following Maven dependencies:

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.11</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.hamcrest</groupId>
    <artifactId>hamcrest-library</artifactId>
    <version>1.3</version>
</dependency>

Custom Exception

We’ll start with a custom exception which does little more than remember the error code at the time the exception was thrown.

/**
 * Error Code Exception - stores the error code that was generated
 * when this exception was thrown.
 */
public class ErrorCodeException extends RuntimeException
{
    private static final long serialVersionUID = 1L;

    /**
     * The error code that triggered the exception.
     */
    private int errorCode;

    /**
     * Constructor.
     * 
     * @param errorCode
     *            the error code that triggered the exception
     */
    public ErrorCodeException(int errorCode)
    {
        this.errorCode = errorCode;
    }

    /**
     * Get the error code that triggered the exception.
     */
    public int getErrorCode()
    {
        return errorCode;
    }
}

Our Exception Matcher

When we pass our Matcher to JUnit’s ExpectedException instance, we’re given a chance to match the exception itself, not the message. In this case, we’re going to write a Matcher that makes sure that the exception’s error code was as expected. We can only match on an instance of our _ ErrorCodeException_, so we’ll save some effort and extend TypeSafeMatcher.

From the documentation:

TypeSafeMatcher : Convenient base class for Matchers that require a non-null value of a specific type. This simply implements the null check, checks the type and then casts.

import org.hamcrest.Description;
import org.hamcrest.TypeSafeMatcher;

/**
 * ErrorCodeMatcher - matches when an ErrorCodeException has the same
 * error code as expected.
 */
public class ErrorCodeExceptionMatcher extends TypeSafeMatcher<ErrorCodeException>
{
    /**
     * The error code we're expecting.
     */
    private int expectedErrorCode;

    /**
     * Constructor.
     * 
     * @param expectedErrorCode
     *            the error code that we're expecting
     */
    public ErrorCodeExceptionMatcher(int expectedErrorCode)
    {
        this.expectedErrorCode = expectedErrorCode;
    }

    /**
     * Describe the error condition.
     */
    @Override
    public void describeTo(Description description)
    {
        description.appendText("Error code doesn't match");
    }

    /**
     * Test if the input exception matches the expected exception.
     */
    @Override
    protected boolean matchesSafely(ErrorCodeException exceptionToTest)
    {
        return exceptionToTest.getErrorCode() == this.expectedErrorCode;
    }

}

Example Tests With ExpectedException and Our Custom Matcher

With the components in place, let’s start testing. Of course, if you only have one or two error test cases, then a custom Matcher might take more work than it saves, but you end up with code that any developer should be able to read, which might reduce maintenance costs.

package org.blakecaldwell.tests.junitrules;

import org.junit.Rule;
import org.junit.Test;
import org.junit.rules.ExpectedException;

/**
 * Test fixture to demonstrate JUnit's ExpectedException @Rule with a
 * custom matcher.
 */
public class ExpectedExceptionRuleCustomMatcherTest
{
    /**
     * ExpectedException must be public.
     */
    @Rule
    public ExpectedException exception = ExpectedException.none();

    /**
     * Test exception error code 500 using our custom Matcher.
     */
    @Test
    public void testErrorCode500UsingMatcher()
    {
        exception.expect(new ErrorCodeMatcher(500));

        // Run your code that you expect will throw an
        // ErrorCodeException with
        // error code 500
        throw new ErrorCodeException(500);
    }

    /**
     * Test exception error code 404 using our custom Matcher.
     */
    @Test
    public void testErrorCodeUsingMatcher()
    {
        exception.expect(new ErrorCodeMatcher(404));

        // Run your code that you expect will throw an
        // ErrorCodeException with
        // error code 404
        throw new ErrorCodeException(404);
    }
}

Asserting Exceptions The Old Way

To demonstrate the benefits of using custom Matchers with JUnit’s ExcpectedException, here are the alternatives that you’re probably familiar with, with inline comments explaining why they’re not ideal.

package org.blakecaldwell.tests.junitrules;

import org.junit.Assert;
import org.junit.Test;

/**
 * Tests that demonstrate how to assert exceptions without
 * ExpectedException @Rule and custom Matchers.
 */
public class ExceptionAssertingOldWayTest
{
    /**
     * Test that an ErrorCodeException was thrown with the "expected"
     * parameter. The limitation here is that you can only test the
     * type of Exception, not its parameters or the message.
     */
    @Test(expected = ErrorCodeException.class)
    public void testErrorCodeExceptionThrownOldWay1()
    {
        // Run your code that you expect will throw an
        // ErrorCodeException with
        // error code 500
        throw new ErrorCodeException(500);
    }

    /**
     * Test exception error code 404 by capturing the Exception and
     * inspecting it inside the catch.
     * 
     * Remarks: We have to make sure to assert failure after our code
     * was supposed to throw the exception, or we won't know if it
     * never does. This nuance makes this method error prone for
     * future modifications.
     */
    @Test
    public void testErrorCodeExceptionThrownOldWay2()
    {
        try
        {
            // The "A".equals("A") is here just for this demo to
      // prevent an "Unreachable code" warning in Eclipse, since
      // we're throwing the exception directly instead of
      // calling code that throws it.
            if ("A".equals("A"))
            {
                // Run your code that you expect will throw an
                // ErrorCodeException with error code 404
                throw new ErrorCodeException(404);
            }

            // if we've gotten to this point, then no Exception was
            // thrown
            Assert.fail("Test case failed: no exception thrown");
        }
        catch (Exception ex)
        {
            Assert.assertEquals(
                    "Expected 404 error code exception",
                    404,
                    ((ErrorCodeException) ex).getErrorCode());
        }
    }

   /**
    * Test exception error code 404 by capturing the Exception and
    * inspecting it outside the try/catch.
    * 
    * Remarks: This is safer than asserting inside the catch (as
    * above), since if the exception is never thrown, our assertion
    * won't be valid, but still is not a very elegant solution.
    */
    @Test
    public void testErrorCodeExceptionThrownOldWay3()
    {
        Exception caughtException = null;
        try
        {
            // Run your code that you expect will throw an
            // ErrorCodeException
            // with error code 404
            throw new ErrorCodeException(404);
        }
        catch (Exception ex)
        {
            caughtException = ex;
        }

        // if the exception was never thrown, or was thrown and is an
        // incorrect
        // type or wrong code, this will fail
        Assert.assertEquals(
                "Expected 404 error code exception",
                404,
                ((ErrorCodeException) caughtException).getErrorCode());
    }
}

Asserting Exception Messages With JUnit Rules

2013-10-28T00:00:00+00:00

If you’re not familiar with JUnit’s @Rule feature for asserting exceptions in your tests, then read on - you’re about to start using it.

Assert Exception Type

It’s very simple to assert that a given type of exception is thrown in a JUnit test case with the following:

public void testExceptionTypeIsThrown()
{
    throw new RuntimeException("Error!");
}

Assert Exception Message (The Old Way)

But, what if you want to be more specific, and check the message itself? I’ve always done the following:

/**
 * Test the exception message the old way.
 */
@Test
public void testExceptionMessageTheOldWay1()
{
    String message = null;
    try
    {
        throw new RuntimeException("Error!");
    }
    catch(Exception e)
    {
        message = e.getMessage();
    }
    Assert.assertEquals("Error!", message);
}

Heres’s another variant you’re probably familiar with:

/**
 * Test the exception message the old way.
 */
@Test
public void testExceptionMessageTheOldWay2()
{
    try
    {
        // this string test was necessary to avoid an "unreachable code" warning in Eclipse
        if ("A".equals("A"))
        {
            throw new RuntimeException("Error!");
        }
        Assert.fail("Exception was expected.");
    } catch (Exception e)
    {
        Assert.assertEquals("Error!", e.getMessage());
    }
}

Assert Exception Message With JUnit Rules

The above methods always felt like hacks. I recently came across JUnit’s @Rule feature, which saves tons of code and is much easier to read. You first define your public ExpectedException instance, and give it a @Rule annotation. Then, in each test case that wants to use it, you set what type of exception you’re expecting, and optionally a substring to look for in the exception message:

/**
 * Our expected exception rule. This must be public.
 */
@Rule
public ExpectedException exception = ExpectedException.none();

/**
 * Test the exception message with a single expectMessage substring match.
 */
@Test
public void testExceptionIsThrownFullText()
{
    exception.expect(RuntimeException.class);
    exception.expectMessage("Error!");

    throw new RuntimeException("Error!");
}

Since expectMessage is looking for substrings, you can use several of them to test more complicated exception messages:

/**
 * Our expected exception rule. This must be public.
 */
@Rule
public ExpectedException exception = ExpectedException.none();

/**
 * Test the exception message with multiple expectMessage substrings.
 */
@Test
public void testExceptionIsThrownMultipleSubstrings()
{
    exception.expect(RuntimeException.class);
    exception.expectMessage("Error: There was an issue processing ");
    exception.expectMessage(" of the notes.");

    throw new RuntimeException("Error: There was an issue processing 5 of the notes.");
}

More Advanced: Custom Matchers

In my next post, I’ll i describe how to implement a custom Matcher for more complicated Exception assertions.

Conditionally Run JUnit Integration Tests with Spring

2013-10-18T00:00:00+00:00

Ideally, your unit test suites require no external dependencies - those should be mocked out. However, sometimes you want extra assurance that your code works with live endpoints via integration tests.

For example, you might want to make sure that your code can successfully navigate your corporate proxy and firewall to make external web requests. For this, we’ll write tests that only run when a command line parameter is defined.

This demonstration assumes that you’re using Spring’s JUnit Runner and Maven for running your tests. The @IfProfileValue annotation will tell the test runner to only include this test suite if our configured ProfileValueSource returns “true” for “live-external-tests-enabled”.

package org.blakecaldwell;
import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.test.annotation.IfProfileValue;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

@RunWith(SpringJUnit4ClassRunner.class)
@IfProfileValue(name="live-external-tests-enabled", value="true")
public class IntegrationTest
{
    @Test
    public void testExternalConnection()
    {
        Assert.fail("testExternalConnection failed!");
    }
}

Let’s verify that this test suite is ignored by default with the maven command:

mvn test

You’ll see that you now have a skipped test:

Results:

Tests run: 1337, Failures: 0, Errors: 0, Skipped: 1

Now, try it again, but this time with our test included:

mvn test -Dlive-external-tests-enabled=true

You’ll now see that the test was run:

Results :

Tests in error: 
  testExternalConnection(org.blakecaldwell.IntegrationTest): Failed to load ApplicationContext

Tests run: 1337, Failures: 0, Errors: 1, Skipped: 0

The @IfProfileValue annotation can also be used above an individual test.

Object/Relational Mapping: Know Your Frameworks

2013-09-03T00:00:00+00:00

I’ve been working with Hibernate for several years now, yet I learn something new about it all the time. The more time I spend with the framework, the more concerned I am about how it will be used by developers new to it.

Mirko Novakovic Alois Reitbauer nails it in a post about O/R Mapping Anti-Patterns:

The simplicity of the entrance into the world of O/R mapping however gives a wrong impression of the complexity of these frameworks. Working with more complex applications you soon realize that you should know the details of framework implementation to be able to use them in the best possible way. In this article, we describe some common anti-patterns which may easily lead to performance problems.

This is an echo of Joel Spolsky’s warnings of the Law of Leaky Abstraction:

The law of leaky abstractions means that whenever somebody comes up with a wizzy new code-generation tool that is supposed to make us all ever-so-efficient, you hear a lot of people saying “learn how to do it manually first, then use the wizzy tool to save time.” Code generation tools which pretend to abstract out something, like all abstractions, leak, and the only way to deal with the leaks competently is to learn about how the abstractions work and what they are abstracting. So the abstractions save us time working, but they don’t save us time learning.

Don’t stop learning about a framework once you figure out how to use it - that’s only the beginning.

Java: Don't Rely on EntityManager.persist() for Immediate Insert

2013-09-03T00:00:00+00:00

I had always counted on EntityManager’s persist() method to immediately insert entities. I would rely on this when writing database integration tests - I’d persist some records, then test my DAO methods to find them.

On my current project, I decided to add a configuration option to allow me to run my datbase integration tests on my development Oracle database rather than my embedded HSQLDB test database - just for an extra sanity check. The tests that tried to persist() and then retrieve those new entities failed. Adding an entityManager.flush() method after the persist() invocations solved the issue.

…But why?

From en.wikibooks.org:

The EntityManager.persist() operation is used to insert a new object into the database. persist does not directly insert the object into the database, it just registers it as new in the persistence context (transaction). When the transaction is committed, or if the persistence context is flushed, then the object will be inserted into the database. If the object uses a generated Id, the Id will normally be assigned to the object when persist is called, so persist can also be used to have an object’s Id assigned. The one exception is if IDENTITY sequencing is used, in this case the Id is only assigned on commit or flush because the database will only assign the Id on INSERT. If the object does not use a generated Id, you should normally assign its Id before calling persist.

Here’s how I wire up my entities’ primary key:

@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;

For my embedded HSQLDB database, the generation strategy is GenerationType.IDENTIY, which relies on the database to generate an autoincrementing primary key for that row. This requires an insert, so the persist() immediately inserts in HSQLDB.

Oracle, on the other hand, uses a cross-table GenerationType.SEQUENCE @Id generator, which doesn’t require an insert, but the following SELECT:

select
  hibernate_sequence.nextval
from
  dual

This select is called immediately on persist() so that the EntityManager has an ID to assign the entity. That entity will only be inserted after a flush(), which is called automatically on transaction commit.

Long story short: If you’re relying on your entity existing in the database after your call to persist(), but before the transaction commits, then call flush() first. Leave a comment justifying it, as manually calling flush is largely considered an anti-pattern akin to invoking the garbage collector. Delayed flush() calls give Hibernate the chance to perform more performant bulk updates.

Builder Pattern Instead of Error-Prone Constructors

2013-08-30T00:00:00+00:00

When designing your classes, rather than following the path of the unreadable telescoping constructor, or leaving yourself open for bugs where the caller incorrectly passes a value into the wrong parameter because you have several of the same type, consider the following Builder pattern.

public class Person
{
  // required
  private String firstName;
  
  // required
  private String lastName;
  
  // optional
  private String url;

  // private constructor to defer responsibility to Builder.
  private Person()
  {
  }
  
  public String getFirstName()
  {
    return this.firstName;
  }
  
  public void setFirstName(final String firstName)
  {
    if(StringUtils.isBlank(firstName))
    {
      throw new IllegalArgumentException("Person.firstName must not be blank");
    }
    this.firstName = firstName;
  }

  public String getLastName()
  {
    return this.lastName;
  }

  public void setLastName(final String lastName)
  {
    if(StringUtils.isBlank(lastName))
    {
      throw new IllegalArgumentException("Person.lastName must not be blank");
    }
    this.lastName = lastName;
  }

  public String getUrl()
  {
    return this.url;
  }
  
  public void setUrl(final String url)
  {
    this.url = url;
  }

  // builder class to ensure that all required fields are set while avoiding clunky, "telescopic" constructors
  public static class Builder
  {
    private Person built;

    public Builder()
    {
      built = new Person();
    }

    public Builder setFirstName(final String firstName)
    {
      built.setFirstName(firstName);
      return this;
    }

    public Builder setLastName(final String lastName)
    {
      built.setLastName(lastName);
      return this;
    }

    public Person build()
    {
      if(built.firstName == null)
      {
        throw new IllegalStateException("Person.firstName is required");
      }
      if(built.lastName == null)
      {
        throw new IllegalStateException("Person.lastName is required");
      }
      return built;
    }
  }
}

Having a private constructor will prevent anyone but the Person’s Builder from instantiating a Person. The setters in the Builder return the Builder, which allows method chaining, providing a DSL-like self-documenting interface. The Builder’s build() method is responsible for making sure that all properties are set before returning the Person.

Of course, this is a simple example with only two fields, so the alternative isn’t exactly error prone:

Person blogger = new Person("Blake", "Caldwell");
blogger.setUrl("http://blakecaldwell.org");

But, once you add a few more required fields, the following makes your code easier to follow, while still ensuring all required fields are set.

Person blogger = new Person.Builder()
    .setFirstName("Blake")
    .setLastName("Caldwell")
    .build();
blogger.setUrl("http://blakecaldwell.org");

I first came across this pattern via a post by Petri Kainulainen. Check out his blog for great posts about Spring Data JPA and other topics.

Apache Camel: Powerful EIP Framework

2013-06-23T00:00:00+00:00

Pradeep Elankumaran gives a high-level overview of Apache Camel

From Apache Camel’s project page:

Apache Camel ™ is a versatile open-source integration framework based on known Enterprise Integration Patterns.

Camel empowers you to define routing and mediation rules in a variety of domain-specific languages, including a Java-based Fluent API, Spring or Blueprint XML Configuration files, and a Scala DSL. This means you get smart completion of routing rules in your IDE, whether in a Java, Scala or XML editor.

Apache Camel uses URIs to work directly with any kind of Transport or messaging model such as HTTP, ActiveMQ, JMS, JBI, SCA, MINA or CXF, as well as pluggable Components and Data Format options. Apache Camel is a small library with minimal dependencies for easy embedding in any Java application. Apache Camel lets you work with the same API regardless which kind of Transport is used - so learn the API once and you can interact with all the Components provided out-of-box.

Apache Camel provides support for Bean Binding and seamless integration with popular frameworks such as Spring, Blueprint and Guice. Camel also has extensive support for unit testing your routes.

Check out “What exactly is Apache Camel?” on StackOverflow for other devs’ descriptions.

PDF Emailer v2.1: Multiple Recipient Support

2013-06-07T00:00:00+00:00

PDF Emailer is a iOS utility app that lets you email PDF and Office documents from Safari using a customizable email template.

In version 2.1, you can now set multiple recipients in your template by separating them with spaces.

PDF Emailer v2.1 is (no longer) available for iPhone, iPad, and iPod Touch

Java: Copy/Paste-Safe Logger Creation

2013-03-07T00:00:00+00:00

We’ve all copied and pasted a Logger from one class to the other, forgetting to change the class name.

// WRONG
public class SomeNewClass
{
  // OOPS! I forgot to change the class name!
  private final Logger _logger = LoggerFactory.getLogger(SomeOtherClass.class);
  
  // …	
}

Here, use this smarter LoggerFactory which uses the stack trace to figure out what class you really mean. This is safe from copypasta laziness.

package org.blakecaldwell.logging;

import org.slf4j.Logger;

/**
 * Smart logger that uses reflection to figure out the logged class
 */
public final class ClassLoggerFactory
{
    /**
     * Disallow factory instances.
     */
    private ClassLoggerFactory()
    {
    }

    /**
     * Use the stack trace to determine the appropriate logger.
     * 
     * @return a logger for the direct caller's class.
     */
    public static Logger make()
    {
        Throwable t = new Throwable();
        StackTraceElement directCaller = t.getStackTrace()[1];
        return org.slf4j.LoggerFactory.getLogger(directCaller.getClassName());
    }
}

Then, to use this logger:

// CORRECT
public class SomeNewClass
{
    // No chance for screwing up anymore!
    private final Logger _logger = ClassLoggerFactory.make();

    // …	
}

Java: Embedding Spring Batch Admin Into An Existing Application

2013-03-06T00:00:00+00:00

For my current project, I need to share Spring beans between my front-end web servlets and the Spring Batch jobs that I’ll launch from Spring Batch Admin (SBA). This sounds straightforward - configure the SBA servlet to listen on /batch/*, and you should be good to go. However, of course it’s not that easy.

URL Path Mismatch

The first problem you run into is bad links in the menus, form posts that go nowhere, and missing CSS files. This is because SBA expects to be deployed on /, not /batch, or /myapp/batch which is where it will go if you deploy it inside another app. You can survive in this mode for the most part by correcting menu URLs after you click them, or use FireBug to change form actions before you submit them - for example, from /batch/files to /myapp/batch/files, but who wants to live like an animal?

Spring Batch Admin 1.2.1 to the Rescue

Spring Batch Admin version 1.2.1 adds the ability to set the base servlet path for all links and forms by overriding the “resourceService” bean. I’m sure there are several ways to successfully accomplish this, but here’s what worked for me.

pom.xml

Add the following repository:

<repository>
  <id>repository.springframework.maven.release</id>
  <name>Spring Framework Maven Release Repository</name>
  <url>http://maven.springframework.org/release</url>
</repository>

and the dependencies:

<dependency>
    <groupId>org.springframework.batch</groupId>
    <artifactId>spring-batch-admin-resources</artifactId>
    <version>1.2.1.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.batch</groupId>
    <artifactId>spring-batch-admin-manager</artifactId>
    <version>1.2.1.RELEASE</version>
</dependency>

web.xml

Configure the Batch Admin Servlet - notice contextConfigLocation:

<servlet>
  <servlet-name>Batch Admin Servlet</servlet-name>
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
  <init-param>
      <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/spring/batch-admin/batch-admin-context.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>Batch Admin Servlet</servlet-name>
    <url-pattern>/batch/*</url-pattern>
</servlet-mapping>

/WEB-INF/spring/batch-admin/batch-admin-context.xml

This is the context file that’s only used by SBA. Keep in mind that any beans defined in your root Spring context will also be available to the jobs that are launched by SBA.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

  <!-- Spring Batch Admin Context: Additional context for Spring Batch Admin -->
  <import resource="classpath*:/META-INF/spring/batch/servlet/resources/*.xml" />
  <import resource="classpath*:/META-INF/spring/batch/servlet/manager/*.xml" />
  <import resource="classpath*:/META-INF/spring/batch/servlet/override/*.xml" />
  <import resource="classpath*:/META-INF/spring/batch/bootstrap/**/*.xml" />
  <import resource="classpath*:/META-INF/spring/batch/override/**/*.xml" />

  <!-- For Spring Batch -->
  <bean id="resourceService"
    class="org.springframework.batch.admin.web.resources.DefaultResourceService">
    <property name="servletPath" value="/batch" />
  </bean>
</beans>

One Last Gotcha - /myapp/batch

The main “Home” link in the SBA action bar navigates to /myapp/batch. This doesn’t work the way I’ve wired it up, because the SBA servlet is configured to listen to /myapp/batch/, but not /myapp/batch. I tried adding another servlet-mapping to /batch, but the servlet won’t answer requests to it.

I’m sure there’s a better way to do this via config only - please tell me if you wouldn’t mind, but I opted for the more manual way, just so I could move on.

I wired up a servlet in my main web app to listen to /batch, and then have it redirect to /batch/.

web.xml - configuration for a servlet in my main app

Pay attention to the last servlet-mapping. This gives /myapp/batch over to Spring MVC for URL mapping.

<servlet>
  <servlet-name>appServlet</servlet-name>
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
  <init-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/spring/appServlet/servlet-context.xml</param-value>
  </init-param>
  <async-supported>true</async-supported>
  <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
  <servlet-name>appServlet</servlet-name>
  <url-pattern>/</url-pattern>
</servlet-mapping>

<!-- LOOK HERE -->
<servlet-mapping>
  <servlet-name>appServlet</servlet-name>
  <url-pattern>/batch</url-pattern>
</servlet-mapping>

HomeController.java

Here’s where I redirect /batch to /batch/. Again, I’m sure there’s a better way to do this (let me know!). Of course, for this specific code to work, you’ll need some dependencies such as spring-webmvc. The bottom line is that I’m just manually listening on /batch and redirecting to /batch/.

@Controller
public class HomeController
{
    /**
     * Redirect the url /batch to /batch/ for the Spring Batch Admin to pick it up.
     * 
     * @return redirect to /batch/
     */
    @RequestMapping(value = "/batch", method = RequestMethod.GET)
    public String redirectBatchToBatchSlash()
    {
        return "redirect:/batch/";
    }
}

Know a Better Way?

Ideally, I’d like to either get Spring Batch Admin to listen to /batch or /myapp/batch, but I’d settle on having a redirect configured in web.xml. Please tell me if you know of a good approach. I moved on with this good-enough solution.

Java: Maven Environment Variables on OS X

2013-02-28T00:00:00+00:00

Mac OS X comes with Apache Maven preinstalled. However, you’re still going to need to set some environment variables to get up and running.

Verify that maven installed in /usr/share/maven:

ls /usr/share/maven

Add the following line to your ~/.profile

# Set the M2_HOME environment variable
export M2_HOME=/usr/share/maven

# Put maven on your path
export PATH=$M2_HOME/bin:$PATH

This won’t take effect until you either reboot or open a new terminal window. You can reload the file in the current terminal window with the following command:

source ~/.profile

Solving a Mobile PDF Problem

2012-07-10T00:00:00+00:00

You find an important PDF document.

It’s not unusual to stumble upon a PDF document while web surfing on your iPad, iPhone, or iPod Touch. You might be logged into your bank’s site to view a monthly statement, or have finally found that important tax document that took you 10 minutes of poking and prodding a confusing online submission form.

You can’t email it to yourself.

You don’t have time to read the document now, and it occurs to you that you should probably share this with your spouse while you’re at it, so you touch the “Share” button and look for “Email”. This is where you realize that your only option is to email a link, not the document itself. This doesn’t help you. You are not amused.

For me, that moment of disappointment came when I had opened up a bunch of tabs with interesting articles from an online version of a magazine that I subscribe to. Emailing myself links wouldn’t work, because these PDF documents require you to login first, and for whatever reason, you can’t just navigate to an article by their URL.

The solution is simple.

I solved this problem by developing the iOS App, PDF Emailer (no longer available).

While in Safari, touch the document once to bring up the options, and touch the “Open in…” button.
Touch the “PDF Emailer” button.
Enter the recipients and send the email.

PDF Emailer will keep your PDF document until you delete it. This allows you to read it while offline, or email it out again later.

It runs on the iPad, iPhone, and iPod Touch, and is available now on the App Store.