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.

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!

When calling methods, primitive data types are passed by value, while objects and arrays are passed by reference. This means when you call a method with an object as a parameter, you are merely providing that method a way to access/manipulate the same object via a reference; no copy is made. Contrast that with primitives: When calling a method that requires them, a copy of that value is put on the call stack before invoking the method.

In that way, references are somewhat like pointers, though they obviously cannot be manipulated by pointer arithmetic. But what about weak references? What are they, and how do they contrast with strong references?

Weakly understood

Based on my experience, the concept of weak references, or more generally reachability, is not one that is well-understood in the Java world. At least I did not have a good grasp of them until stumbling upon some sample code one day. It may be that the need to utilize them is outside the confines of most day-to-day programming tasks, as the concept is fairly low-level. Nonetheless, it’s an important concept to understand.

Basically, Java specifies five levels of reachability for objects that reflect which state the object is in, in relation to being marked as finalizable, being finalized and being reclaimed. They are, in order of strongest-to-weakest:

1. Strongly Reachable
2. Softly Reachable
3. Weakly Reachable
4. Phantom Reachable
5. Unreachable

An object’s normal state, as soon as it has been instantiated and assigned to a variable/field is strongly reachable. Chances are, these are the only types of objects you’ve worked with. We’ll first cover the concept of weakly reachable objects, as I believe it provides a good base for understanding the remainder.

Cleaning out the trash

Going by the API reference, a weakly reachable object is one that can be reached by traversing (i.e. going through) a weak reference. That’s a succinct definition to be sure, but it just raises the next question: What is a weak reference?

Simply put, if an object can only be reached by traversing a weak reference, the garbage collector will not attempt to keep the object in memory any more than it would an object with no references to it, i.e. an object that cannot be accessed. Thus, from the garbage collector’s point-of-view, a weakly-referenced object will eventually be cleaned from memory the same as an object no references to it.

So, if weakly-referenced objects are treated the same as completely non-referenced ones, what is the purpose of the weak reference? A good example is the WeakHashMap, a class provided by Java.

WeakHashMap

Unfortunately, WeakHashMap may also be poorly understood, probably as a result of weak references not being well known. WeakHashMap may at times be described as a “cache” of sorts, where objects/entries that are not used will be removed to decrease memory usage. This is not how WeakHashMap works at all.

The best way to describe a WeakHashMap is one where the entries (key-to-value mappings) will be removed when it is no longer possible to retrieve them from the map. For example, say you’ve added an object to the WeakHashMap using a key k1. If you now set k1 to null, there should be no way to retrieve the object from the map, since you don’t have the key object around any more to call get() with. This behaviour is possible because WeakHashMap only has weak references to the keys, not strong references like the other Map classes.

Note that for the WeakHashMap to work this way, as it was intended, the key objects must only be considered equal if they are actually the same object – i.e. object identity instead of mere equality. This is the default behaviour for Object.equals() and Object.hashCode(), so if these methods have not been overridden, the object is OK to be used as a key in WeakHashMap. Objects like Integer are not suitable for use in WeakHashMap, because it is possible to create two separate (non-identical) objects that are both equal:

final Integer i1 = new Integer(4);
final Integer i2 = new Integer(4);
LOGGER.debug("i1.equals(i2): " + i1.equals(i2)); // True.
LOGGER.debug("i1 == i2: " + (i1 == i2)); // False.

Another point of importance is that String is not a suitable key for a WeakHashMap as well. In addition to its overriding of equals() and hashCode(), String objects in Java are also interned (i.e. stored) in a pool by the JVM when created. This means that they may remain strongly referenced even after you have apparently gotten rid of your reference to them. Because of this, entries that you add to a WeakHashMap using String keys may never get dropped, even after you have apparently lost reference to the keys, since the Strings may remain strongly referenced in the string intern pool.

An example of String interning:

final String s1 = "The only thing we have to fear is fear itself.";
final String s2 = "The only thing we have to fear is fear itself.";
LOGGER.debug("s1.equals(s2): " + s1.equals(s2)); // True.
LOGGER.debug("s1 == s2: " + (s1 == s2)); // May also return true!

String objects are interned for performance reasons, so when you are going to create a new String, Java first checks if there is a String in the pool that is “equal” to the one you are creating. If such a String exists, the existing object is just returned instead of having to instantiate a new object. This is possible because Strings in Java are immutable, i.e. operations that appear to modify a String (such as concatenation, toUpperCase(), etc.) really return a new String object while preserving the original.

The last usage note is that even though the keys are weakly-referenced by WeakHashMap, the values remain strongly-referenced. Thus, you must take care to not use value objects that strongly reference the keys themselves, as if this happens, the keys/entries will no longer be automatically dropped because a strong reference may always exist to the keys. (This can be avoided by wrapping the value object in a WeakReference, so that both keys and values are weakly-referenced when in the WeakHashMap)

Example use of WeakHashMap

Here is a brief, albeit contrived example of WeakHashMap at work:

// SampleKey is just an object that holds a single int. (Use instead of
// Integer, since Integer overrides equals() and hashcode())
SampleKey key = new SampleKey(42);
SampleObject value = new SampleObject("Sample Value");

final WeakHashMap<SampleKey, SampleObject> weakHashMap = new WeakHashMap<SampleKey, SampleObject>();
weakHashMap.put(key, value);

// At this point, we still have a strong reference to the key. Thus, even
// though the key is weakly-referenced by the WeakHashMap, nothing will
// be automatically removed even if we give a hint to the GC.
System.gc();

LOGGER.debug(weakHashMap.size()); // Will still be '1'.
LOGGER.debug(weakHashMap.get(key)); // Will still be 'Sample Value'.

// Now, we if set the key to null, the entry in weakHashMap will eventually
// disappear. Note that the number of times we have to 'kick' the GC
// before the entry disappears may be different on each run depending
// on the JVM load, memory usage, etc.
key = null;
int count = 0;
while(0 != weakHashMap.size())
{
  ++count;
  System.gc();
}
LOGGER.debug("Took " + count + " calls to System.gc() to result in weakHashMap size of : " + weakHashMap.size());

Finishing up

In an upcoming article, I plan on covering the other types of references (soft and phantom) as well as the associated Reference classes in Java. I wanted to keep this post brief so that it provided a basic understanding of the situation.

Changes/Fixes

• 2011-04-10: Fixed numerous incorrect usages of the term “dereference”. Thanks to Ranjit for the explanation.

References

1. Package java.lang.ref
2. WeakHashMap
3. Understanding Weak References

As reported a little while ago, Sun plans to launch their own app store for Java-based desktop applications. With Apple’s App Store having passed the one-billion download mark last month and thus proving to be a roaring success, it’s clear that Sun, like many others, is hoping to imitate and perhaps improve on the effort. But does it make sense?

Mobile vs. Desktop

Following in the steps of RIM, Google’s Android, Palm and others, Sun hopes to follow the same pattern of success that Apple has enjoyed with their App Store. However, things are a bit different here. All the current App Store competitors have a separate mobile platform with which to compete against Apple. In general, this business model makes sense because there are few other easy ways to get software onto the devices, so a centralized app store of sorts makes sense.

In Apple’s case, they intended from the beginning to have the App Store be the only way to get software onto their devices. This closed-model and high level of control, which Apple is known for, is what helped make the App Store so popular. It was also very easy to use, and provided functionality not available elsewhere. Other mobile app stores aim to emulate this “app store tie-in”, hoping to make their respective app stores the primary place to get new software for your device, thus providing the companies with a steady source of revenue.

On the desktop, thing’s aren’t so clear. For the most part, people are already able to freely and easily download/purchase and install software, either through their web browser or through content delivery systems like Steam. Sun will have some real competition on their hands because of this, and unless they can create the ecosystem to spawn “killer apps”, people won’t be flocking to it in droves. Currently, there are just too many options for getting new software onto your desktop, thanks to the openness of the system, and this will be a real problem for Sun when it comes to gaining any significant market share in this area.

Furthermore, as noted in the article, there haven’t been very many compelling Java apps, save for Eclipse and Azureus. (I only use the former) Java on the desktop just hasn’t been as much of a success as Sun would’ve hoped for, mainly because Java desktop applications haven’t had the same consistent look & feel that native OS applications have offered, with some notable exceptions like Eclipse. While Java has gained much acceptance on the server side, it may have to settle for this before looking to gain significant acceptance on the desktop anytime soon.

App Store Hype?

It should be also noted that while the Apple’s App Store has been a roaring success for the company itself, it seems that it’s not as much of a success for the vast majority of developers out there. Like most markets with low-barriers to entry, (blogging for profit, startups, etc.) the distribution of revenue seems to follow a long-tail model, with very few developers making a lot of money, with the rest only making a fraction of that.

This was highlighted by a recent TechCrunch article about the reality of the App Store, which referenced an original article by an App Store developer. In that article, the developer revealed that because there were so many apps available for download, it didn’t take much to get into the top 100 for a given category:

In order to place #34 on the social networking charts, you need 30-35 downloads a day. At the standard app store pricing of .99, and after Apple takes its cut, that means your app needs to bring in a little over $20 a day to chart at that position. And social networking is a popular category.

Thus, it would appear that App Store not as profitable for developers as the hype or large success stories would suggest. You may have a compelling app that is nicely done, but it may only make a marginal amount instead of the six-figure amounts being seen by some of the most successful apps. If this is the case with even a successful implementation like Apple’s App Store, how does this bode for Sun, which hasn’t even proven that their Java app store can enjoy similar success? Indeed, it appears that they will have a hard time attracting developers to their app store platform.

Mind you, this hasn’t stopped people from even speculating about an Ubuntu app store, though it’s hard to see this business model working well with the FOSS model of Ubuntu. Nevertheless, it wouldn’t be unrealistic, given that Canonical is trying to make Android apps run on Ubuntu, possibly allow for Android’s app store to make an entrance to the desktop through this backdoor method.

If you’re using Maven to manage your project’s build and dependencies, you may have encountered some problems when trying to include the latest version of log4j as a dependency. Specifically, log4j 1.2.15 depends on some artifacts that are not available in the central Maven repository due to licensing issues, and thus when you try to build a project that depends on this version of log4j, you may not be able to download the artifacts and your build will fail.

We could download and install these artifacts to the local repository, if we really needed them. But in most cases, they’re not needed and thus you won’t want your project relying on these artifacts just because some parts of log4j do. Thus, we need to exclude them.

The problem: Not really needed

The issue is going from log4j 1.2.14 to 1.2.15, the developers added some features which required some dependencies on various sun and javax packages. However in most cases, you won’t be using this extra functionality, but if you just include log4j 1.2.15, this will cause your project to require those extra artifacts as per the transitive dependency rule.

Because some of these artifacts are not available from the central Maven repository, due to licensing issues, they will not be automatically installed to your local repository. So, if you attempt to run mvn install, you’re likely to encounter this sort of error:

[INFO] Unable to find resource 'com.sun.jdmk:jmxtools:jar:1.2.1' in repository central (http://repo1.maven.org/maven2)
[INFO] Unable to find resource 'javax.jms:jms:jar:1.1' in repository central (http://repo1.maven.org/maven2)
[INFO] Unable to find resource 'com.sun.jmx:jmxri:jar:1.2.1' in repository central (http://repo1.maven.org/maven2)
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Failed to resolve artifact.

Missing:
----------
1) com.sun.jdmk:jmxtools:jar:1.2.1
...
2) javax.jms:jms:jar:1.1
...
3) com.sun.jmx:jmxri:jar:1.2.1
...
----------
3 required artifacts are missing.

And if you’re using Eclipse, and have used the Maven Eclipse plugin command (mvn eclipse:eclipse) to generate the project settings, you’ll have the problem of Eclipse not being able to find the artifacts references on the build path, resulting in an error like so:

This causes a big problem as it essentially prevents you from building your project. You could download and install these artifacts to your local repository, but since they’re not really needed, we should exclude them from the dependency list for log4j.

Excluding dependencies

Thankfully, Maven make it easy to exclude dependencies from a certain project. Looking at the log4j 1.2.15 POM file (you may have to select “View Source”), we can see several dependencies that weren’t there in the previous release. These are likely to support new features, and aren’t needed for the most common uses of log4j. Here are the actual dependencies for log4j 1.2.15:

<dependencies>
  <dependency>
    <groupId>javax.mail</groupId>
    <artifactId>mail</artifactId>
    <version>1.4</version>
  </dependency>
  <dependency>
    <groupId>javax.jms</groupId>
    <artifactId>jms</artifactId>
    <version>1.1</version>
  </dependency>
 <dependency>
    <groupId>com.sun.jdmk</groupId>
    <artifactId>jmxtools</artifactId>
    <version>1.2.1</version>
  </dependency>
 <dependency>
    <groupId>com.sun.jmx</groupId>
    <artifactId>jmxri</artifactId>
    <version>1.2.1</version>
  </dependency>
 <dependency>
    <groupId>oro</groupId>
    <artifactId>oro</artifactId>
    <version>2.0.8</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>3.8.1</version>
    <scope>test</scope>
  </dependency>
</dependencies>

We only need to exclude the first four, and not the last two, since they have a scope of test, and won’t be included anyways. To exclude these dependencies, add the log4j 1.2.15 dependency as show below.

<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>1.2.15</version>
  <scope>provided</scope>
  <exclusions>
    <exclusion>
      <groupId>javax.mail</groupId>
      <artifactId>mail</artifactId>
    </exclusion>
    <exclusion>
      <groupId>javax.jms</groupId>
      <artifactId>jms</artifactId>
    </exclusion>
    <exclusion>
      <groupId>com.sun.jdmk</groupId>
      <artifactId>jmxtools</artifactId>
    </exclusion>
    <exclusion>
      <groupId>com.sun.jmx</groupId>
      <artifactId>jmxri</artifactId>
    </exclusion>
  </exclusions>
</dependency>

This tells Maven not to add those artifacts to the classpath and so they won’t be needed to build your project anymore. Note that you have to explicitly exclude each one, there is no way to exclude all of the dependencies for a project, but there is a feature request for such an ability.

If you’re using Eclipse, after running mvn eclipse:clean/mvn eclipse:eclipse, you should have the build path properly setup without any missing artifacts:

Everything should now work!

Transitive Dependencies and Exclusions

The issue here is that the log4j 1.2.15 POM file probably should have marked these dependencies as optional, which would have had the same effect as having to exclude them on every project that referenced that version of log4j. What does an optional dependency mean? The Maven website has a pretty good explanation.

Basically, if you have a large project that requires a lot of dependencies, but the “core” features only require a subset of those dependencies, you may want to mark the others as “optional” so as not to burden any projects that reference yours. Your project will still need all of the dependencies to build, but other projects that reference yours will only need the optional dependencies if they are using the additional features. In this case, they’ll have to explicitly add those dependencies, as the transitive dependency rule won’t kick in for “optional” ones.

Also worthy to note: exclusions are done on a per-dependency basis. This means that the dependencies that we excluded from log4j are only excluded from the log4j scope. This has the effect of not globally excluding those dependencies. So, for example, if we added another dependency that did really require the javax.jms/jms artifact, it would not be prevented from being added. Furthermore, if we wanted, we could manually add a dependency to our own list for that JMS artifact, and it would show up as normal.

References

1. Exclude Transitive Dependencies
2. Maven and Excluding Transitive Dependencies

When Google launched App Engine about one year ago, many were excited about their expected move into the cloud computing space, but at the same time, dismayed that it only supported Python, a language seemingly favoured at the Mountain View-headquartered company.

However, Google was adamant that they would begin supporting new languages and began taking requests on their issue tracker for what language to support next. So, it was no surprise that support for Java was announced last week as part of an “Early Look” at the feature.

I qualified for signup!

The Google App Engine page indicated that access would be limited to the first 10,000 developers who signed up, but I was able to get approved for access after signing up over the weekend, even though Java support was launched last Wednesday on April 8th. Google has since expanded the “early Look” to accommodate a total of 25,000 developers, so be sure to sign up if you can!

The choice of Java as the next language to support was no big surprise, as indicated by many articles speculating on the matter.

Furthermore, Java is one of the most popular languages out there, both outside and inside Google, making it a logical choice. This is seen by the numerous Java projects Google has created/supported, such as Google Web Toolkit and Google Guice. Additionally, Java is second to none when it comes to a viable developer ecosystem, which has resulted in great open source projects such as JBoss, the Apache Commons collections, and other libraries/frameworks that have provided great tools to any Java developer, allowing them focus on developing their application instead of worrying about lower-level problems. There are also a great many websites out there running on J2EE, such as LinkedIn and numerous corporate websites.

App Engine as a enabler for free/cheap Java hosting

However, this hasn’t translated into the availability of cheap web hosting for J2EE/Java development. Typically, web hosting for a shared-server solution will be only a few dollars per month if you’re using a scripting/interpreted language like PHP, Python or Perl. If you want to develop Java web applications though, you’ll likely have to pay much more due to the complexity and overhead of the hosting provider having to run a Java VM.

As outlined in this somewhat overly optimistic article, Google’s support for Java in App Engine has the potential to change the game by offering a cheap/low-cost, or in most cases, a free solution to allow developers to begin creating J2EE/Java-based web applications. This will have the effect of encouraging greater adoption of J2EE as a server-side solution. In my opinion, the high cost of Java web hosting has indeed hampered its adoption by the community, as compared to alternatives like PHP, Python and Ruby.

Hello, World

As for me, I’m currently devoting my free time to experimenting on App Engine using Java. So far, the documention and tutorial seem to be fairly well-written and easy to follow, and for the most part App Engine is using the standard Java APIs for providing most of their service functionality. Furthermore, Google has made an excellent Eclipse plugin for App Engine Java support, which provides not only the SDK, but also a built-in development server/Jetty-based servlet container for local testing, but also the tools necessary to upload your application to Google’s servers directly from the IDE. Another reason why Eclipse is the best IDE out there.

I hope to have something working within a few days, at least to test the service and play around with its capabilities. Overall, I’m very impressed!

A bit of background

However, what I want to discuss today relates to certificate chains. At the top of every certificate chain is a root CA, whose certificate is self-signed. This sort of certificate can be considered a “God certificate” because it essentially says, “Trust me, because I say so”. As you can imagine, that’s not much of an argument for trusting someone, so that is why your browser has a list of default root CAs that it automatically trusts.

Some default trusted CAs in Firefox.

These root CAs are owned and operated by companies that are in the business of issuing certificates to other people for use on their servers. They have been added to the default trusted list of most browsers so that an end user doesn’t need to manually add all of them; doing so would be a usability nightmare. Essentially, these root CAs provide a trust anchor point, as not only are they trusted, but any certificates they issue will also be automatically trusted by the browser. Attempting to visit a HTTPS/SSL website that does not have a trusted certificates results in a nasty warning from modern browsers.

Rarely is the root CA certificate directly used for a web server, but instead it is used to sign or issue other certificates that are then used on a web server to confirm its identity and provide for secure end-to-end communication.

As you can imagine, operating a CA is an immense responsibility, so that is why these default lists have been setup: Essentially these companies have to vet entities that purchase certificates from them, to make sure they actually own the domain that they are trying to buy a certificate for, otherwise phishing would become too easy! Even so, these companies sometimes still have lapses due to use of outdated technologies and poor security practices, but that is another complicated issue for another day.

Issuing a certificate – An example

The act of issuing a certificate essential entails a CA using its public-private key pair to sign the contents of the certificate that is being issued. This ties the identity information in the certificate to its key pair and provides confirmation that the CA has affirmed the authenticity of the certificate, I.E., that it has truly issued this certificate and that it has not been forged.

Going back to a certificate chains, it was previously mentioned that the root CA certificate is at the top of the chain. Any certificates it issues are directly below it, so if these certificates are directly used on a web server, then the chain is of length two. However, certificate chains can be longer. If a certificate chain is longer than two, then this indicates the presence of an intermediate CA.

An intermediate CA is a CA that does not have a self-signed certificate but still has the capability to issue certificates that are trusted. For an example of the root CA to intermediate CA relationship, we can look at the certificate chain returned from https://mail.google.com:

The Root CA certificate from VeriSign, an X.509 v1 certificate.

Above we see the root CA certificate, a self-signed certificate created/issued by VeriSign. I’ve highlighted the fact that it is an X.509 version 1 certificate, which also means it doesn’t have any certificate extensions. This may not mean much right now, but we’ll get back to it soon.

The Intermediate CA certificate from Thawte, an X.509 v3 certificate.

This next shot shows the intermediate CA certificate that was issued by the root CA. This certificate has been issued to Thawte, a company coincidentally founded by Mark Shuttleworth, the South African man behind Canonical/Ubuntu. Thawte was acquired by VeriSign during the dot-com craze for US $575 million.

The “Basic Constraints” extension of the intermediate CA.

We can clearly see that this certificate is an X.509 version 3 certificate, meaning it does support certificate extensions. One of its extensions is a Basic Constraints extension, which has been set to signify that this is indeed a Certificate Authority. It also specifies one other parameter, which is the maximum number of intermediate CAs allowed beneath this one in the certificate chain hierarchy. Since this value is set to 0, this means this intermediate CA cannot issue any more CA certificates, but instead can only issue client certificates. Any attempt will to use a client certificate from this CA as a CA or signing certificate will fail, when consumed by a conforming client.

The client certificate

The last screenshot shows the client certificate, which is the last certificate in the chain. This is the certificate that is used by the server at mail.google.com to secure HTTPS traffic, and as we can see, it is also an X.509 v3 certificate (has extensions) and one of those extensions is the “Basic Constraints” extension. This time it is set to indicate that this is not a CA certificate.

The Basic Constraints of the client certificate, indicating it is not a CA certificate.

Basic Contraints – Why it’s needed

The “Basic Constraints” extension is one way for a CA to control the usage of the certificates it issues. For instance, when the root CA certificate in the example above issued the intermediate CA certificate, it set the Basic Constraints extension to signify that:

• The issued certificate is for a Certificate Authority, i.e. an intermediate CA.
• This certificate may not be used to create further CA certificates

In turn, the intermediate CA certificate was used to create the client certificate for mail.google.com, and it attached a Basic Constraints extension to signify that this certificate was not a CA certificate. By doing this, it was indicating that this certificate should not be used to sign/create further certificates.

This is necessary because of the how trust relationship works in X.509 PKI. Someone who trusts the root CA implicitly trusts all the intermediate CAs, and then by extension, all the client certificates issued by those intermediate CAs! (Note how this creates a single point-of-failure at the root CA as well)

If the CA could not control what the certificates it issued were used for, then someone could purchase a VeriSign certificate and use it to sign/create other certificates which would also be trusted by default! Clearly, this is not desirably from a security or financial point of view, if you are VeriSign. By using extensions such as the Basic Constraints one, the signing CA can enact fine-grained control over how the certificate is used. If the client certificate was used to sign another certificate, that certificate would be rejected by a browser that conformed to the X.509 v3 specifications.

The Grey Area

However, we run into a “grey area” of sorts when faced with a certificate that does not have a Basic Constraints extension. In this case, it is not indicated whether this is a CA certificate or not. How do the browsers respond in this scenario? In this case, it seems to depend on whether the CA is a root CA or an intermediate one.

For root CA certificates, it seems that the Basic Constraints extension is not required in order for the CA certificate to be viewed as valid from the browser’s point of view. (I’ve observed this in Firefox and Internet Explorer) This most likely stems from the fact that there are root CAs that were created and put into operation well before X.509 v3 extensions were in wide use. The VeriSign root CA in our example is an X.509 v1 certificate with a starting validity date of 1996-01-28.

However, for intermediate CAs, it seems that the Basic Constraints extension is required if you want things to work, at least in Firefox and Internet Explorer. I encountered this situation when working with a Private Root CA of my own. I was trying to create an intermediate CA (without any Basic Constraints extension) from this root CA, and was running into problems when using this intermediate CA to create client certificates. Any of the client certificates from the intermediate CA were being essentially rejected by the browser when attempting to visit the website they were being used for.

Because this was a “grey area”, the results were mixed. In Firefox, the site would load correctly, however when attempting to view the certificate chain (by double-clicking the lock icon in the lower right), only the client certificate could be viewed, not the fully certificate chain. Internet Explorer would show the full certificate chain but simply failed to load the page. Neither browser gave any indication as to why things were failing.

However, once I created an Intermediate CA with a Basic Constraints extension set to explicitly signify that this was indeed a CA, everything worked as expected. I don’t believe this is well-documented, though this is understandable since most people will not be creating their own Private CAs unless it’s for a very specialized purpose.

How to do this using the Bouncy Castle APIs

I’ve talked about the Bouncy Castle Java APIs before, and they have been an invaluable resource for simplifying the creation of a Private CA and for issuing certificates.

When issuing a certificate it’s fairly easy to set the Basic Constraints extension to indicate you want the certificate to be a CA certificate. First, take a look at this guide to under the fundamentals of certificate creation with the Bouncy Castle APIs, then look at this code fragment:

private static final int NUM_ALLOWED_INTERMEDIATE_CAS = 0;
...

// Construct the certificate.
final X509V3CertificateGenerator certGen = new X509V3CertificateGenerator();

...

// Need this extension to signify that this certificate is a CA and
// can issue certificates. (Extension is marked as critical)
certGen.addExtension( X509Extensions.BasicConstraints, true, new BasicConstraints(
  NUM_ALLOWED_INTERMEDIATE_CAS ) );

...

final X509Certificate intermediateCaCert = certGen.generate( signingCaPrivateKey, "SunRsaSign" );

By doing this you ensure that the intermediate CA certificate has the proper Basic Constraints extension to work correctly with modern web browsers.

Conclusion

I hope you found this helpful. Certainly if you’re here, you’ve been puzzled over the same issues that I struggled through!

References

1. X.509 Public Key Certificate and Certification Request Generation
2. OID 2.5.29.19 – Basic Constraints
3. OID Repository – basicConstraints(19)

First, we define a simple class with one instance method and one static method.

public class A
{
  public String getName()
  {
    return "I am A";
  }

  public static String getStaticName()
  {
    return "Statically A!";
  }
}

Then we extend that class with one that has identical method signatures.

public class B extends A
{
  // Note: @Override only makes sense for instance methods.
  // The annotation is not needed but makes for best practices, since if the
  // method DOES NOT override a superclass, a compile-time error will be
  // generated, limiting damage. (@Override was added in Java 1.5)
  @Override
  public String getName()
  {
    return "I am B";
  }

  public String onlyOnB()
  {
    return "Only available on B";
  }

  // Cannot @Override, generates a compile error. Instead, this methods
  // `hides` the one in the super class.
  public static String getStaticName()
  {
    return "Statically B!";
  }

  public static void main( String[] args )
  {
    A a = new A();
    B b = new B();

    A b_as_a = new B();
    A b_as_a_copied_from_reference = b;

    System.out.println(a.getName());
    System.out.println(a.getStaticName() + "\n");

    System.out.println(b.getName());
    System.out.println(b.getStaticName() + "\n");

    System.out.println(b_as_a.getName());
    System.out.println(b_as_a.getStaticName() + "\n");

    System.out.println(b_as_a_copied_from_reference.getName());
    System.out.println(b_as_a_copied_from_reference.getStaticName() + "\n");
  }
}

Sorry for the funky variable names in main(), but camelCase just didn’t look good. Anyway, can you guess the output of the program? It’s actually quite interesting:

I am A
Statically A!

I am B
Statically B!

I am B
Statically A!

I am B
Statically A!

The first two are fairly straightforward, since for variables a and b, the declared type matches the instantiated type, so there can be no doubt. But what happens when the declared type does not match the instantiated type, as in the second two examples?

The short answer is this: When instance methods are invoked, they will always be called on the instantiated type, regardless of the declared type. When static or class methods are invoked, they will be called on the declared type.

Declared type vs. instantiated type

You can think of the declared type as a “window” into the actual instantiated type. This “window” provides a view as to what methods are available for invocation and provides these hints to the compiler. This is why you cannot call a method that exists on an instantiated type unless it has been declared or exists on the declared type. (The use of interfaces provides the best example of this)

When an instance method is invoked, the JVM will then determine the runtime type of the variable and then call the appropriate method on that object. This is why for the last two examples, the output was I am B, even though the declared type was A. This is what allows polymorphism to work in Java.

However, when a static or class method is invoked, it will always be invoked from the declared type, regardless of what the runtime or instance type is. This is because static methods are per-class rather than per-instance and thus the exact method invoked can be determined at compile time from the declared type. This is why for the last two examples, the output is from the the method defined on class A, the declared type of the two variables.

What Sun has to say

Sun’s own tutorials on these subjects refers to this as hiding; that is, when a subclass static method has the same signature as one in a superclass, it hides it instead of overriding it. Override is a term reserved for instance methods only, and in fact, marking getStaticName() with the annotation @Override in class B results in a compile-time error.

However, to me, it’s far simpler to just remember that static methods are always invoked on the declared type, while instance methods will be invoked on the instantiated type. This provides an easy way to remember how things work in the JVM.

Pop Quiz

Consider the following code fragment. We create a MapContainer object, and then get the contained map, which is guaranteed to have a certain value associated with the key “today”. We then alter the value associated with this key, using our local reference to returned map. We then query the MapContainer object and get the contained map again. What is the value associated with the key “today” in this map?

final MapContainer mapContainer = new MapContainer();
final Map<String, String> map = mapContainer.getKeyValuePairs();

final String today = map.get("today");
assert null != today;
System.out.println(today);  // Returns the current date-time.

// Change the value using our local reference.
map.put("today", "tomorrow");

final Map<String, String> mapAgain = mapContainer.getKeyValuePairs();
System.out.println(mapAgain.get("today")); // What is output?

Don’t waste too much time on this problem, as it’s a trick question. The answer actually depends on the implementation of MapContainer. Depending on how it’s implemented, the second output could be unchanged from the first or be changed to the new value of “tomorrow”.

It’s all in the getters

Let’s take a look at the code for MapContainer.

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

public class MapContainer
{
  final private Map<String, String> keyValuePairs;

  public MapContainer()
  {
    this.keyValuePairs = new HashMap<String, String>();
    this.keyValuePairs.put("today", new Date().toString());
  }

  public Map<String, String> getKeyValuePairs()
  {
    return keyValuePairs;
  }
}

We have a simple constructor that initializes the keyValuePairs Map and adds one value for the current date-time. But the real ‘key’ (no pun intended) to solving the problem is looking at the getter for the field. As you can see, it simply returns a reference to the private field. Under this implementation, a caller is able to alter the contents of the private field/Map even though no public “set” methods are available. Why is this? For two reasons: In Java, objects are passed/returned by reference, and HashMap is a mutable object. Thus using this implementation, the second output from our original code fragment is “tomorrow”, since the caller has altered the contents of the Map through the returned reference.

Furthermore, the original reference returned from the getter is not independent either; if some other code were to call the get method on the MapContainer object and make changes to the Map, those changes would also be reflected in the original returned reference!

How can we “fix” this? We simply have to ensure that the getter for the field returns a reference to a copy of the private Map. This is easy since there is a constructor for HashMap that accepts an existing Map. Here’s the altered code:

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

public class MapContainer
{
  final private Map<String, String> keyValuePairs;

  public MapContainer()
  {
    this.keyValuePairs = new HashMap<String, String>();
    this.keyValuePairs.put("today", new Date().toString());
  }

  public Map<String, String> getKeyValuePairs()
  {
    return new HashMap<String, String>(keyValuePairs);
  }
}

With these changes, the private Map cannot be altered by a caller and thus the second output will remain changed in our first code fragment example.

To change, or not to change?

It should be noted that sometimes you may want to allow callers to alter the backing data structure that you return from a get method. For example, some of the data structures from the Java Collection Framework have getters that return references that can be used to alter the state of the original object. A good example is the entrySet() method of the HashMap object.

But in my opinion, these examples are the exception rather than the rule. In general, you do not want to allow callers to be able to alter the state of private fields directly since this violates information-hiding principles. If there is some change a caller needs to make to your object, it’s best accomplished through a set method since this allows you to control the changes and prevents unwanted/unexpected situations. If you do decide to allow callers to directly alter the state of private fields, it’s best to explicitly document this in the JavaDoc.

Mutability and safety

Note that in this example the field used was a HashMap object, which was mutable. If the field consisted of an immutable object, like a String, you would not have to worry about making a copy before returning it. This is because if the object is immutable, you do not have to worry about a caller changing its state because this is impossible to do! This is why immutable objects are much easier to deal with in multithreaded/concurrent environments.

Note that mutability has nothing to do with the final keyword in Java, contrary to this definition. Simply marking a field as “final” will not magically change a mutable object into an immutable one. As we saw earlier, whether an object is mutable or not depends entirely on its implementation, the details of which should be expressed in the JavaDoc for that class. The final keyword only ensures that you cannot reassign that field/variable to completely new reference or object; it does not ensure that you can’t change the state of the object already referenced.

One thing they handle well is the concept of certificate extensions. X.509 v3 certificates introduced the concept of these extensions, which are basically additional (potentially optional) fields containing information not contained in the older original X.509 specifications. Each extension is specified by an OID (Object Identifier); a good list of these extensions is available.

While it’s easy to read these extensions from an existing X.509 v3 certificate using the Bouncy Castle APIs it is a bit more involved to read these extensions from a Certificate Signing Request, or CSR; this is the data structure that is sent to a CA to request a certificate. The CA then reads the data from this and creates a signed certificate issued to the requester. In this guide I’ll present a brief way to extract X.509 extensions request from a CSR so that they may be included in the resulting issued certificate.

Code: The good stuff

Assuming you have added the Bouncy Castle JARs to your classpath, you should have access to the classes used here.

You must first have the CSR in the format of a Bouncy Castle data object, namely the PKCS10CertificationRequest. If all you have is the PEM-format of the CSR (i.e. Base64-encoded contents delimited by headers like ----- BEGIN CERTIFICATE REQUEST ----- and ----- END CERTIFICATE REQUEST -----) then you will need to convert this to the proper data structure using something like
PEMUtil from Commons-SSL like I have done below. (BC has a PEMUtil class as well, but it appears to be only for internal use)

// NOTE: Commons-SSL doesn't support generics.
final List pemItems = PEMUtil.decode( csrContent.getBytes() );

// Verify list isn't empty - uses Apache Commons Lang.
Validate.isTrue( !pemItems.isEmpty() );

// No support for generics, so have to cast. (Could have cast the entire List)
final PEMItem csrPemFormat = (PEMItem) pemItems.get( 0 );

// Verify the type.
Validate.isTrue( csrPemFormat.pemType.equals( "CERTIFICATE REQUEST" ),
  "This is not a CSR" );

final PKCS10CertificationRequest csr = new PKCS10CertificationRequest(
  csrPemFormat.getDerBytes() );

We first decode the PEM (Base64) CSR into List of PEMItems. Note that Commons-SSL doesn’t support generics, so you are going to get a cast warning somewhere in the code, no matter what. When calling getBytes() on the CSR string, you may want to specify the US-ASCII character set, since the no-arg method uses the platform default character set, which might give inconsistent results across different systems when converting from characters to bytes.

We then grab the first entry in the list, checking if it is a CSR. We can now convert this into the proper data structure by supplying the raw bytes (i.e. the DER-encoded format) to the constructor of PKCS10CertificationRequest.

The method to extract the X509Extensions structure from the PKCS10CertificationRequest is shown below.

   /**
    * Gets the X509 Extensions contained in a CSR (Certificate Signing Request).
    *
    * @param certificateSigningRequest the CSR.
    * @return the X509 Extensions in the request.
    * @throws CertificateException if the extensions could not be found.
    */
   X509Extensions getX509ExtensionsFromCsr(
         final PKCS10CertificationRequest certificateSigningRequest ) throws CertificateException
   {
      final CertificationRequestInfo certificationRequestInfo = certificateSigningRequest
            .getCertificationRequestInfo();

      final ASN1Set attributesAsn1Set = certificationRequestInfo.getAttributes();

      // The `Extension Request` attribute is contained within an ASN.1 Set,
      // usually as the first element.
      X509Extensions certificateRequestExtensions = null;
      for (int i = 0; i < attributesAsn1Set.size(); ++i)
      {
         // There should be only only one attribute in the set. (that is, only
         // the `Extension Request`, but loop through to find it properly)
         final DEREncodable derEncodable = attributesAsn1Set.getObjectAt( i );
         if (derEncodable instanceof DERSequence)
         {
            final Attribute attribute = new Attribute( (DERSequence) attributesAsn1Set
                  .getObjectAt( i ) );

            if (attribute.getAttrType().equals( PKCSObjectIdentifiers.pkcs_9_at_extensionRequest ))
            {
               // The `Extension Request` attribute is present.
               final ASN1Set attributeValues = attribute.getAttrValues();

               // The X509Extensions are contained as a value of the ASN.1 Set.
               // Assume that it is the first value of the set.
               if (attributeValues.size() >= 1)
               {
                  certificateRequestExtensions = new X509Extensions( (ASN1Sequence) attributeValues
                        .getObjectAt( 0 ) );

                  // No need to search any more.
                  break;
               }
            }
         }
      }

      if (null == certificateRequestExtensions)
      {
         throw new CertificateException( "Could not obtain X509 Extensions from the CSR" );
      }

      return certificateRequestExtensions;
   }

Basically, we get the certificate request info from the CSR structure and then extract attributes from it. Then, we loop through to find the attribute with the “Extension Request” OID.

After that, I make an assumption that the actual extensions are contained in the first value of the place of the ASN.1 Set that makes up the “Extensions Request” structure – not a big assumption, and in my testing I haven’t encountered a situation where this wasn’t the case. It’s worthwhile to keep in mind that ASN.1 often prescribes Set or multi-value structures in places where the underlying data can only be single-valued.

After running through that code, we’ll have either found the extensions, and be returning them in a X509Extensions structure, or an exception will be thrown. You could modify the code to return null if that suits your style or purpose better.

A few more notes

Once you have the X509Extensions structure you can use the extensions contained within to create/issue a certificate with them. Check out the Bouncy Castle Guide on Certificate Generation for more details.

Note that a CA is not required to use any of the extension requests present in a CSR – hence the name “requests”. It is entirely up to the CA to decide what extensions are appropriate, along with their values, for the certificates that it issues.

Code Review

The code is a little complicated and could probably benefit from some refactoring. However, a lot of the complexity derives from the fact that the X.509 and associated standards are quite complex themselves. This is a reflection on the vision that the designers of X.509 had for the future of the standard. However, the complexity of X.509 is another topic for another article.

I hope you found this article useful, as while I found lots of information for generating CSRs, information on parsing and working with them was a little sparse. Please feel free to leave your comments below!