Number crunching for XPages Java Padawans

Integrating Java into XPages is not particularly challenging, once you are comfortable with SSJS. There are some gotchas around Domino objects (database.getTitle() and other such methods that return primitive values – strings, etc – still return the value even after the object has been recycled!), but those are the kinds of things the OpenNTF Domino API are designed to prevent developers having to worry about.

But there are two aspects that developers are likely to hit pretty quickly whose solutions are not immediately obvious.

The first is String handling. There are two aspects here. The first is that to compare two strings you can’t use ==. Instead you have to use the equals() method of a String. The other point of note is that myString.equals() will fail if myString is null. So it’s advisable to compare a String you know will not be null, so if you want to check if the value if the value is “Yes” for a String whose variable name is myString, you would typically use “Yes”.equals(myString). Better still would be to use a Java class better designed for handling Strings. IBM has provided the StringUtil class in XPages, that includes a lot of helper methods like StringUtil.isEmpty(). Apache Commons has a more extensive package, called StringUtils. It’s a bit harder to use because of Java security issues, but the second comment on this blog post shows how to add it to the lib folder and add to the Build Path.

The second aspect of Java that developers are likely to hit is number handling. Although you can probably get away with adding two small integers or doubles together in most circumstances, for anything significant, you need something more designed for mathematical handling. Anyone coming from a LotusScript background is well aware of challenges with numbers and that there is nothing specific to help. Fortunately Java has a class fully designed for number handling. This is java.math.BigDecimal. You can create a BigDecimal easily from something else, best an int or a String, by using BigDecimal myNum = new BigDecimal("1.75"). One caveat is that there is also an IBM BigDecimal class – you don’t want that one. Instead you want the java.math one. This has various methods for adding, subtracting, multiplying and dividing. The important point to be aware of is that the class is immutable. That means the methods for adding etc don’t change the BigDecimal you’re using, but instead return a new BigDecimal containing the result. So you would use myNum = myNum.add(new BigDecimal(10), for example.

The other point I want to mention is around dividing. This is where you’ll usually want to do rounding, and maybe need to. The divide() method I use most often is divide(BigDecimal divisor, int scale, int roundingMode). The second parameter is the number of decimal places to round to and the third is the rounding mode. BigDecimal has a set of static variables to help you here, so you can just use BigDecimal.ROUND_HALF_UP as the third parameter, for example.

If you want to read more, you can always read a good Java book. But for those coming from a LotusScript background, this should avoid falling into basic errors with Java number handling.