Mapping PostgreSQL Arrays with iBATIS

I needed to map a PostgreSQL integer array column to a Java integer array using iBATIS. The following is what seems to do the trick. Suppose you have a table with an integer array:

create my_table (
  id integer primary key,
  array_column integer[]
);

And some data was inserted using e.g. the following insert statement:

insert into my_table (id, array_column) values (1, array[1, 2, 3]);

Now lets have a Java class that can map to the above table, as follows:

public class MyTable {

  private int id = 0;
  private int[] arrayColumn = null;
  
  public int getId() { return id; }
  public void setId(int id) { this.id = id; }
  public int[] getArrayColumn() { return arrayColumn; }
  public void setArrayColumn(int[] arrayColumn)
    { this.arrayColumn = arrayColumn; }
  
}

We will now specify a select map, and we pass a result map to the select which is going to contain the mappings from the various columns to the properties in the Java bean.

<select id="getMyTable" parameterClass="int" resultClass="MyTable"
        resultMap="myTableResult">
    select id, array_column from my_table where id = #id#
</select>

The result map that we refer to in the resultMap attribute in the above select map is specified below:

<resultMap id="myTableResult" class="MyTable">
    <result property="id" column="id" />
    <result property="arrayColumn" column="array_column" jdbcType="ARRAY"
            javaType="java.sql.Array" typeHandler="ArrayTypeMapper" />
</resultMap>

In this result map, we map the id column to the id property and the array_column column to the arrayColumn property. There is however additional configuration needed for this second mapping. We specify that the JDBC type is ARRAY (as in java.sql.Types.ARRAY). We also specify that the Java type is java.sql.Array, but more importantly we specify the typeHandler attribute, which refers to the handler that is going to handle this array, and it is called ArrayTypeMapper. It implements TypeHandlerCallback, and its contents are as follows:

import java.sql.Array;
import java.sql.SQLException;

import com.ibatis.sqlmap.client.extensions.ParameterSetter;
import com.ibatis.sqlmap.client.extensions.ResultGetter;
import com.ibatis.sqlmap.client.extensions.TypeHandlerCallback;

public class ArrayTypeMapper implements TypeHandlerCallback {

  public void setParameter(ParameterSetter setter, Object parameter) 
        throws SQLException {
    throw new UnsupportedOperationException("Not implemented");
  }

  public Object getResult(ResultGetter getter) throws SQLException {
    Array array = getter.getResultSet().getArray(getter.getColumnName());
    if (!getter.getResultSet().wasNull()) {
      return array.getArray();
    } else {
      return null;
    }
  }

  public Object valueOf(String s) {
    throw new UnsupportedOperationException("Not implemented");
  }
}

It is very convenient that the getter object has the column name available (so we can avoid having to explicitely name the column or use indexes). Do not get the array from the array object immediately, you should first check whether is was null. If that was the case, return null (causing the MyTable object's array to be set to null), otherwise return array.getArray(). This will automatically cause the int[] in MyTable to be filled with the contents of the array column of my_table.

Smart Version Class with Version Increment Validation and Suggestion

For a build management system I am working on, I want a smarter way of doing version numbering for versioned builds. Right now a user can enter any version number, but I would like the system to suggest a next version number. E.g. if the last versioned build had a version number 1.2.3, I would like the system to suggest 1.2.4 as next version number when a new versioned build is started. I would also like to give a warning when a user tries to go from 1.2.3 to 1.2.5, skipping a number.

For this I have created a "smart" version class that works with numerical version numbers only and that can have any amount of version digits. Such version numbers include 1.2.3, 2.1.0, 2.33.24.18.65, etc. Valid transitions of one version number to another are from 1.2.3 to 1.2.4, 1.2.3 to 1.3.0, 1.2.3 to 1.2.3.0, 1 to 2, 1.2.3 to 2, 1.2.3 to 2.0, 1.2.3 to 2.0.0, 1 to 2.0, 2.0 to 3. The basics of this smart version class is an integer array, although that is quite the overkill, and a byte would probably have been enough (640KB anyone?). The constructor of this class takes an integer array, and per version class I want the array to become immutable (if you need a new version, instantiate a new version object).

public class Version {

  private final int[] versionDigits;
  
  public Version(int[] versionDigits) {
    if (versionDigits == null) {
      throw new IllegalArgumentException("versionDigits is null");
    }
    if (versionDigits.length == 0) {
      throw new IllegalArgumentException("versionDigits length is 0");
    }

    this.versionDigits = versionDigits;
  }

To complement the foundation, a helper method is added that is able to parse a version string such as "1.2.3" into an array of digits. This just makes our life easier when we have version strings and want to convert them into a version object. This is done by the parse method.

  public static Version parse(String versionString) {
    if (versionString == null) {
      throw new IllegalArgumentException("versionString is null");
    }
    
    StringTokenizer st = new StringTokenizer(versionString, ".");
    int[] versionDigits = new int[st.countTokens()];
    int i = 0;
    while (st.hasMoreTokens()) {
      versionDigits[i++] = Integer.valueOf(st.nextToken()).intValue();
    }
    return new Version(versionDigits);
  }

Now we will get to the interesting stuff. The following method checks whether a transition was a valid one and returns true if so, otherwise false.

  public boolean isValidNextVersion(Version newVersion) {
    int i = 0;
    for (; i < versionDigits.length; i++) {
      if ((newVersion.getVersionDigits()[i] - versionDigits[i]) == 1) {
        i++;
        break;
      } else if (newVersion.getVersionDigits()[i] != versionDigits[i]) {
        return false;
      } else if ((i + 1) == newVersion.getVersionDigits().length) {
        return false;
      }
    }
    for (; i < newVersion.getVersionDigits().length; i++) {
      if (newVersion.getVersionDigits()[i] != 0) {
        return false;
      }
    }
    return true;
  }

The above method deserves some explanation. It goes through all the digits and first checks whether the difference is positive one (new digit - old digit = 1). If that's the case, then we have found the one digit that changed and that it had increased with one. We will then need to increase the position in the array with one, break out of the initial loop and start checking whether the remainder of digits are zero in the new version number. E.g. if the second digit in 1.2.3 was increased by one, the resulting version number must be 1.3.0.

If there was no difference of one, then the new digit and the old digit must be the same (e.g. in the case of the second digit in 1.2.3 to 1.2.4). If that is not the case (new digit != old digit), we know one of the digits did an invalid transition, e.g. from 1.2.3 to 1.4.0, and we can safely return false.

The last condition in the first loop checks whether the next run in the loop would cause the array index to be out of bounds for the new version number. As the first check did not break yet, we are pretty confident that the version number remained the same, e.g. from 1.2 to 1.2, or went backward losing digits, e.g. from 1.2.3 to 1.2. The condition that the old version number has less digits than the new version number is already covered by the fact that the first for loop loops through the digits of the old version number.

The second loop in the method just checks whether all remaining digits in the new version number are zeros. If that is not the case, we would have gone from e.g. 1.2.3 to 1.2.3.1 or 1.2.3 to 1.2.4.1. Return false if that's the case for any of these digits, else we can safely say the version number transition was valid and return true. As a bonus we can implement a method that suggests a new version. Because we do not want the old version number's digits to be touched, we first create a getVersionDigits method that returns a copy of the internal array:

  public int[] getVersionDigits() {
    int[] newVersionDigits = new int[versionDigits.length];
    System.arraycopy(versionDigits, 0, newVersionDigits, 0,
        versionDigits.length);
    return newVersionDigits;
  }

The method that suggests the new version will actually return a new version object with the suggested version digits. This is done by calling the getVersionDigits method, increasing the last digit of that array by one and returning a new version number object with the given array, e.g. in the case of 1.2.3 the suggested new version is 1.2.4. Variations on this theme could include a mechanism that suggests valid transitions for any of the digits, e.g. in the case of 1.2.3 the new suggested version number would be 1.3.0.

  public Version getNextSuggestedVersion() {
    int[] newVersionDigits = getVersionDigits();
    newVersionDigits[newVersionDigits.length - 1]++;
    return new Version(newVersionDigits);
  }
}

This class is in no way set in stone. Variations on this class could be returning the position of the invalid digit transition (e.g. digit 2 did an invalid transition) or something that gives back reason codes as to why a transition was invalid (e.g. numbers are the same, new version is smaller than old version, etc.), or the ability to specify whether version numbers are zero based or one based (e.g. making 1.2.3 to 1.2.4.1 a valid transition and suggesting version numbers likewise). Maybe it is desirable to have something like a suffix as well, and requiring the suffix to change if the version number remains the same (e.g. 1.2.3 RC1, 1.2.3 final, etc.).

This can all be put into place in the code shown above. At least this class is a starting point that takes care of the nitty gritty details of the algorithm that does the validation on the version digit transitions. Although something like validating version transitions sounds simple, suffice to say my initial attempt consisted of 6 for loops and 24 if branches and that I am very happy to have been able to bring this down to what I have now.

Testing Java2Html with Eclipse Europa and Blogger.com

Although the plugin is a bit dated (version 1.5.0 dates from January 2006), the Java2Html Eclipse plugin seems to be working with the Eclipse 3.3 Europa fall maintenance release (and thus very likely works with all 3.x versions). I downloaded and extracted the plugin to the plugins directory, restarted with the -clean option and I had a new context menu, called "Java2Html". And now for a little test to see what it'll look like here:


/**
 * Type comment
 */
public class Test3 {
  public static void main(String[] args) {
    // Some comments
    System.out.println("Java2Html test");
  }
}


I had to manually remove the <br /> elements as they caused empty lines and obviously I had to remove the html head, body, etc. I also got rid of the table and the div that were generated. Although I made these manual changes afterwards, I still think it's a nice little plugin that'll save lots of time when you want to generate syntax highlighted code from within Eclipse. Obviously this isn't just handy for posting, but it would work great in JavaDoc comments as well (albeit not very readable in the comment itself of course ;-))

w.bloggar blogger

Ha, got w.bloggar to work with Blogger. Seems I upgraded to the beta, and for that I am to do something a little different than just selecting the "Blogger" option in the account setup wizard. The relevant information can be found here. As always, Google is your friend, as searching for w.bloggar blogger reveals the relevant link as the first result. I'm certainly feeling lucky :-)