Making Pickles

One of the great things about living in Toronto is the abundance of corner stores with fresh, cheap produce. There's at least one within walking distance of most inner city houses and apartments. Stores like these are made possible by the Ontario Food Terminal, a wholesale market where producers lease stalls and buyers can enter for a small fee. From the mom & pop operation down the street to the multinational megamarkets, all kinds of buyers show up early every morning.

The selection at the corner store tends to be smaller, fresher, and cheaper than the megamarts. Beyond the traditional Western staples of carrots, onions, potatoes, and so on which are always available, I imagine the selection is based mostly on what was cheapest or best presented last time the owners visited the food terminal.

For the past 4-6 weeks, our local store has kept a big box of small cucumbers filled. The sign says they're "Dill Cucumbers." I'm not sure if there really is such a thing (maybe that's what they're really called!), but turning them into dill pickles sounded like a fun project. So I bought some.

I don't have any canning experience or equipment, so I started by looking up recipes for refrigerator dill pickles. There are many to choose from, and my survey of 10-15 of them tells me the essence of the dill pickle brine is vinegar, water, kosher salt, and dill weed or seed. I combined the following in a saucepan and brought it to a boil:

1 part pickling or kosher salt (by dry volume)
4 parts vinegar
12 parts water
1 tbsp dill seeds
1 tsp pickling spice

Once the salt dissolves into the brine, it doesn't add much volume. You can ignore it in your calculation. So, you can make 1 litre of brine using 75cL water, 25cL vinegar, and 62.5mL salt.

Some recipes call for boiling the brine where others say to just work with room-temperature ingredients. I decided to boil the brine mostly because I believed it would extract more flavour from the spices, and perhaps speed up the initial stage of the pickling process. Maybe next time I'll try it at room temperature to see if it makes any difference.

Of the recipes that did call for boiling the brine, a few of them said to chill the cucumbers in an ice water bath before pouring the brine over them. The claimed advantage is that the pickles will come out crunchier if you chill them first. I did this. It makes sense--cold pickles should be less likely to get cooked by near-boiling brine, but of course the cold probably cancels out the possibility that the hot brine will kick-start the pickling process.

After their ice bath, I packed the following into three jars (I later discovered we had a large jar big enough to hold everything. I'll use that next time!)

1 bunch of fresh dill
1kg of pickling cucumbers, chilled in ice water
4 cloves of garlic, sliced
1/2 white onion, thinly sliced

Then I poured the boiled brine over the ingredients in the jars, lidded them, and waited for them to reach room temperature (several hours).

How long did they take to become pickled? I tried one after a few days, and it was mildly pickled. I was actually worried that there was too much water and not enough salt and vinegar in the brine. But after a full seven days in the fridge, the cucumbers were pickled all the way through and had a pleasant abundance of sourness and saltiness.

I was surprised that the dill flavour was less prominent than expected. Dill is a distinctive flavour, but quite mild. I assumed a whole batch of dill weed plus some seeds would have provided sufficient flavour. Perhaps with more time in the fridge, the dill flavour would have become more pronounced. Which brings me to my next point…

These pickles were quite popular, both with us and our guests! They were completely gone within three weeks of my making them, which effectively means we ate them all in the two weeks after they "matured." A store-bought jar of pickles typically lasts several months in our house.

In conclusion, making refrigerator dill pickles was fun and easy. Not only would I do it again, but I already have. The second batch is ready for consumption. I think I'll go have a pickle now.

I've started contributing to the Android Cookbook, a brand new project of O'Reilly which is being run by my friend, Ian Darwin. Since you retain ownership of the material that you submit and simply license it to O'Reilly under the Creative Commons cc-by license, you have every reason to contribute something you may have already written–and no excuse not to!

Here is the first recipe I submitted:

Problem

Android's embedded SQLite3 database supports date and time data directly, including some useful date and time arithmetic. However, getting these dates out of the database is troublesome: there is no Cursor.getDate() in the Android API.

Solution

Use SQLite's strftime() function to convert between SQLite timestamp format and the Java API's "milliseconds since the epoch" representation.

Discussion

This recipe demonstrates the advantages of using SQLite timestamps over storing raw milliseconds values in your database, and shows how to retrieve those timestamps from your database as java.util.Date objects.

Background

The usual representation for an absolute timestamp in Unix is time_t, which historically was just an alias for a 32-bit integer. This integer represented the date as the number of seconds elapsed since UTC 00:00 on January 1, 1970 (the Unix time epoch.) On systems where time_t is still a 32-bit integer, the clock will roll over partway through the year 2038.

Java adopted a similar convention, but with a few twists. The epoch remains the same, but the count is always stored in a 64-bit signed integer (the native Java long type) and the units are milliseconds rather than seconds. This method of timekeeping will not roll over for another 292 million years.

Android example code that deals with persisting dates and times tends to simply store and retrieve the raw milliseconds since the epoch values in the database. However, by doing this, it misses out on some useful features built in to SQLite.

The Advantages

There are several advantages to storing proper SQLite timestamps in your data: you can default timestamp columns to the current time using no Java code at all; you can perform calendar-sensitive arithmetic such as selecting the first day of a week or month, or adding a week to the value stored in the database; and you can extract just the date or time components and return those from your data provider.

All of these code-saving advantages come with two added bonuses: first, your data provider's API can stick to the Android convention of passing timestamps around as long values; second, all of this date manipulation is done in the natively-compiled SQLite code, so the manipulations don't incur the garbage collection overhead of creating multiple java.util.Date or java.util.Calendar objects.

The Code

Without further ado, here's how to do it.

First, create a table that defines a column of type timestamp.

CREATE TABLE current_list (
    item_id INTEGER NOT NULL,
    added_on TIMESTAMP NOT NULL DEFAULT current_timestamp,
    added_by VARCHAR(50) NOT NULL,
    quantity INTEGER NOT NULL,
    units VARCHAR(50) NOT NULL,
    CONSTRAINT current_list_pk PRIMARY KEY (item_id)
);

Note the default value for the added_on column. Whenever you insert a row into this table, SQLite will automatically fill in the current time (accurate to the second) for the new record.

sqlite> insert into current_list (item_id, added_by, quantity, units)
   ...> values (1, 'fuerth', 1, 'EA');
sqlite> select * from current_list where item_id = 1;
1|2010-05-14 23:10:26|fuerth|1|EA
sqlite>

See how the current date was inserted automatically? This is one of the advantages you get from working with SQLite timestamps.

How about the other advantages?

Select just the date part, forcing the time back to midnight:

sqlite> select item_id, date(added_on,'start of day')
     ...> from current_list where item_id = 1;
1|2010-05-14
sqlite>

Or adjust the date to the Monday of the following week:

sqlite> select item_id, date(added_on,'weekday 1')
     ...> from current_list where item_id = 1;
1|2010-05-17
sqlite>

Or the Monday before:

sqlite> select item_id, date(added_on,'weekday 1','-7 days')
   ...> from current_list where item_id = 1;
1|2010-05-10
sqlite>

These examples are just the tip of the iceberg. You can do a lot of useful things with your timestamps once SQLite recognizes them as such.

Last, but not least, you must be wondering how to get these dates back into your Java code. The trick is to press another of SQLite's date functions into service—this time strftime(). Here is a Java method that fetches a row from the current_list table we've been working with:

 Cursor cursor = database.rawQuery(
  "SELECT item_id AS _id," +
  " (strftime('%s', added_on) * 1000) AS added_on," +
  " added_by, quantity, units" +
  " FROM current_list", new String[0]);
 long millis = cursor.getLong(cursor.getColumnIndexOrThrow("added_on"));
 Date addedOn = new Date(millis);

That's it: using strftime's %s format, you can select timestamps directly into your Cursor as Java milliseconds since the epoch values. Client code will be none the wiser, except that your content provider will be able to do date manipulations for free that would take significant amounts of Java code and extra object allocations.

See Also

SQLite's documentation for its date and time functions
This recipe in the Android Cookbook

Guaranteed Definite Assignment, Bugs, and You

Here is a great technique to adopt when you must initialize a variable to one of two or more values. It's a simple technique that's easy to apply even when you're feeling lazy, but I'm surprised at how few people are aware of the advantages.

The scenario is simple enough: while revisiting a little parser I wrote a few months ago which turns strings such as "2010-02.1m" into corresponding typesafe immutable objects with a start date and end date, a small addition I made to it had the fortunate side effect of revealing a boneheaded bug I had baked into the original version.

Quick–can you spot the bug in this code, which compiles with no warnings and no errors?

Calendar start = (Calendar) end.clone();
if (periodType.equals("d")) {
 start.add(Calendar.DAY_OF_MONTH, 1 - periodScalar);

} else if (periodType.equals("m")) {
 start.set(Calendar.DAY_OF_MONTH, 1);
 start.add(Calendar.MONTH, 1 - periodScalar);

} else if (periodType.equals("y")) {
 start.add(Calendar.DAY_OF_MONTH, 1);
 start.add(Calendar.YEAR, -periodScalar);
}

return new FilingPeriod(
     code,
     start.getTime(),
     end.getTime());

It's missing the else part that throws an exception for unknown period types. Did you see it, or were you too distracted by the calendar manipulation to notice the obvious problem?

This code fragment comes from an accounting-related application, and sooner or later someone is going to have to add "q" for Quarter. If you gave the above code a periodType of "q," it would happily return an incorrect result rather than throw an exception. Besides, we're essentially building a parser for a little language here. It ought to throw an informative exception when you give it invalid input.

It was easy to justify the need for the catch-all else clause here, but truthfully, it's simply part of the idiom, and it's a waste of time to contemplate whether the catch-all is likely to actually do anything in practice. You should just get in the habit of always including it, and consider its omission in existing code to be an error. Unfortunately, even though it's such an important thing to remember, the compiler didn't issue any warnings or errors about its absence.

The good news is, your Java compiler can enforce the need for an else block that throws an exception (or returns normally, but your muscle memory for this idiom should have you typing "throw new …" before you've even thought about it.)

By the way, even if you did "immediately" spot the missing else, I bet it still took you more than .0001 seconds. It would have been more efficient, and safer, to let your Java compiler pick it up.


Let the compiler help you

So how do you enlist javac's help? Here's the change I made that gave javac the chance to throw my previous mistake in my face (sure, it sounds irritating, but it's actually a very very good thing:)

Calendar start = (Calendar) end.clone();
int monthsCovered;
if (periodType.equals("d")) {
   start.add(Calendar.DAY_OF_MONTH, 1 - periodScalar);
   monthsCovered = periodScalar / 30; // approximate

} else if (periodType.equals("m")) {
   start.set(Calendar.DAY_OF_MONTH, 1);
   start.add(Calendar.MONTH, 1 - periodScalar);
   monthsCovered = periodScalar;

} else if (periodType.equals("y")) {
   start.add(Calendar.DAY_OF_MONTH, 1);
   start.add(Calendar.YEAR, -periodScalar);
   monthsCovered = periodScalar * 12;
}

return new FilingPeriod(
     code,
     start.getTime(),
     end.getTime(),
     monthsCovered);

Now, the code won't compile: referencing monthsCovered is now an error because it might not be initialized. If I had initialized monthsCovered to 0 (or any other value) then the compiler would not have found the missing else for me. This is the key of what I'm saying: don't initialize your local variables to some garbage value. Leave them blank, and the compiler will help you to write better code.


But you can do even better

In most cases such as this, you can gain even more safety by marking the uninitialized variable final. This causes the compiler to guarantee that the variable has been assigned exactly once before it is first referenced.

Marking your uninitialized local variables final makes it virtually impossible for a future maintainer^[1] to accidentally introduce subtle bugs into your multi-path initialization code–and this is the code where bugs experience long incubation periods before they rear their ugly heads^[2].

Calendar start = (Calendar) end.clone();
final int monthsCovered;
if (periodType.equals("d")) {
   start.add(Calendar.DAY_OF_MONTH, 1 - periodScalar);
   monthsCovered = periodScalar / 30; // XXX approximate

} else if (periodType.equals("m")) {
   start.set(Calendar.DAY_OF_MONTH, 1);
   start.add(Calendar.MONTH, 1 - periodScalar);
   monthsCovered = periodScalar;

} else if (periodType.equals("y")) {
   start.add(Calendar.DAY_OF_MONTH, 1);
   start.add(Calendar.YEAR, -periodScalar);
   monthsCovered = periodScalar * 12;

} else {
   throw new ParseException(
       "Unrecognized period type in period " +
       "specifier: " + code);
}

return new FilingPeriod(
     code,
     start.getTime(),
     end.getTime(),
     monthsCovered);

This third revision is robust code that's relatively safe in the hands of future maintainers. In terms of word count, it's a small change from the first example, but it's code I'd be far more comfortable having inside any system I'm responsible for.


The next step

Is it possible to make this type of code even more robust in the face of future modification? Yes! The typesafe enum pattern, introduced by Josh Bloch, is undoubtedly safer than what I've recommended above. It has even become a language feature in Java 5, which eliminates much of the boilerplate in simple applications of the pattern. However, unlike leaving your variables uninitialized and marking them final, applying the typesafe enum pattern to this type of problem is a big tradeoff in terms of lines of code you will write to solve the same problem. Is the tradeoff worthwhile? In many cases, I think it is.

My next post will go through the process of applying a typesafe enum to this same problem, and I will give you my insights on when I would go the extra mile versus sticking with the more succinct solution you see above. Ultimately, though, it's up to you to decide for yourself on a case-by-case basis.

[1] And let's be honest–this hypothetical future maintainer will be you, six weeks from now.
[2] This will happen either in production, or, more likely, during a demo.