Wrapping ReCaptcha in a Custom JSF Component (With Facelets Support)

A couple of days ago I decided to protect a form in a web application of ours with a CAPTCHA and, after spending some hours evaluating the available options, I chose Google's reCaptcha.

Since the form I had to protect is presented by a Java EE 6 Web Module using Facelets, I decided that the best course of action was:

• Using a reCaptcha Java library, as suggested by the reCaptcha developer's documentation.
• Wrapping the library functionality into a custom JSF component, so that it could be easily reused in any Java EE web application.
• Writing a Facelets tag library descriptor so that I could use my component from both JSP and Facelets pages.

Please beware that, for the sake of clarity, some error management and logging code has been omitted from the examples below. 

reCaptcha Java Library

The contributed reCaptcha Java library described in the reCaptcha developer's documentation is really easy to use but it does not offer the adequate tools that a Java EE developer needs. To summarize, it requires you to add Java scriptlets into a JSP page, something awful to see and awkward to maintain.

With this code you can create your reCaptcha instance:

ReCaptcha c = ReCaptchaFactory.newReCaptcha("your_public_key", "your_private_key", false);

and with the createRecaptchaHtml method you can have it create the required HTML to show the reCaptcha widget:

c.createRecaptchaHtml(null, null);

Once the client submits the form where the widget is shown, the following piece of code can be used to determine whether the value introduced by the user is correct or not:

String remoteAddr = request.getRemoteAddr();

ReCaptchaImpl reCaptcha = new ReCaptchaImpl();

reCaptcha.setPrivateKey("your_private_key");

String challenge = request.getParameter("recaptcha_challenge_field");

String uresponse = request.getParameter("recaptcha_response_field");

ReCaptchaResponse reCaptchaResponse = reCaptcha.checkAnswer(remoteAddr, challenge, uresponse);

reCaptchaResponse.isValid();

No doubt a custom tag would be much easier to use.

A reCaptcha Custom Tag

We would like to be able to write something like this in our pages, instead:

<rc:recaptcha ... />

The required parameters that the library needs are the two reCaptcha keys, so our custom tag would end up like:

<rc:recaptcha id="..." publicKey="..." privateKey="..." />

The basics files you need to build a custom JSF components are:

• The component implementation file.
• The component's renderer.
• The component's tag handler.

The Component

Since users will input data through the component, our component class will extend the JSF UIInput class. Although we won't ever read what the user inputs, we use this class so that we can take advantage of the JSF infrastructure during the validation phase.

Into our component skeleton, we create the setter methods so that the reCaptcha keys can be configured:

public class RecaptchaComponent extends UIInput {

  static final String RecaptchaComponent_FAMILY = "RecaptchaComponentFamily";

  private String publicKey;

  private String privateKey;

  @Override

  public final String getFamily() {

    return RecaptchaComponent_FAMILY;

  }

  public void setPublicKey(String s) {

    publicKey = s;

  }

  public void setPrivateKey(String s) {

    privateKey = s;

  }

  public String getPublicKey() {

    if (publicKey != null)

      return publicKey;

       

    ValueExpression ve = this.getValueExpression("publicKey");

    if (ve != null) {

      return (String)ve.getValue(getFacesContext().getELContext());

    } else {

      return publicKey;

    }

  }

  public String getPrivateKey() {

    if (privateKey != null)

      return privateKey;

    ValueExpression ve = this.getValueExpression("privateKey");

    if (ve != null) {

      return (String)ve.getValue(getFacesContext().getELContext());

    } else {

      return privateKey;

    }

  }

}

As you may notice, since we want to accept EL expressions to set the reCaptcha keys, the corresponding getters take that into account and retrieve the value from a value expression if the user didn't use a literal.

The Renderer

The component renderer is pretty simple, since the HTML will be produced by the reCaptcha Java library:

public class RecaptchaComponentRenderer extends Renderer {

  static final String RENDERERTYPE = "RecaptchaComponentRenderer";

  @Override

  public void decode(FacesContext context,

    UIComponent component) {

    if (component instanceof UIInput) {

      UIInput input = (UIInput) component;

      String clientId = input.getClientId(context);

      Map requestMap =
        context.getExternalContext().getRequestParameterMap();

      String newValue = (String) requestMap.get(clientId);

      if (null != newValue) {

        input.setSubmittedValue(newValue);

      }

    }

  }

  @Override

  public void encodeBegin(FacesContext ctx,

    UIComponent component) throws IOException {

  }

  @Override

  public void encodeEnd(FacesContext ctx,

    UIComponent component)

    throws IOException {

   

    if (component instanceof RecaptchaComponent) {       

      RecaptchaComponent rc = (RecaptchaComponent) component;

      String publicKey = rc.getPublicKey();

      String privateKey = rc.getPrivateKey();

      if (publicKey == null || privateKey == null) {

        throw new IllegalArgumentException("reCaptcha keys cannot be null. This is probably a component bug.");

      }

      ReCaptcha c = ReCaptchaFactory.newReCaptcha(publicKey, privateKey, false);

      String createRecaptchaHtml = c.createRecaptchaHtml(null, null);

      ResponseWriter writer = ctx.getResponseWriter();

      writer.write(createRecaptchaHtml);

    }

  }

}

The Component Tag Handler

You can think of the tag handler as the intermediary between the custom tag you use in the page and the component class. It is basically responsible for getting and setting the component's properties.

In this case, we will need the two setters to retrieve the reCaptcha keys and they must accept a ValueExpression object. When the tag handler sets the component's properties, it will check if the value are literals or value expressions and act accordingly:

• If they're literals, it will set them into the components fields.
• If they're value expressions, it will store them into the map of value expressions of the component for later evaluation (as seen in the component's code).

The code will be such as:

public class RecaptchaComponentTag extends UIComponentELTag {
  private ValueExpression publicKey;
  private ValueExpression privateKey;

  public void setPublicKey(ValueExpression s) {
    publicKey = s;
  }

  public void setPrivateKey(ValueExpression s) {
    privateKey = s;
  }

  @Override
  public String getComponentType() {
    return RecaptchaComponent.RecaptchaComponent_FAMILY;
  }

  @Override
  public String getRendererType() {
    return RecaptchaComponentRenderer.RENDERERTYPE;
  }

  @Override
  protected void setProperties(UIComponent component) {
    super.setProperties(component);
 
    if (component instanceof RecaptchaComponent) {
      RecaptchaComponent c = (RecaptchaComponent) component;

      if (publicKey != null) {
        if (publicKey.isLiteralText()) {
          c.setPublicKey(publicKey.getExpressionString());
        } else {
          c.setValueExpression("publicKey", publicKey);
        }
      }

      if (privateKey != null) {
        if (privateKey.isLiteralText()) {                
          c.setPrivateKey(privateKey.getExpressionString());
        } else {
          c.setValueExpression("privateKey", privateKey);
        }
      }
    }
  }
}

The Validator

When the user submits the form, we need to check if the value he entered was correct or not. JSF input components undergo a validation phase during their life cycle, so that we can perform the reCaptcha validation during this phase.

To do that, we need an instance of the Validator class and implement the validate method accordingly:

public class RecaptchaValidator implements Validator {

  public void validate(FacesContext context, UIComponent component, Object value) throws ValidatorException {
    HttpServletRequest request = (HttpServletRequest) context.getExternalContext().getRequest();

    if (component instanceof RecaptchaComponent) {
      RecaptchaComponent c = (RecaptchaComponent)component;
      String remoteAddr = request.getRemoteAddr();
      ReCaptchaImpl reCaptcha = new ReCaptchaImpl();
      reCaptcha.setPrivateKey(c.getPrivateKey());

      String challenge =
        request.getParameter("recaptcha_challenge_field");
      String uresponse =
        request.getParameter("recaptcha_response_field");
      ReCaptchaResponse reCaptchaResponse =
        reCaptcha.checkAnswer(remoteAddr, challenge, uresponse);

      if (!reCaptchaResponse.isValid()) {
        throw new ValidatorException(
          new FacesMessage(FacesMessage.SEVERITY_ERROR, "Invalid captcha", "Invalid captcha"));
      }
    }
  }
}

As it can be seen, we just use the reCaptcha Java library code to perform the check.

Use the Validator Into the Component

To use the validator as a default validator, we can simply add it to the list of validator of our component during the component creation:

public RecaptchaComponent() {
    super();
    addValidator(new RecaptchaValidator());

}

Also, we need to override the UIInput validate method so that our validator be called;

@Override

public void validate(FacesContext ctx) {
  Validator[] validators = getValidators();
  for (Validator v : validators) {
    try {
      v.validate(ctx, this, null);
    } catch (ValidatorException ex) {
      setValid(false);
      FacesMessage message = ex.getFacesMessage();
      if (message != null) {
        message.setSeverity(FacesMessage.SEVERITY_ERROR);
        ctx.addMessage(getClientId(ctx), message);
      }
    }

    super.validate(ctx);
  }

}

The JSF Configuration File

We now must tell JSF about this new component. Since we distribute it into a standalone JAR, we add a faces-config.xml file into the META-INF directory of the archive with this content:

<?xml version='1.0' encoding='UTF-8'?>

<faces-config version="2.0"
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd">
  <component>
    <component-type>RecaptchaComponentFamily</component-type>
    <component-class>es.trafico.jsf.component.RecaptchaComponent</component-class>
  </component>

  <render-kit>
    <renderer>
      <description>Renderer.</description>
      <component-family>RecaptchaComponentFamily</component-family>
      <renderer-type>RecaptchaComponentRenderer</renderer-type>
      <renderer-class>
        es.trafico.jsf.component.RecaptchaComponentRenderer
      </renderer-class>
    </renderer>
  </render-kit>

  <validator>
    <validator-id>recaptchaValidator</validator-id>
    <validator-class>
      es.trafico.jsf.component.RecaptchaValidator
    </validator-class>
  </validator>
  
</faces-config>

The Tag Library Descriptor

To be able to use our new custom component in our JSP pages, we need a tag library descriptor. Since we're packaging our custom component in a standalone JAR file so that it can be used in all our applications, the tag library descriptor must be placed into the META-INF directory of the archive.

Our taglib.tld file is like this:

<?xml version="1.0" encoding="UTF-8"?>
<taglib version="2.1" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-jsptaglibrary_2_1.xsd">

  <tlib-version>1.0</tlib-version>
  <short-name>ReCaptcha-Library</short-name>
  <uri>http://www.reacciona.es/rc</uri>

  <tag>
    <name>recaptcha</name>
    <tag-class>
      es.trafico.jsf.component.RecaptchaComponentTag
    </tag-class>
    <body-content>empty</body-content>
    <attribute>
      <name>id</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
    </attribute>
    <attribute>
      <name>publicKey</name>
      <required>true</required>
      <deferred-value>
        <type>java.lang.String</type>
      </deferred-value>
    </attribute>
    <attribute>
      <name>privateKey</name>
      <required>true</required>
      <deferred-value>
        <type>java.lang.String</type>
      </deferred-value>
    </attribute>

  </tag>
</taglib>

Using The Component

You can now use your new tag library in your JSP page adding this directory at the beginning of the page:

<%@taglib prefix="rc" uri="http://www.reacciona.es/rc"%>

You can now add your custom component instances into your JSP pages (with JSF) this way:

<f:view>
...
  <h:form>
    <rc:recaptcha id="rc"
      publicKey="#{yourBean.publicKey}"
      privateKey="#{yourBean.privateKey}"/>
    <h:message for="rc" />
  </h:form>
</f:view>

In this example, we use a value expression to set both the reCaptcha keys using two properties of a managed bean of yours. This way, you won't hardcode any parameter into your pages.

Using the Custom Component With Facelets

You won't be able to use the custom component into a Facelets page until you write a Facelets tag library descriptor. You might be wondering why so many indirection layers: Facelets is designed to be more flexible than JSP and its tag descriptors reflect this design decision. Instead of having to describe your component down to the smallest detail, Facelets lets your just declare its existence and, for example, will set attributes at runtime, inspecting the component and tag classes.

A basic Facelets tag library descriptor for the component is the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE facelet-taglib PUBLIC
  "-//Sun Microsystems, Inc.//DTD Facelet Taglib 1.0//EN"
  "http://java.sun.com/dtd/facelet-taglib_1_0.dtd">

<facelet-taglib>

  <namespace>http://www.reacciona.es/rc</namespace>
  <tag>
    <tag-name>recaptcha</tag-name>
    <component>
      <component-type>RecaptchaComponentFamily</component-type>
      <renderer-type>RecaptchaComponentRenderer</renderer-type>
    </component>
  </tag>
</facelet-taglib>

Please note that both the component and the renderer type are just the identifiers we declared in the JSF configuration file.

We can now use the custom component into a Facelets page adding the following namespace into the html tag at the beginning of the page:

xmlns:rc="http://www.reacciona.es/rc"

The syntax to add the component is the same syntax that we used in the JSP example.

Java Generics Tutorial - Part II - Subtyping

Part I - The Basics
Part II - Subtyping
Part III - Wildcards
Part IV - Bounded Type Variables

In Part I we quickly explored the basics of Java generics. In this blog post we will explore how generic types behave in the Java type system.

Subtypes

In Java, as in other object-oriented typed languages, hierarchies of types can be built:

In Java, a subtype of a type T is either a type that extends T or a type that implements T (if T is an interface) directly or indirectly. Since "being subtype of" is a transitive relation, if a type A is a subtype of B and B is a subtype of C, then A will be a subtype of C too. In the figure above:

• FujiApple is a subtype of Apple.
• Apple is a subtype of Fruit.
• FujiApple is a subtype of Fruit.

Every Java type will also be subtype of Object.

Every subtype A of a type B may be assigned to a reference of type B:

Apple a = ...;

Fruit f = a;

Subtyping of Generic Types

If a reference of an Apple instance can be assigned to a reference of a Fruit, as seen above, then what's the relation between, let's say, a List<Apple> and a List<Fruit>? Which one is a subtype of which? More generally, if a type A is a subtype of a type B, how does C<A> and C<B> relate themselves?

Surprisingly, the answer is: in no way. In more formal words, the subtyping relation between generic types is invariant.

This means that the following code snippet is invalid:

List<Apple> apples = ...;

List<Fruit> fruits = apples;

and so does the following:

List<Apple> apples;

List<Fruit> fruits = ...;

apples = fruits;

But why? Is an apple is a fruit, a box of apples (a list) is also a box of fruits.

In some sense, it is, but types (classes) encapsulate state and operations. What would happen if a box of apples was a box of fruits?

List<Apple> apples = ...;

List<Fruit> fruits = apples;

fruits.add(new Strawberry());

If it was, we could add other different subtypes of Fruit into the list and this must be forbidden.

The other way round is more intuitive: a box of fruits is not a box of apples, since it may be a box (List) of other kinds (subtypes) of fruits (Fruit), such as Strawberry.

Is It Really a Problem?

It should not be. The strongest reason for a Java developer to be surprised is the inconsistency between the behavior of arrays and generic types. While the subtyping relations of the latter is invariant, the subtyping relation of the former is covariant: if a type A is a subtype of type B, then A[] is a subtype of B[]:

Apple[] apples = ...;
Fruit[] fruits = apples;

But wait! If we repeat the argument exposed in the previous section, we might end up adding strawberries to an array of apples:

Apple[] apples = new Apple[1];
Fruit[] fruits = apples;
fruits[0] = new Strawberry();

The code indeed compiles, but the error will be raised at runtime as an ArrayStoreException. Because of this behavior of arrays, during a store operation, the Java runtime needs to check that the types are compatible. The check, obviously, also adds a performance penalty that you should be aware of.

Once more, generics are safer to use and "correct" this type safety weakness of Java arrays.

In the case you're now wondering why the subtyping relation for arrays is covariant, I'll give you the answer that Java Generics and Collections give: if it was invariant, there would be no way of passing a reference to an array of objects of an unknown type (without copying every time to an Object[]) to a method such as:

void sort(Object[] o);

With the advent of generics, this characteristics of arrays is no longer necessary (as we'll see in the next part of this post) and should indeed by avoided.

Next Steps

In the next post we will see how generic wildcards introduce both covariant and contravariant subtyping relations with generics.

Part I - The Basics
Part II - Subtyping
Part III - Wildcards
Part IV - Bounded Type Variables

Java Generics Tutorial - Part III - Wildcards

Part I - The Basics

Part II - Subtyping

Part III - Wildcards

Part IV - Bounded Type Variables

The previous posts introduced us to the basics of Java generics y their subtyping relations. In this posts we'll introduce wildcards and how can covariant and contravariant subtyping relations be established with generics.

Wildcards

As we've seen in the previous post, the subtyping relation of generic types is invariant. Sometimes, though, we'd like to use generic types in the same way we can use ordinary types:

• Narrowing a reference (covariance).
• Widening a reference (contravariance) 

Covariance

Let's suppose, for example, that we've got a set of boxes, each one of a different kind of fruit. We'd like to be able to write methods that could accept a any of them. More formally, given a subtype A of a type B, we'd like to find a way to use a reference (or a method parameter) of type C<B> that could accept instances of C<A>.

To accomplish this task we can use a wildcard with extends, such as in the following example:

List<Apple> apples = new ArrayList<Apple>();
List<? extends Fruit> fruits = apples;

? extends reintroduces covariant subtyping for generics types: Apple is a subtype of Fruit and List<Apple> is a subtype of List<? extends Fruit>.

Contravariance

Let's now introduce another wildcard: ? super. Given a supertype B of a type A, then C<B> is a subtype of C<? super A>:

List<Fruit> fruits = new ArrayList<Fruit>();

List<? super Apple> = fruits;

How Can Wildcards Be Used?

Enough theory for now: how can we take advantage of these new constructs?

? extends

Let's go back to the example we used in Part II when introducing Java array covariance:

Apple[] apples = new Apple[1];
Fruit[] fruits = apples;
fruits[0] = new Strawberry();

As we saw, this code compiles but results in a runtime exception when trying to add a Strawberry to an Apple array through a reference to a Fruit array.

Now we can use wildcards to translate this code to its generic counterpart: since Apple is a subtype of Fruit, we will use the ? extends wildcard to be able to assign a reference of a List<Apple> to a reference of a List<? extends Fruit> :

List<Apple> apples = new ArrayList<Apple>();

List<? extends Fruit> fruits = apples;

fruits.add(new Strawberry());

This time, the code won't compile! The Java compiler now prevents us to add a strawberry to a list of fruits. We will detect the error at compile time and we won't even need any runtime check (such as in the case of array stores) to ensure that we're adding to the list a compatible type. The code won't compile even if we try to add a Fruit instance into the list:

fruits.add(new Fruit());

No way. It comes out that, indeed, you can't put anything into a structure whose type uses the ? extends wildcard.

The reason is pretty simple, if we think about it: the ? extends T wildcard tells the compiler that we're dealing with a subtype of the type T, but we cannot know which one. Since there's no way to tell, and we need to guarantee type safety, you won't be allowed to put anything inside such a structure. On the other hand, since we know that whichever type it might be, it will be a subtype of T, we can get data out of the structure with the guarantee that it will be a T instance:

Fruit get = fruits.get(0);

? super

What's the behavior of a type that's using the ? super wildcard? Let's start with this:

List<Fruit> fruits = new ArrayList<Fruit>();

List<? super Apple> = fruits;

We know that fruits is a reference to a List of something that is a supertype of Apple. Again, we cannot know which supertype it is, but we know that Apple and any of its subtypes will be assignment compatible with it. Indeed, since such an unknown type will be both an Apple and a GreenApple supertype, we can write:

fruits.add(new Apple());

fruits.add(new GreenApple());

If we try to add whichever Apple supertype, the compiler will complain:

fruits.add(new Fruit());

fruits.add(new Object());

Since we cannot know which supertype it is, we aren't allowed to add instances of any.

What about getting data out of such a type? It turns out that you the only thing you can get out of it will be Object instances: since we cannot know which supertype it is, the compiler can only guarantee that it will be a reference to an Object, since Object is the supertype of any Java type.

The Get and Put Principle or the PECS Rule

Summarizing the behavior of the ? extends and the ? super wildcards, we draw the following conclusion:


Use the ? extends wildcard if you need to retrieve object from a data structure.
Use the ? super wildcard if you need to put objects in a data structure.
If you need to do both things, don't use any wildcard.

This is what Maurice Naftalin calls The Get and Put Principle in his Java Generics and Collections and what Joshua Bloch calls The PECS Rule in his Effective Java.

Bloch's mnemonic, PECS, comes from "Producer Extends, Consumer Super" and is probably easier to remember and use.

Next Steps

In the next post (coming soon), we will put all together in some examples to clarify how generics can be used to help us write cleaner, clearer and more type safe code.

Part I - The Basics
Part II - Subtyping
Part III - Wildcards
Part IV - Bounded Type Variables

Java Generics Tutorial - Part I - Basics

Generics is a Java feature that was introduced with Java SE 5.0 and, few years after its release, I swear that every Java programmer out there not only heard about it, but used it. There are plenty of both free and commercial resources about Java generics and the best sources I used are:

• The Java Tutorial.
• Java Generics and Collections, by Maurice Naftalin and Philip Wadler.
• Effective Java (second edition), by Joshua Bloch.

Despite the wealth of information out there, sometimes it seems to me that many developers still don't understand the meaning and the implications of Java generics. That's why I'm trying to summarize the basic information developers need about generics in the simplest possible way.

This blog post is made up of the following parts:

Part I - The Basics
Part II - Subtyping
Part III - Wildcards
Part IV - Bounded Type Variables

The Motivation for Generics

The simplest way to think about Java generics is thinking about a sort of a syntactic sugar that might spare you some casting operation:

List<Apple> box = ...;

Apple apple = box.get(0);

The previous code is self-speaking: box is a reference to a List of objects of type Apple. The get method returns an Apple instance an no casting is required. Without generics, this code would have been:

List box = ...;

Apple apple = (Apple) box.get(0);

Needless to say, the main advantage of generics is having the compiler keep track of types parameters, perform the type checks and the casting operations: the compiler guarantees that the casts will never fail.

Instead of relying on the programmer to keep track of object types and performing casts, which could lead to failures at runtime difficult to debug and solve, the compiler can now help the programmer enforce a greater number of type checks and detect more failures at compile time.

The Generics Facility

The generics facility introduced the concept of type variable. A type variable, according to the Java Language Specification, is an unqualified identifier introduced by:

• Generic class declarations.
• Generic interface declarations.
• Generic method declarations.
• Generic constructor declarations.

Generic Classes and Interfaces

A class or an interface is generic if it has one or more type variable. Type variable are delimited by angle brackets and follow the class (or the interface) name:

public interface List<T> extends Collection<T> {

  ...

}

Roughly speaking, type variables act as parameters and provide the information the compiler needs to make its checks.

Many classes in the Java library, such as the entire Collections Framework, were modified to be generic. The List interface we've used in the first code snippet, for example, is now a generic class. In that snippet, box was a reference to a List<Apple> object, an instance of a class implementing the List interface with one type variable: Apple. The type variable is the parameter that the compiler uses when automatically casting the result of the get method to an Apple reference.

In fact, the new generic signature or the get method of the interface List is:

T get(int index);

The method get returns indeed an object of type T, where T is the type variable specified in the List<T> declaration.

Generic Methods and Constructors

Pretty much the same way, methods and constructors can be generic if they declare one or more type variables.

public static <T> T getFirst(List<T> list)

This method will accept a reference to a List<T> and will return an object of type T.

Examples

You can take advantage of generics in both your own classes or the generic Java library classes.

Type Safety When Writing...

In the following code snippet, for example, we create an instance List<String> of populate it with some data:

List<String> str = new ArrayList<String>();
str.add("Hello ");
str.add("World.");

If we tried to put some other kind of object into the List<String>, the compiler would raise an error:

str.add(1); // won't compile

... and When Reading

If we pass the List<String> reference around, we're always guaranteed to retrieve a String object from it:

String myString = str.get(0);

Iterating

Many classes in the library, such as Iterator<T>, have been enhanced and made generic. The iterator() method of the interface List<T> now returns an Iterator<T> that can be readily used without casting the objects it returns via its T next() method.


for (Iterator<String> iter = str.iterator(); iter.hasNext();) {
  String s = iter.next();
  System.out.print(s);
}

Using foreach

The for each syntax takes advantage of generics, too. The previous code snippet could be written as:

for (String s: str) {
  System.out.print(s);
}

that is even easier to read and maintain.

Autoboxing and Autounboxing

The autoboxing/autounboxing features of the Java language are automatically used when dealing with generics, as shown in this code snippet:

List<Integer> ints = new ArrayList<Integer>();
ints.add(0);
ints.add(1);
      
int sum = 0;
for (int i : ints) {
  sum += i;
}

Be aware, however, that boxing and unboxing come with a performance penalty so the usual caveats and warnings apply.

Next Steps

In the next part of this post, we will see subtyping relations of generic types.

Part I - The Basics
Part II - Subtyping
Part III - Wildcards
Part IV - Bounded Type Variables

Atlassian JIRA: In-Place Database Upgrades

Upgrading JIRA to a newer version, or even migrating JIRA from a machine to another, has always been a pretty simple task. Oversimplifying (only a little bit), a JIRA migration can be accomplished following these steps (this is an excerpt of the Official JIRA Documentation):

• Prevent users from modifying JIRA while the migration is taking place.
• Export the old JIRA data using the export tool.
• Back up the old JIRA: installation directory, home directory, database. Attachments and indexes should be backed up only if stored outside the JIRA home directory (which is not the default installation).
• Install the new JIRA.
• Migrate JIRA configurations from the old instance to the new one.
• Connect the new JIRA to a new, empty database.
• Start the new instance and use the import tool to load the data exported from the old instance.

I acknowledge that it might seem otherwise, but the migration process is really easy to perform. Unfortunately, the migration process has some drawbacks that affect your users while it is taking place:

• Users cannot use JIRA during the migration process.
• The import and export phases are not constant-time tasks: the time required to complete them depends on the amount of data that's been migrated and it can quickly become an issue for large JIRA installations.

Although unsupported up to JIRA v. 4.3, I've seen users neglecting the import/export phase and trying to connect the new JIRA instance to the old database. Most of the times, it worked but it would not update the database structures used by JIRA, with at least a performance degradation as a consequence.

In-Place Database Upgrades

Atlassian JIRA v. 4.3 now officially supports In-Place Database Upgrades when upgrading from at least JIRA 4.0.x.

This means that, during an upgrade process, the administrator is not required to perform the export/import phase any longer. Instead, he will be able to connect the new instance directly to the old database: during the first startup, JIRA will perform a check of the database structures and will upgrade them accordingly.

The bigger the JIRA instance, the more time will be saved during an upgrade process and the less downtime will be experienced by JIRA users.

Upgrading JIRA has never been so easy.

Atlassian JIRA 4.3 Has Been Released With a Wealth of Exciting New Features

On March, 16th Atlassian released a new version of its flagship issue tracking and project management solution: Atlassian JIRA v. 4.3.

This new release comes with a bunch of exciting new features both for users and for administrators. This are just some of the new JIRA features that you can find in this release (the following list is an excerpt of Atlassian JIRA v. 4.3 Release Notes):

• Revamped user management and full LDAP integration.
• New Plugin Management System.
• In-place JIRA upgrade.
• Improved search capabilities.
• Support for Google Chrome and Safari 5.

In the posts in this series I'll explore some of these features:

Part I - Full LDAP Integration
Part II - In-Place Database Upgrades

Nevertheless, the best thing you can do and the quickest way to discover what's new in the latest JIRA is checking it out yourself: download JIRA and get started.

Atlassian JIRA: Full LDAP Integration

Atlassian introduced many new features in JIRA v. 4.3 and one of them is one that users have been waiting for for a long time: full LDAP integration.

Up to now, administrators basically had two options to manage JIRA users:

• Using JIRA internal user registry.
• Using an external LDAP directory for authentication only.
• Using Atlassian Crowd.

Please note that Atlassian Crowd provides a broader identity management and Single Sign-On solution and it is out of scope in this blog post.

The Problem

User management can be an issue and a burden for the administrator even small-sized business: without a "user registry", the complexity of keeping in sync user accounts throughout the organization grows both with the number of accounts and with the number of environments to be kept in sync (such as workstations, servers, applications, etc.).

To solve this problem, organizations often centralize the administration of user accounts on some sort of "user registries" integrated with all of their environments, from operating systems to applications. Nowadays, LDAP is one of the most commonly used protocol to integrate such registries and it is supported by almost any enterprise-level operating system and many enterprise applications.

Up to version 4.2, Atlassian JIRA could integrate with an LDAP directory just for authentication: this factored out only part of the user management complexity (basically, the management of an user's credentials) but administrators still had to provision JIRA with user accounts (and all of their attributes).

The Solution: Full LDAP Integration

Atlassian JIRA v. 4.3 comes with full LDAP integration. Administrators can now:

• Integrate JIRA with one of the supported LDAP directories.
• Use JIRA two-way synchronization.
• Integrate JIRA with more than one directory at a time.
• Administer user directories with a revamped, easy to use GUI.
• Use JIRA as an user directory for Atlassian Confluence.

Supported Directories

Atlassian JIRA now integrates with many of the most commonly used directory servers out there:

• Apache User Directory (v. 1.0.x and 1.5.x).
• Apple Open Directory (read-only).
• FedoraDS (read-only POSIX schema).
• Novel eDirectory Server.
• OpenDS.
• OpenLDAP.
• OpenLDAP (read-only POSIX schema).
• Oracle Directory Server Enterprise Edition (former Sun Directory Server Enterprise Edition).
• Microsoft Active Directory.
• Generic LDAP directory servers.
• Generic POSIX/RFC2307 directory servers (read-only).

Although disable by default, it's worth noting that JIRA also supports nested groups, the ability to recursively scan group memberships in the case that a group be member of another group.

User Directories Management Made Easy

The setup and configuration of user directories can be easily performed using the JIRA Administration Console, whose new User Directory windows has been redesigned from scratch:

Using the GUI, the administration will be able to configure most of the parameters to customize and fine-tune the integration of JIRA with your directory servers. Some of the tuneable parameters are:

• Directory Server settings.
• LDAP Schema: to configure the Base DN and, optionally, the User DN and the Group DN to limit the search scope to a sub-tree of the whole directory.
• LDAP Permission: to decide whether the directory will be accessed in read-only mode or in write-mode, in which case modifications to users, groups and memberships made in JIRA will be synced back to the LDAP directory.
• User and Group Schema settings: to establish object classes, filters and attribute names.
• LDAP cache and connection pool settings.

Conclusions.

Atlassian JIRA v. 4.3 can now be easily integrated with the directory server of choice of your organization. Even unexperienced administrators will be able to quickly setup and configure an user directory for JIRA in a matter a few minutes, using the new User Directories window of the JIRA Administration Console.

No doubt, JIRA has never been so close to its users.

Quickly Determining the Key From a Key Signature

A couple of days ago a friend of mine asked me how you can determine the key of a music score by observing its "key signature". The key signature is the set of ♯ or ♭ symbols that are placed on the staff to indicate the notes that should be played one semitone higher (in the case of ♯) or lower (in the case of ♭) along the score (unless an accidental indicates otherwise). An example key signature (A major or F♯ minor) is shown below:

The key signature, despite its name, is a tool meant to reduce the number of accidentals in a score but it might not necessarily match the key of the score. Nevertheless, most of the time, it will.


The notational convention used comes from the circle of fifths:

Basically, the circle can be navigated clockwise or counter-clockwise, starting from the upper C, down to the G♭/F♯. In every "step" a symbol is added to the key signature: a ♯ if the circle is navigated clockwise or a ♭ if the circle is navigated counter-clockwise. The rule to add the symbol to the key signature is the following:

• A ♯ shall be added to the leading note for the major scale or, equivalently, to the supertonic for a minor scale.
• A ♭ shall be added to the subdominant for the major scale or, equivalently, to the submediant for a minor scale.

So far, so good, but theory would not help my friend so much, would it?

Fortunately, there's a quick mnemonic to find out the key from a key signature.

• In the case of a key signature made up of ♯ symbols: Since, as explained earlier, the new ♯ shall be placed on the leading note (in the case of a major scale), the mnemonic is: look at the last ♯ in the signature and raise it by one semitone. That's the corresponding major key.
• In the case of a key signature made up of ♭ symbols: Since the new ♭ shall be placed on the subdominant (in the case of a major scale), take the second last ♭: that's the corresponding major key. If the signature has got only one ♭, that's a F major (that's easy).

For example, if we look at the following signature:

The last ♯ symbol is a E♯. If we raise it one semitone we've got a F but, since the F is already marked as F♯ on the signature, the corresponding major key will be F♯.

If we look at this signature:

The second last ♭ is a C♭: the corresponding major key is, indeed, C♭.

Upgrading Oracle Glassfish Server to v. 3.1

Oracle Corporation just released Oracle Glassfish Server v. 3.1: this release includes many interesting features and I started upgrading as soon as I could allocate some time. The official Glassfish Server 3.1 Upgrade Guide can be found here.

In a very recent post, I described how you can upgrade your Glassfish instance to v. 3.0.1 using the tools provided by the application server. With the release of version 3.1 things haven't changed so much so that, if you're in a hurry, you can just follow those instructions.

Nevertheless, I'll take advantage of this news to summarize which are the possible upgrade paths for your Glassfish instances so that you can choose the one that best fits your needs:

• Upgrade tool.
• Update tool.
• pkg tool.
• Software Update Notifier.

Upgrade Tool

The upgrade tool let us perform side-by-side upgrades and it's the only tool that can be used to upgrade a Glassfish instance earlier than Glassfish v. 3.0.1 or Enterprise Server v. 3.0.

The ability to perform side-by-side upgrades is important in the cases in which you do not want to upgrade your existing installation. In the case something goes wrong during the upgrade procedure, the original instance is not modified and the administrator is free to try the upgrade procedure again or restart the old instance until further investigation is done.

The upgrade tool, installed on $GF_INST/glassfish/bin/asupgrade, can be used both in graphical or command line mode. To use this tool, both the source and the target server directories must be accessible from the system in which asupgrade is launched and the user must have read permission on the source and read and write permission on the target directory.

Before launching the tool, the Glassfish domain to be upgraded must be stopped. Also, the official documentation suggests to manually copy libraries in the server /lib directory from the source to the target server. As pointed out in Bobby's comment, older versions of this tool (such as v. 3.0.1) even tried to detect and copy user libraries from $GF_INST/glassfish/lib: the upgrade tool bundled with GlassFish 3.1 will not so that it's important to manually check this directory to manually migrate libraries form one server installation to another.

The options accepted by the tool are the following:

• -c|--console: Launches the tool in command-line mode.
• -V|--version: Dumps the tool's version number.
• -h|--help: Dumps the tool's arguments' help.
• -s|--source: Specifies the source domain directory.
• -t|--target: Specifies the target domain root-directory.
• -f|--passwordfile: Specifies a password file with Glassfish master password.

The quickest way to launch the tool is just:

asupgrade

to launch it in GUI mode, or

asupgrade -c

if you prefer using the CLI mode. In either mode, just supply the required parameters and proceed with the upgrade information.

If you need to automate the upgrade procedures of multiple domains, perhaps you'd rather use the asupgrade tool in a script:

asupgrade -c \

  -s /path/to/source/domain \

  -t /path/to/target/root/domain

At the end of the upgrade procedure, you should check the logs to verify that no error was encountered during the process. If everything is ok, you can now start your new Glassfish v. 3.1 domain.

Update Tool and pkg Tool

The update tool and the pkg tool are, respectively, a GUI and a CLI utility, which are part of the Update Center Tools. Although very similar, they do not provide the same set of features to the user. Nevertheless, as far as it concerns the upgrade procedure, they can be used interchangeably and whether you want to use one or the other is just a matter of taste and opportunity.

The biggest differences with the upgrade tool describe in the previous section is that these tools cannot be used to upgrade instances earlier than 3.0.1 and they do modify the server installation directory during the upgrade procedure. Should the procedure fail, although both the tools and the upgrade procedure are very resilient, the administrator could be left with a non-functional Glassfish installation. The biggest advantage is that it's a very quick upgrade path.

Before upgrading, as usual, Glassfish domains should be stopped.

To update tool can be launched with the:

$GF_INST/glassfish/bin/updatetool

command and its GUI will appear. On the main window, click the Available Updates control, select all items on the list and proceed with the upgrade procedure. The server will be upgraded to version 3.1 and, at the end of the procedure, the existing domains must be upgraded starting them with the --upgrade options:

asadmin start-domain your-domain --upgrade

Despite the name of the command, at the end of the upgrade the domain will be stopped. After upgrading all of your domains, you can start them normally.

Upgrading using the pkg command will be familiar to long time (Open)Solaris users. Glassfish bundles a version of the pkg command to support IPS repositories. To upgrade Glassfish to the latest version is sufficient to launch the following command:

$GF_INST/glassfish/bin/pkg image-update

After the upgrade completes correctly, each Glassfish domain should also be upgraded as explained in the update tool case.

Software Update Notifier

The Software Update Notifier is yet another Update Center tool and, as such, it enables the administrator to perform upgrades under the same conditions explained in the previous section.

The Software Update Notifier, if installed, periodically checks if updates are available and, when they are, it suggests the administrator to install them with a fancy notification balloon. When all domains are stopped, the upgrade process can be started accepting the notification in the balloon.

After the upgrade completes correctly, each Glassfish domain should also be upgraded as explained in the update tool case.