Compacting product version strings into shorts

[brian.stansberry]

JBoss has recently standardized the naming conventions for product releases (see http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossProductVersioning). This thread is aimed at deriving a standard mechanism for converting the String identifier for releases into a short.

Background:

Both JBoss Cache and JGroups encode their release version into a short for inclusion in data transmitted between cluster nodes. This information is used to control interoperation between nodes running different releases of the software.

In the JGroups case at least, the use of a short (as opposed to, say, an int) is important, as the value is included with every message and needs to be transmitted as efficiently as possible.

Other projects may have a similar need. Many projects may have no such need, or may prefer to encode in an int. For reasons discussed below, I don't advocate that all projects be able to convert version strings into shorts; only that those who do should follow a common mechanism.

Proposal:

The JBoss convention is that release names are of format X.Y.ZZ.Q*, where Q is an alpha-numeric qualifier. I propose simply to put X in the thousands position, Y in the hundreds, Z in the tens. The final position would be 0 unless Q == "SP", in which case the final position would be the digit immediately following SP. If Q were a digit, the final digit would be Q.

Thus 1.2.4.SP1 would be 1241, 1.3 would be 1300. 2.2.9.1 would be 2291.

A couple issues arise with this scheme:

1) All versions up to and including the GA release all resolve to the same short. In the clustering use cases for these shorts, this is not an issue; if, for example, JBossCache 1.3.0.Alpha1 and 1.3.0.Alpha2 had different wire formats, the short wouldn't be useful in distinguishing the versions, but who cares if different pre-GA versions don't interoperate?

(This "problem"could be resolved by giving a position to the alpha qualifier, shifting higher order elements up. But then release numbers > 3.2.7 would not be possible; 6.5.5 if unsigned shorts were used.)

2) Clearly, numeric values other than the major version number cannot be > 9. This is a significant limitation. I would suggest that projects that see the possibility of lower-level version numbers going higher than nine should not use shorts for version encoding.

Please note also that even in the string versions of release names, using values > 9 in positions other than the major version field results in strings that sort incorrectly, e.g.

1.2.0
1.2.1
1.2.10
1.2.2
1.2.9

[starksm64]

I would suggest the following mapping between X.Y.Z and the short format:

------- X ---- ------- Y ---- ------ Z --------
15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00

This gives:
X = 0-31 for major versions
Y = 0-31 for minor versions
Z = 0-63 for patch level

The qualifier is irrelevant for compatibility because there should not even be compatibility problems for different Z values.

 static final int MAJOR_SHIFT = 11;
 static final int MINOR_SHIFT = 6;
 static final int PATCH_SHIFT = 0;
 static final int MAJOR_MASK = 0x00f800;
 static final int MINOR_MASK = 0x0007c0;
 static final int PATCH_MASK = 0x00003f;

 public static short encodeVersion(int major, int minor, int patch)
 {
 short version = (short) ((major << MAJOR_SHIFT)
 + (minor << MINOR_SHIFT)
 + patch);
 return version;
 }
 public static String decodeVersion(short version)
 {
 int major = (version & MAJOR_MASK) >> MAJOR_SHIFT;
 int minor = (version & MINOR_MASK) >> MINOR_SHIFT;
 int patch = (version & PATCH_MASK);
 String versionString = major +"."+minor+"."+patch;
 return versionString;
 }

For versions gt 15.31.63 the encoded short will be a negative number.

[brian.stansberry]

Forgot to mention a key point, which is that 1.2.4.SP1 uses a different state transfer format from 1.2.4.

[brian.stansberry]

Of course, JBossCache could always code around this issue. Initially at least JBossCache is going to have to have its own version of the the utility function, as it doesn't exist yet in a separate sharedlibrary and we want JBossCache to be usable in previous versions of the AS.

[starksm64]

We can't have a broken release drive the semantics of how to handle a version packing scheme. Cache will have to encode 1.2.4SP1 as 1.2.5 and recognize the significance.