Here’s how I achieved a similar result in Spring Web MVC. (Note: the following examples were done with Spring 3.2.1)

Built-in?

Spring does provide some build-in support for conversion to specific types. For example, you can convert to Date and various numeric types. But, what if you want to convert a request parameter to some other custom type or a type from a third party? (Such as the date-time classes from Joda Time)

Minimize configuration

I searched for a bit and found various solutions, but they all seemed to require too much configuration: In addition to writing a converter class, you’d have to manually the converter with a ConversionService (either in code or in XML configuration). I didn’t like the idea of having to register the converter class; instead, I wanted it to be registered automatically based on some annotations.

Solution

Here’s what I came up with, based on this answer on Stack Overflow.

1. Define a custom annotation for your converters so they can be automatically found

   @Target({ ElementType.TYPE, ElementType.FIELD })
   public @interface MyConverter {
   }

2. Create a converter class, annotated with your custom annotation and @Component

   This is so it will be available for injection via @Resource. (In this example, we convert to a Joda Time LocalDate)

   The converter class must implement Spring’s Converter interface.

   @Component
   @MyConverter 
   public class LocalDateConverter implements Converter<String, LocalDate> {
   
     public static final String DATE_FORMAT = "YYYY-MM-dd";
   
     @Override
     public LocalDate convert(final String source) {
       return LocalDate.parse(source, DateTimeFormat.forPattern(DATE_FORMAT));
     }
   }

3. Create a bean that extends FormattingConversionServiceFactoryBean that will auto-register all converters

   Here is where all the converters annotated with your custom annotation (and @Resource) are injected.

   public class MyConversionServiceFactoryBean extends FormattingConversionServiceFactoryBean {
   
     @Resource
     @MyConverter
     private List<Converter<?, ?>> myConverters;
   
     @Override
     protected void installFormatters(final FormatterRegistry registry) {
       // NOTE: This method call is deprecated.
       super.installFormatters(registry);
   
       for (final Converter<?, ?> converter : this.myConverters) {
         registry.addConverter(converter);
       }
     }
   
   }

4. Edit Spring configuration so that the auto-registering bean is loaded

   Ok, I lied: There is one piece of configuration you need, but once it’s made it need never be changed, even when you define additional converters.

   <mvc:annotation-driven conversion-service="applicationConversionService" />
   <bean class="com.myapplication.spring.mvc.controller.converters.MyConversionServiceFactoryBean" id="applicationConversionService"/>

5. Modify controller method to use the proper type

   Note that if conversion fails (via an uncaught exception from the convert() method) then the client will see a 400 Bad Request response.

   @RequestMapping(value = "widget/{date}", method = RequestMethod.GET)
   @ResponseBody
   public String getWidgetDate(@PathVariable("date") final LocalDate date) {
     // We get auto-conversion to a LocalDate type... 
     // Just spits back the date to the client.
     return date.toString();
   }

Summary

I hope you found this useful. With just a little bit of work, we have a bean that will auto-register and make available any new converters you define, so as long as you annotate the converter properly.

The final keyword – classes and methods

When used on a class, final prevents the class from being extended. Similarly, when final is used on a method, that method cannot be overridden in any subclass.

This is mainly done for reasons of security and consistency: If you have a class whose methods you count on to provide predictable results, you may want to prevent that class from being extended so that someone cannot substitute a subclass that behaves differently to a consumer that expects your original class. The same may go for certain methods on a class.

But generally, you should not be marking classes/methods as final unless you have a compelling argument for it. The reason is that using final may unnecessarily constrain the design and hamper future developers who may have a legitimate reason for wanting to extend your class. Though I prefer composition over inheritance, it’s not a choice I would want to force on everyone else, nor do I believe it’s always the right choice.

In particular, you should not be marking classes/methods as final just for some perceived performance benefit. In many cases you won’t gain a thing performance wise, but will be unnecessarily be constraining your design.

One reason you shouldn’t refrain from marking a method as final is for mockability; mocking frameworks like JMockit allow you to easily mock out final methods, so don’t let that affect your design decisions.

The final keyword – variables

When used on variables, final essentially means that the variable can only be assigned once. For class/static members, this is when the class is loaded; for instance members, this is when an instance of the class is created; for local variables, it is usually when the variable is declared. Method parameters can also be declared as final.

As opposed to the use of final on classes/methods, I usually like using final for most variables, as it can decrease the complexity of code by decreasing the chances for state changes. Once you know that a local variable is final, if it’s primitive, you can be sure its value won’t change; if it’s an object, you can be sure you’ll always be dealing with the same object.

Furthermore, the use of final on member variables ensures that you know they’ll be assigned once and only once: At object creation.

Some people may think that the use of final variables is superfluous, but I think it’s a good defensive programming technique. This article sums up my viewpoints nicely.

finally

As opposed to the final keyword, which is completely optional and not strictly necessary to use, you should almost always be using the finally keyword in Java when dealing with closeable resources. (This is true before Java 7, as Java 7 introduces some nice syntactic sugar that can remove the need to use finally)

Here is a contrived example:

InputStream inputStream = null;
try {
  inputStream = new FileInputStream(new File("TEST.XML"));
  final int read = inputStream.read();
  // Do other stuff with the stream...
} finally {
  if (null != inputStream) {
    inputStream.close();
  }
}

In this example, we initialize the inputStream within a try block. If anything goes wrong with reading from the stream, an exception will be thrown (which we don’t handle here, for brevity) but before it is allowed to propagate, the code within the finally block will be executed, ensuring that if the stream has been opened, it will be closed. This will prevent a resource leak from happening.

Here is how that code could also look in Java 7:

try (final InputStream inputStream = new FileInputStream(new File("TEST.XML"))) {
  final int read = inputStream.read();
  // Do other stuff with the stream...
}

As you can see, the amount of “boilerplate” is reduced as we don’t need to have an explicit finally block anymore. This is known as a “try-with-resources” statement, where an object that implements Closeable/AutoCloseable is declared and initialized with the try statement and automatically closed no matter what the outcome of the statements within the try block. I would suggest using this unless your code needs to be JDK 6 compatible.

finalize()

As opposed to final, which you may use and finally, which you will certainly have to use in JDK 6 and below, you will almost never need to implement or override Object.finalize().

The finalize() method is called by the garbage collector (GC) determines that there is no longer anyway for the object to accessed; this means the object is eligible for finalization, which means the GC can begin the process of making the object finalizable, finalized and then reclaimed. Generally any Object that does not have a Strong reference is eligible.

There is generally no need to override the default finalize() method; if your class opens resources then it should be responsible for properly closing/releasing them by using try-catch-finally as outlined above, or you should make your class implement Closeable so that clients/callers of your class can ensure its proper closure.

You could, in theory, use finalize() as a “safety net” of sorts to mitigate the effects of bad clients/callers not calling close() on your class by ensuring that internal resources are closed/released in finalize() but you should never rely on this.

Additionally, if you are overriding finalize() you must take care to ensure that you don’t “leak” a reference to the object to the “outside world”, or else this may prevent the object from being garbage collected, resulting in a potential memory leak! (i.e. don’t pass a reference to this to any external objects during finalize())

In general, if you are going to implement/override finalize(), you should have a very specific reason and be very careful in how you do so.

The final word

I hope you enjoyed this summary of final, finally and finalize(). Learning these concepts is pretty fundamental to having a good understanding of Java as a whole.

This isn’t so much of an issue for @PathParam parameters, (since you won’t even get to the proper resource method without a matching URI) but it does affect @HeaderParam and @QueryParam (among others) since they aren’t needed for Jersey to determine which resource method to invoke. By that definition, they are implicitly optional. There should be a way to make them required.

The behaviour of such a required annotation might be as follows:

• If the request does not have the parameter, then by default a Response with Status.BAD_REQUEST (HTTP 400) would be returned to the client.
• Some way of customizing the HTTP response code and message should also be provided.

Right now, there’s not really an elegant way to make something like a @HeaderParam required. Here are some solutions I’ve tried.

Attempt #1: Parameter classes

Parameter classes can be useful for transforming the single input of a parameter into a single output, and also for verifying that the input parameter value is valid. This can be useful for ensuring that an input parameter can be converted into a specific object, or that it matches a specific format.

As an example, consider the CsvListParam class. This class takes a comma-separated list as a parameter, and returns a List<String> comprising each entry in the list. It does an additional check to ensure that the input is not blank, according to StringUtils.isBlank(). If it is blank, a 400 Bad Request response is returned to the client via the WebApplicationException thrown.

Note: The following examples use the AbstractParam class from Coda Hale’s article.

public class CsvListParam extends AbstractParam<List<String>> {

  public CsvListParam(String param) throws WebApplicationException {
    super(param);
  }

  @Override
  protected List<String> parse(final String suppliedStringValue) throws Throwable {
    if (StringUtils.isBlank(suppliedStringValue)) {
      throw new WebApplicationException(Response.status(Response.Status.BAD_REQUEST).build());
    }
    return Arrays.asList(StringUtils.split(suppliedStringValue, ","));
  }
}

@GET
@Path("test")
public Response test(@HeaderParam("X-TEST") final CsvListParam param) {
  final String output;
  if (null != param) {
    output = param.getValue().toString();
  } else {
    output = "param was null";
  }
  return Response.ok(output).build();
}

However, if the parameter is not present at all – for example, if this was obtained via the @HeaderParam annotation and the header was not present – then the code in the parameter class will not even be invoked by Jersey. Instead, the value will simply be null. If we require this parameter, it results in nasty if-else null-checking code in each of our resource methods that requires the parameter.

We need something that gets rid of the necessary null-checking in each resource method.

Attempt #2: Injection Providers

Coda Hale provides another brilliant example how to use Injection Providers in Jersey. Basically, with Injection Providers, you can do everything that you could do with Parameter classes, and more.

While Parameter classes are useful only for single-input to single-output mapping, Injection Providers can map multiple inputs to single or multiple outputs. This could allow you to take multiple values in the HTTP request and use them populate a single Bean, or use them to form some more complex single value. It also allows you to do validation, as throwing a WebApplicationException from an Injection Provider will cause the contained Response or status to be properly returned to the client.

So, we can achieve a similar effect using an Injection Provider. A first attempt at resolving the issue yields the CsvListProvider class:

@Provider
public class CsvListProvider extends AbstractInjectableProvider<CsvListParam> {
  public CsvListProvider() {
    super(CsvListParam.class);
  }

  @Override
  public CsvListParam getValue(final HttpContext httpContext) {
    final String suppliedStringValue = httpContext.getRequest().getHeaderValue("X-TEST");
    return new CsvListParam(suppliedStringValue);
  }
}

@GET
@Path("test")
public Response test(@Context final CsvListParam param) {
  final String output = param.getValue().toString();
  return Response.ok(output).build();
}

However, while this works as expected, it has the unfortunate side effect that the source of the parameter (an HTTP header of “X-TEST”) has to be specified in the Provider class rather than on the annotation. This isn’t ideal since we have to create a new Injection Provider class for each HTTP header we want to make required.

Further attempts

I have been trying to figure out a solution to this. One possible way might be to change the AbstractInjectableProvider to the following declaration:

public abstract class AbstractInjectableProvider<E, A extends Annotation> extends AbstractHttpContextInjectable<E> implements InjectableProvider<A, Type>

We could then define a custom annotation type to take the place of A instead of always using @Context. However, this doesn’t work, as we have no way of then obtaining any of the annotation’s values in the concrete Provider class. A solution like this would require changes in the core of Jersey to make it work, thus reducing the solution essentially the same as having an @Required annotation as proposed above.

Conclusion

It seems like we need a proper solution to this via a change in Jersey. Evidently, others have come to the same conclusion, as there are at least two issues open for Jersey related to this.

Double trouble

The key point to understanding the tricky syntax is to realize that when you’re creating a String literal in Java, backslashes are used to form escape sequences as well. Most people are familiar with this concept, when, for example, constructing a String that spans multiple lines:

final String multiline = "A String...\nOn two lines";

When calling Pattern.compile, you pass in a String literal that is the regular expression. However, regular expressions also use the backslash character to begin escape sequences. So, to ensure that the regular expression engine in Pattern gets the correct syntax, you must replace every backslash in your regular expression with two backslashes. This is to prevent Java from interpreting the single backslash as just a String escape sequence.

Or, put another way, if you wanted a String with the contents "\n", that is a String with a backslash followed by the letter ‘n’, you’d have to define it as:

final String newLineEscapeSequence = "\\n";

This is the gist of it; we need to pass in the preserved backslashes into the Pattern regular expression engine, so you have to create a literal backslash by using a double-backslash in your String literal. This information is in the Pattern Javadoc, but it’s sort of buried beneath loads of regular expression syntax.

Keep this in mind when constructing your regular expressions outside of Java in a tool like RegExr. These principles also apply when using other classes/methods that use Pattern, such as String.split() or Scanner.useDelimiter()

An example

Here’s a simple example where we try to find the word “The” at the beginning of a String, delimited by a word boundary matcher.

public class PatternExample {
  private static final Logger LOGGER =
      Logger.getLogger(PatternExample.class);
  private static final String TEST_STRING =
      "The quick brown fox jumps over the lazy dog";

  public static void main(final String[] args) {
    System.out.println(TEST_STRING);

    final Pattern wordBoundaryWrong = Pattern.compile("^The\b.*");
    Matcher matcher = wordBoundaryWrong.matcher(TEST_STRING);
    LOGGER.debug(matcher.matches()); // false.

    final Pattern wordBoundaryCorrect = Pattern.compile("^The\\b.*");
    matcher = wordBoundaryCorrect.matcher(TEST_STRING);
    LOGGER.debug(matcher.matches()); // true.
  }
}

The key point here is that the word boundary matcher (\b) must be passed in as a String literal of "\\b" so that the backslash is properly interpreted. In the incorrect Pattern, "\b" maps to a backspace character literal.

I think the reason this concept is somewhat tricky is that you have to deal with two levels of escaping – the Java String literal syntax and the Regular Expression syntax.

Long story short, I just had to implement it (albeit a simple version) in JavaScript. The result is available on my website and I suggest you give it a try; a good pattern to start out with is the F-pentomino.

The reason I find emergence so interesting is that it provides a possible framework or explanation for the complexity and order seen in our universe, based on a fairly simple or rudimentary set of rules.

One to rule them all

The interactions seen in Conway’s Game of Life can be fairly complex and are not straightforward to predict. However, they all result from a simple set of rules:

• Each square is labeled as a cell, and has eight neighbours.
• A cell can either be “dead” or “alive”.
• A dead cell turns alive on the next turn if it has exactly three alive neighbours.
• A live cell continues to live on the next turn if it has 2 or 3 alive neighbours.

Thus, during each iteration, the state of a cell (alive or dead) is determined from the state of its neighbours on the previous turn.

Complexity from simplicity

Despite this limited ruleset, complex behaviour can be seen in the interaction between cells. In fact, quite a lot of study has been put into understanding the interactions and categorizing the various “structures” that have emerged in game.

Simulating the game on a large scale can take a lot of CPU power, so some interesting dynamic programming techniques have been utilized to increase the iteration speed. One of them is Hashlife, which exploits the repeatability and determinism in the game.

For example, if a pattern shows up an in an early stage of the simulation, it’s “evolution” can be tracked and stored so that if the same pattern ever shows up again, it’s long(er) term fate will already be known, since it was already computed earlier. This prevents unnecessary iterations in the simulation. This sort of technique is called memoization.

In Real Life

Obviously, our universe is probably more complex than the Game of Life. (It would likely have to be, since the simulation exists within our universe) But it’s also likely that all the complex interactions and structures observed in our universe boil down to some set of rudimentary rules. The point of science, in many respects, is connecting the dots that allow us to understand how these higher-level properties emerged from lower-level interactions. I’m not saying that it will provide all the answers or explain things like self-awareness, but to me, that sort of emergence is the real beauty of our universe.

The astute among you will know that one way is by implementing the Fisher-Yates shuffle algorithm. But, let’s investigate what happens when other, seemingly adequate solutions, are used instead.

Shuffler’s dilemma

One example that highlights the implications of using seemingly random and unbiased “shuffling” involves the Windows EU Browser Ballot.

The purpose of the Browser Ballot was so that Microsoft could comply with an EU directive that ordered them to provide users with a clear choice of which browser to use with Windows. The ballot was supposed to have been carefully designed; the first section contained the five most common browsers (Chrome, Firefox, Internet Explorer, Opera and Safari) with the second section containing seven lesser-used browsers.

Since it is generally considered an advantage to be placed first in a ballot (because users who don’t care one way or another might just pick the first option), the EU directed Microsoft to randomize the order in which the browsers appeared on the ballot in each of the sections. Thus, when users visited the ballot page, they were supposed to get a random ordering of the top five browsers followed by a random ordered of the lesser seven.

Looking into the cards

The team in charge of the ballot design came up with a solution to use a sorting function with a randomized comparator. In this way, they hoped to apply a randomized sort to the list of browsers, producing a random ordering that met the rules of the EU. While this did produce a random ordering, (and thus technically was in compliance with the EU directive), it did not produce unbiased results, as the ordering of some browsers came up more often than others. This lead to allegations that Microsoft was trying yet again to stifle its competition to unscrupulous practices.

However, this probably wasn’t the case, and was likely an instance of a seemingly adequate solution being used without proper testing/analysis.

To understand the problem, we first have to understand sorting algorithms, specifically those that use comparisons as their basis. (i.e. comparison sorts) An example of a comparison sort is Insertion sort. Through each step of the sorting process, the sorted portion of the list increases by one as we take the next element from the unsorted portion and position it properly within the sorted portion. This is done by comparing the element to be inserted with each element in the sorted portion until we find the correct position.

A comparator is simply a function that compares two objects, and tells us which one is greater than the other, or whether they are equal. In Java, the general structure of a Comparator would be:

new Comparator<T>() {
  @Override
  public int compare(final T o1, final T o2) {
    // If o1 is "less than" o2, return a negative integer.
    // If o1 is "equal to" o2, return 0.
    // If o1 is "greater than" o2, return a positive integer.
  }
};

In this way, the exact semantics of comparisons can be tailored to meet the needs of the application. In the case of the Browser Ballot, the team implemented something akin to the following: (Though the language was JavaScript, not Java, as the Browser Ballot was a website)

new Comparator<T>() {
  @Override
  public int compare(final T o1, final T o2) {
    return Math.random() < 0.5 ? 1 : -1;
  }
};

In this comparator, the objects being compared are not even considered; instead the either -1 or 1 is returned with equal probability. Using this sort of “comparison” with a sorting algorithm might seem to provide random, unbiased results – but in reality, such “common sense” did not make so much sense after further analysis.

Looking deeper

To look at the problem a bit more in-depth, I decided to write an example in Java that would test the results of a “random sort” on a set of four objects, using the following sorting algorithms: A modified Merge sort (provided by Java’s Collections.sort()), Quicksort, Insertion sort and Selection sort. These results would then be compared to using the proper method, a Fisher-Yates shuffle.

Some more details:

• The list to be shuffled started off with the ordering of [1, 2, 3, 4]
• I used my own implementation of Quicksort that just selected the pivot from the middle of the list.
• Bubble sort was not considered, since with a randomized comparator, the algorithm may never terminate!

Here are the results:

As you can see, the Fisher-Yates shuffling algorithm produces the expected near-uniform distribution, represented by the almost-straight line. The “randomized” sorting algorithms most definitely did not produce a uniform distribution. Interestingly, the modified merge sort used by Collections.sort() produced the same distribution as Insertion sort; This may mean that this specific implementation of merge sort uses an insertion sort when the collection size is sufficiently low.

Of the sorting algorithms tested, Quicksort had the least difference between the “peaks” and “troughs”, though the bias was still very evident. I’ve heard that Quicksort may produce a near-uniform distribution when used with a randomized comparator, but I’m guessing that would depend greatly on the choice of pivot.

Conclusion

Randomization is never an easy thing; one must fully consider the effects of a specific algorithm before jumping to conclusions as “common sense” doesn’t really make much sense in this area. Come to think of it, “common sense” is rarely sensible.

Careful analysis is always needed whenever dealing with distribution of random variables. In general, for a random variable A that has a certain distribution, f(A) is not guaranteed to have the same distribution. This is the point that was missed when designing the ballot.

Analysis of the Fisher-Yates algorithm is fairly easy: The reason why it works is that at each step of selecting an element from the collection, each remaining element has an equally-likely probability of being selected. Analysis of each of the randomized sorting algorithms to understand why each distribution was produced is more difficult, and is left as an exercise to the reader.

It’s also worthwhile to note that the correct shuffling algorithm (Fisher-Yates) runs in O(n) time, while all of the randomized sorting algorithms have a longer asymptotic run time.

This isn’t going to be an indictment of bad programming; in fact, I think it’s good if you can look back at your old code and see where it could be improved. Such a process suggests that you are continually self-improving, a skill crucial in software development. Besides, all of us have made a mistake or two at times when we were stressed, tired or just plain not thinking straight.

However, there’s one mistake that I’ve seen that I think warrants bringing to light, and that is the misuse of the Flyweight pattern.

Who wants to be a Flyweight?

Flyweight is typically used to describe one of the smaller weight classes in boxing or other fighting sports. This “minimal” aspect is what is shared with the design pattern of the same name. Simply put, a Flyweight object is one that reduces memory use by sharing common data with other objects. Despite this plain definition, implementing the Flyweight pattern can be tricky.

Perhaps this is why I have seen examples like this: (Java pseudo-code below; may not compile, but you shouldn’t use it anyways)

public class WidgetWithManyFields() {
  private Data field1;
  private String field2;
  private int field3;
  // A lot more fields...
  private SomeOtherData fieldN;

  // Getters and setters...
}

Now, obviously the memory footprint of WidgetWithManyFields can be quite large, and since not all aspects of an application will need access to all data fields, it was decided that a “Flyweight” was needed:

public class WidgetFlyweight() {
  // Only these fields are needed.
  private Data field1;
  private String field2;

  public WidgetFlyweight() {
    // Default constructor.
  }
  
  // Constructor to make one from the regular widget class.
  public WidgetFlyweight(WidgetWithManyFields widget) {
    this.field1 = widget.getField1();
    this.field2 = widget.getField2();
  }
  // Getters and setters...
}

This isn’t really the Flyweight pattern at all. In fact, I don’t even know if it is a pattern at all. It might be considered something like the Proxy pattern, if the “Flyweight” class contained an instance of the regular class. But I don’t really know.

So what is a Flyweight?

Consider the example of a document that can have images embedded in it. There might be multiple copies of the same image present in the document, but each copy would be sized and positioned differently within the document.

In this case, you wouldn’t want to load and store the data in memory for multiple copies of the same image as that would be wasteful. However, each instance of the image displayed in the document might be formatted or positioned differently. How might this be done?

Firstly, some assumptions:

• An image is uniquely identified by some resource path.
• The underlying image data does not change during the lifetime of the application.

With these assumptions, we can define three classes that allow us to implement the Flyweight pattern.

Firstly, an ImageData class that encapsulates the actual image data. There should be only one canonical instance of this class for each unique resource path. Because of this, we can pool these objects for reuse.

However, the ImageData objects won’t be directly used by other parts of the application. Instead, we create an ImageFlyweight class that is manipulated. Each instance contains a reference to a canonical ImageData object and also stores information about how to format and position the image.

In this way, there can be multiple ImageFlyweight instances that reference the same image and hence the same ImageData instance, but each instance would define separate formatting and positioning details.

Tying everything together is a factory (ImageFlyweightFactory) that maintains the pool and is the access point for getting instances of ImageFlyweight.

Below is the code: (Sorry, it’s a lot of code to throw at you at once, but I didn’t feel like breaking it down into separate chunks, and you can just copy & paste it into your favourite IDE for inspection/compilation)

/**
 * Copyright (c) 2012 Peter Chng, http://unitstep.net/
 */
package net.unitstep.examples.flyweight;

import java.util.HashMap;
import java.util.Map;

/**
 * In order for the Flyweight Pattern to be effective, ImageFlyweight instances
 * should only be obtained via ImageFlyweightFactory.getImageFlyweight().
 *
 * This ensures that for each unique resource path, there is only one instance
 * of the backing ImageData existing in the application.
 *
 * @author Peter Chng
 */
public class ImageFlyweightFactory {
  private Map<String, ImageData> imageDataPool =
      new HashMap<String, ImageData>();

  public ImageFlyweight getImageFlyweight(final String resourcePath) {
    // This will return a new ImageFlyweight object each time; however, the
    // backing ImageData might be shared across multiple ImageFlyweight
    // instances.
    return new ImageFlyweight(this.getImageData(resourcePath));
  }

  private ImageData getImageData(final String resourcePath) {
    ImageData imageData = this.imageDataPool.get(resourcePath);
    if (null == imageData) {
      imageData = new ImageData(resourcePath);
      this.imageDataPool.put(resourcePath, imageData);
    }
    return imageData;
  }

  /**
   * @return the current count of ImageData instances in the pool; only for
   *         testing purposes.
   */
  public int getImageDataPoolCount() {
    return this.imageDataPool.size();
  }

  /**
   * Will contain the data representing an image loaded from some resource, i.e.
   * the file system.
   *
   * This is a private inner class because it should never need to be used
   * externally by callers. It is considered an implementation detail.
   *
   * We assume that the resource path is the uniquely-identifying aspect of an
   * image and that the underlying image resource/data will not change over the
   * lifetime of the application.
   *
   * Thus, only one instance of the ImageData class is needed for each image
   * uniquely identified by its resource path.
   *
   * @author Peter Chng
   */
  private class ImageData {
    private final byte[] data;
    private final String resourcePath;

    public ImageData(final String resourcePath) {
      this.resourcePath = resourcePath;

      // Image data would be loaded here based on the resource path supplied.
      // For brevity, it's not really done.
      this.data = new byte[] {};
    }

    public byte[] getData() {
      // Note: If we really intend to make this class immutable, we should
      // return a defensive copy instead so that callers cannot modify the
      // data stored in this instance.
      return this.data;
    }

    public String getResourcePath() {
      return resourcePath;
    }

    // Note: Not strictly necessary to override equals() and hashCode() for this
    // example, but it's done to indicate we only consider the resource path
    // in determining equality.
    @Override
    public boolean equals(final Object object) {
      if (null == object) {
        return false;
      }
      if (object == this) {
        return true;
      }
      if (object.getClass() != this.getClass()) {
        return false;
      }
      return this.resourcePath.equals(((ImageData) object).getResourcePath());
    }

    @Override
    public int hashCode() {
      return this.resourcePath.hashCode();
    }
  }

  /**
   * The ImageFlyweight object contains a reference to a canonical ImageData
   * object containing the actual image data we wish to render.
   *
   * By making this a static inner class of {@link ImageFlyweightFactory} and
   * the constructor private, instantiation of this class can be controlled and
   * limited to only the {@link ImageFlyweightFactory}. Callers MUST obtain an
   * instance of the ImageFlyweight through the factory and not by direct
   * instantiation.
   *
   * It also contains other properties that will affect the rendering of the
   * image in the application, such as height, width and position.
   *
   * Reusing the same ImageData object across different ImageFlyweight instances
   * allows us to display the same image in different ways within the
   * application, without having to load (or store in memory) the image data
   * multiple times.
   *
   * @author Peter Chng
   */
  public static class ImageFlyweight {
    private final ImageData imageData;

    private int height;
    private int width;
    private int positionX;
    private int positionY;

    private ImageFlyweight(final ImageData imageData) {
      this.imageData = imageData;
    }

    public byte[] getData() {
      return this.imageData.getData();
    }

    // Getters/setters for height, width, positionX, positionY...

    public int getHeight() {
      return height;
    }

    public void setHeight(int height) {
      this.height = height;
    }

    public int getWidth() {
      return width;
    }

    public void setWidth(int width) {
      this.width = width;
    }

    public int getPositionX() {
      return positionX;
    }

    public void setPositionX(int positionX) {
      this.positionX = positionX;
    }

    public int getPositionY() {
      return positionY;
    }

    public void setPositionY(int positionY) {
      this.positionY = positionY;
    }
  }
}

Everything is contained within the ImageFlyweightFactory class, because the ImageData class does not need to be visible to outsiders and callers should not be able to instantiate ImageFlyweight instances on their own.

With this code, we have a simple test harness to verify whether it’s working:

/**
 * Copyright (c) 2012 Peter Chng, http://unitstep.net/
 */
package net.unitstep.examples.flyweight;

import net.unitstep.examples.flyweight.ImageFlyweightFactory.ImageFlyweight;

import org.apache.log4j.Logger;

/**
 * @author Peter Chng
 */
public class ImageFlyweightTest {

  private static final Logger LOGGER =
      Logger.getLogger(ImageFlyweightTest.class);

  public static void main(final String[] args) {
    final ImageFlyweightFactory factory = new ImageFlyweightFactory();

    final String resourcePath1 = "/path/to/images/someImage.png";
    final String resourcePath2 = "/path/to/images/anotherImage.png";

    final ImageFlyweight image1 = factory.getImageFlyweight(resourcePath1);

    displayImageDataCountInPool(factory);

    final ImageFlyweight image2 = factory.getImageFlyweight(resourcePath2);

    displayImageDataCountInPool(factory);

    // Should not create an new ImageData instance in the pool.
    final ImageFlyweight image3 = factory.getImageFlyweight(resourcePath1);

    displayImageDataCountInPool(factory);
  }

  private static void displayImageDataCountInPool(
      final ImageFlyweightFactory factory) {
    LOGGER.debug("Current number of ImageData instances: "
        + factory.getImageDataPoolCount());
  }
}

Running the code yields the following results:

DEBUG ImageFlyweightTest - Current number of ImageData instances: 1
DEBUG ImageFlyweightTest - Current number of ImageData instances: 2
DEBUG ImageFlyweightTest - Current number of ImageData instances: 2

The key point is that after the third ImageFlyweight object is created, the count in the ImageData pool does not increase since the same image has already been “loaded”.

Other examples

Note that Java itself implements something similar to the Flyweight pattern for Strings; this is known as string interning and many other languages support this feature as well.

Basically, because Strings are immutable, Java can store each distinct value in a pool and then reuse these instances when appropriate. As an example, the following code displays “EQUAL”:

String string1 = "A test of the string intern pool.";
String string2 = "A test of the string intern pool.";
// Note that we are comparing object identity, NOT equality.
if (string1 == string2) {
  System.out.println("EQUAL");
} else {
 System.out.println("NOT EQUAL");
}

Note that this doesn’t work if you directly create a String using the new keyword.

Conclusion

I know that this was a fairly contrived example (aren’t they all?), but I hope it provided the basics of the Flyweight pattern to readers. There are a lot of holes and I don’t suggest you directly copy this example for production code, but instead learn the skills to effectively develop the pattern on your own.

As always, I welcome questions or comments and especially corrections if I’ve made a mistake! Thanks for reading!

They’ve fallen off of my face more than once, have tumbled many times to the hardwood floor from my nightstand while I fumbled for them in the dark, been lost in my bed covers and rolled onto during numerous occasions, and of course I’ve fallen asleep with them on more times than I can remember. Despite all of this, they not only held together, but retained much of the original lustre and remain in excellent condition.

Only one of the earpieces is starting to look worn, the nose pads are looking a little old and one of the lens screws had to be replaced when it fell out and got lost, but other than that, they’re as good as new. This was the first “thin” pair of glasses I had ever worn and I initially had some reservations about durability, so I’m more than pleased with how well they’ve held up. (I think the frames are made up of some titanium, but I can’t remember)

But this past weekend, I decided it was time to finally replace them.

We’ve had a good run, old friend, but I’m afraid it’s time to part ways.

I went down to the local Pearle Vision since it was close and seemed to have a decent selection of frames. In fact, I found there was just too many options. Many of them were easily ruled out, but I still ended up spending over an hour trying on frames with fingerprints and smudges all over the lenses in an effort to find the right pair. Or, rather, the right pairs, since they had this screwed up pricing that basically forced you to buy two pairs at once since you hardly saved anything by buying a single pair.

The problem with selecting glasses (besides my indecisiveness, aggravated by the multitude of options) is that it’s hard to know how well they’ll do or look over the long run. Durability is important to me, and certainly some frames “felt” more durable than others, but that’s not really a sound way of assessing things. I guess I’m just expecting these new frames to last as long as the previous ones did, because I find it hard to change “styles”.

The other problem is that it’s hard to tell what you look like in them if you don’t wear contacts – thankfully this isn’t a problem for me; I’d be nearly blind without corrective vision.

Eventually, if you try on enough frames and stay in the store for long enough, almost all glasses start to look acceptable. This is because style and attractiveness are both subjective and tend to be swayed one way or another by overexposure. It’s almost as if your subconscious is overriding your critical thinking in an effort to get you out of the store and on your way.

You need to know when this effect is taking a hold of you, so I suggest the following: Within five minutes of entering the store, identify and try on a pair of frames that look utterly ridiculous on you. Then, put these back; don’t worry, you definitely won’t be getting these. After you’ve been in the store for an hour or so, and you’re noticing that most frames you’re trying on are looking good, go back and try on the hideous pair.

If the hideous pair now look attractive or even slightly better than before, your judgment has already been compromised. Either leave and come back another day or take your chances with a pair that you found attractive early on during your search. This is what I did.

I should be getting the new frames within a few days. Hopefully I wasn’t judgment-impaired when I made my choice.

I took a new approach to training and really dedicated myself to it. There were many mid-week 4 AM mornings, followed by 1.5-2 hour runs in the dark, snow/rain and wind. I arrived at the starting line being as prepared for any race as I’d ever been.

However, I failed to meet my goal time of a sub-3:03 marathon, finishing in only 3:07:20. I made several mistakes early on and fell behind the pace within the first 10 km. However, I was most disappointed in myself for not pushing harder. I felt that I had mentally “checked out” after the first half, and consciously or not, believed that meeting my goal was now impossible due to the early mistakes. Because of that, I felt that I didn’t try as hard as I could and that I did not give 100% for fear of failure. It was almost as if I had sabotaged myself into thinking, “If I don’t give 100% and miss my goal, well at least then I will have an excuse.”

I fell into a pretty big slump after Boston and didn’t/couldn’t run for almost a week after. Even when I did start again, things just weren’t the same – my confidence had been shattered. I knew I had to break out of this slump, so I signed up for the Mississauga Half Marathon, which was about a month after Boston, to give me something to shoot for.

Why the half? Simply put, I didn’t think I’d be ready for another full so soon – not just physically, but mentally as well. If I were to run the full, I would have wanted to aim for a sub-3:05, in order to get in on the first week of registration for 2012. However, I didn’t feel that I would have the mental toughness required to meet that time and couldn’t deal with the heartbreak of another missed goal. So, I decided on the half, a distance I felt comfortable with.

Things turned out great – though the conditions were looking windy/rainy, things actually were not that bad, and I was able to pull of a huge PR, finishing in a time of 1:24:02 in the Mississauga Half Marathon, well ahead of any goal I’d had. This was good enough for 4th in my age group. Suffice to say, this was a huge confidence booster, something I sorely needed.

Edmonton Marathon

Coming off my performance at the Mississauga Half, I felt elated and immediately signed up for the Edmonton Marathon, which takes place on August 21st of this year. This would give me two weeks of downtime before I would have to start a 12-week training schedule for it. 12 weeks might seem a little short, but I actually think it’s pretty close to optimal considering my present situation. I felt that the 18-week program I used for Boston was perhaps a little long, and something between 14-16 weeks would have been better.

Given that I’m coming off a good base established by my Boston training (though not reflected in my performance there, but instead at the Mississauga Half), I feel that 12 weeks is more than enough to be ready for Edmonton, provided I stick to the plan, rest/recovery well and not over do things.

Edmonton will be my last chance to qualify for Boston 2012, since registration starts in early September. Technically, I’m already “qualified” for Boston 2012, but I don’t believe my time will be fast enough to actually allow my entry accepted. Complicated story aside, most runners I’ve talked to have thought that you’ll need to have at least BQ-5 (that is, your Boston Qualification time minus 5 minutes) in order to have a chance to get in, so I’ll be aiming for a sub-3:05 finish.

Running a marathon is no easy task. You train for months and basically have once chance to prove yourself. I don’t deal well with pressure, and I choked at Boston this year. I’m trying to avoid that this time in Edmonton.

Edmonton has the advantage of being a flat course, and the climate is not known for its hot summers. When I ran it back in 2009, the starting line temperature was only around 8C with a finishing temperature of 16C. This is pretty close to ideal. However, there are only so many things one can control.

Training doesn’t guarantee any performance; it can only increase the chances of reaching your desired goal. I have accepted the fact that I may give 100% this time and again fail to meet my goal – that is just part of the game. You can’t be afraid to fail if you want to achieve something.

Site updates

Yet again, I’ve fallen behind with keeping this site up to date with articles and guides. It’s not that I don’t have any ideas, it’s just that I’ve been lazy to make the time to put them together. A combination of work, training and life has yet again provided me with the excuse to not further this site with articles that may be of importance to readers.

Writing tutorials and other informational articles is as much a help to me as it is to those who read them, so I will be putting more effort towards this. I hope that you have enjoyed the few that I have written this year.

However, when I received the package from Dell, I was surprised at the size. It came in a huge 18″x13″ bubble envelope:

I thought it was just excess shipping packaging, but opening the enveloped made it clear that the packaging was only just big enough to hold the actual item:

For batteries with packaging that seems to imply they’re good for the environment, you think they would have made the packaging a little less excessive. The packaging is still 100% recyclable, but it still costs energy to make it.

At least Dell didn’t put the already-large item in a huge shipping box.