Business Data Types

In a brokerage application I worked on a few years ago, I believe we made a good start at defining a set of useful business classes. Not surprisingly, the first type of unit we addressed was money, which is not only the main preoccupation of much of business programming, but the fuel that makes much of it go.  Money, as defined in our application, has a magnitude and a currency. Since currencies are so important to our society, we do actually have 3-letter ISO codes for the different currencies - our package supported about 200 of them. In our package, a monetary value was always represented by the ISO code followed (with no intervening blanks) by an amount, whether for input or for output. Thus we might have CAD205.10, or USD3012.55. Each currency has a preferred number of decimals for amounts (although this does not apply to rates), except for some oddball "currencies" (such as Euro-Gold) that allow any number of decimals.  In our application we loaded the currency information at start of session from a database.

Note that rates have different precision requirements from monetary amounts.  The general rule for currency is that, at the end of a computation, they must be rounded to whatever the smallest denomination is in that currency, whereas rates can have any number of decimal places.  In the case of (US and Canadian) currency, the smallest unit is really the cent, but instead of 12345 cents we usually write $123.45.  This can be handled in most cases  by forcing rounding when the currency amount is turned into displayable format, e.g. by using some method built on the Java toString() method.   In addition, in our application we provided a round() method which did the same thing to non-display currency amounts.  It has been suggested that we should really distinguish between "non-final" and "final" currency values, but that would involve a vast increase in the number of methods over what we already have, so I think the above technique is adequate.  

In turn, the numeric value in our Monetary class was implemented using the new Java BigDecimal class which is now available, as of Java 1.5, replacing the previous one.  Even though they have explicit precision, floating point numbers are not appropriate for monetary amounts, although they work quite well for rates (another difference between rates and monetary amounts) or physical units such as distances. We chose the new BigDecimal, as its arithmetic has been consciously designed to give the same results that you would get yourself when doing decimal arithmetic by hand.   For instance, 3.82 + 2.18 becomes 6.00, not 6.

Before getting into the specific classes and methods, I would like to point out that money was really rather an easy class to define.  There is a much more complex issue revolving around the question of Quantity.  We have tentatively added a  class called Quantity to the project, but the real question is "Quantity of what?".   Quantity does not extend BigDecimal, as there are many things you can do with BigDecimal that you do not want to automatically be able to do with Quantity - i.e. you cannot normally multiply two Quantities together (unless it is two lengths to form an area), and conversely, a Quantity should almost always be a quantity of something.   Users can extend Quantity for their own purposes - this will usually entail adding the thing that it is a quantity of - what Denis Garneau (the very talented IBM architect who did most of the design work) calls its "quality".    You should not be able to add weight to length - or number of eggs to number of chickens!  Denis recently ran into a mysterious programming bug, which eventually turned out to be caused by someone adding a temperature to a weight!  Alternatively, Quantity could be an interface, rather than a class.   So you see, we are starting to stray into the area talked about in Physical Units.  Denis and I would like people to explore this area, especially in different problem domains, and write papers about it!  Specifically, a) should Quantity be a class or an interface? b) what extensions/implementations did you need to add to it for your particular domain of interest?

As of Nov. 4, 2009, the source code for these classes can be found in SourceForge.   A non-executable jar file can be downloaded from SourceForge - it is also available as a jar file.

Monetary class

The constructors for our money class, called "Monetary", are as follows:
 

BigDecimal objects are (immutable) decimal numbers with explicit precision, while Currency objects represent the actual currencies themselves - thus one Currency object is US dollars, another is Canadian dollars, while yet another might be pounds sterling .   The first constructor is needed to build Monetary objects that are the result of a computation; the second to build them from the String representation.  So we needed the converse operation, which was a method called either toString() or  serialize().

The complete set of methods we provided for our Monetary class are as follows:
 

This list is to give you a flavour for the kinds of things we felt would be needed in this class.  As requirements for new methods came up in our application we added them, so if you don't see something in this list that you would expect, it's probably because the need didn't come up in our application.  You will see that a number of other classes (apart from the standard Java ones) are mentioned in the list given above and we will be describing them in what follows - although perhaps not to such a fine level of detail.

Monetary amounts cannot be multiplied together, but they can be added, subtracted, compared against each other, and so on.  In all these cases, the currency must be the same; if the two currencies involved are not identical, an error condition is raised.  In our implementation, this was a run-time test, as opposed to a compile-time test. In our view it wouldn't make sense to make every one of our 200 currencies a different class.

Monetary amounts can however be multiplied or divided by instances of the classes PCPrice and BigDecimal (more about PCPrice later).  These latter are both essentially dimensionless, and in general we can multiply or divide dimensioned values by dimensionless ones, giving a result that has the same dimension as the dimensioned quantity.

Note that we allowed a Monetary object to have an undefined currency.  In this state you cannot do anything with it except set the currency.  I am not sure if this function was ever used.

Monetary Price (MPrice) class and Percent Price (PCPrice)

This web page will be talking about the classes we actually used in our application, and what their capabilities were. Although we used BigDecimal for MPrice (in conjunction with Currency), we allowed an MPrice object to have more decimal places than monetary amounts.  I believe one of the types of floating point number might also work well for MPrice, but we went with BigDecimal..

For now, we are going to expand on the Monetary Price (MPrice) class.  This could be entered as a decimal value, but also as a fraction of the form "3 + 5 / 16" (usually referred to as a "vulgar fraction"), where the last integer was always a power of 2.  Supposedly, US stock exchanges are switching to decimal prices soon (or may already have done so), but at the time we built this system, they had not yet made the switchover.

We held the three integer fields, provided in a constructor, in the MPrice object, as well as the decimal value, which was computed if the price was entered in vulgar fraction form.  If the price was entered as a decimal, the denominator item of the integer fields was set to zero, and the other two integer fields were ignored. I managed to figure out a way to calculate the vulgar fraction from the decimal, and we provided a constructor to do this. Again I'm not sure if it was ever used.

Here are the constructors for Monetary Prices:

Here are some typical methods for this class:

Our brokerage application also required a different kind of price, which we called "PCPrice".  This stands for PerCentPrice and is basically a dimensionless quantity that is entered or displayed as a percentage, i.e. 20PCT represents the value .2.  PCPrice also supports "discount" and "premium", coded as DSC and PRM.  20DSC represents a value of .8, while 20PRM represents 1.2.   Although PCPrice has interesting ways of being displayed, it is dimensionless, so it is equivalent to a pure value. Because of this, it can extend BigDecimal, and its methods are basically whatever it inherits from BigDecimal, plus a few quirks due to the PCT/DSC/PRM convention, so I will not go into it further.  

Exchange Rate (ExchRate) class

Since we are dealing with multiple currencies, we need a way of exchanging money.  You can't add money of different currencies, so of course we need an ExchRate class - instances of this class can be applied to a Monetary value to convert it to Monetary of another currency.

Its constructors are as follows:

By the way, our TimeStamp class extends the Java Date class, which goes down to the millisecond, in spite of its name. The Java SQL TimeStamp class goes down to the nanosecond, but we didn't consider that necessary for our application, although we had methods to convert our time stamps from and to SQL time stamps. We held all time stamps in UTC format (Universal Time Code) as our application not only dealt in many currencies, but in many countries and time zones. More about that later.

The methods of ExchRate are as follows:

Of particular interest are  invert() and propagate(): the former creates an exchange rate that is the inverse of the given one, while the latter combines two exchange rates to create a single resultant exchange rate.  In the first case, the inverse of the exchange rate 

would be 

In the second case, combining 

and 

would result in

You may perhaps have noticed that we didn't integrate the TimeStamp values into our Exchange Rate methods - this was put in because clearly exchange rates only apply at a particular point in time. Ideally, the convert() methods should have been tagged with a TimeStamp, and therefore most other methods dealing with the ExchRate class.  Now most computer applications apply at some moment in time - they could be called "synchronic", whereas in real life things change across time ("diachronic"). So it was reasonable to leave the time stamp off the exchange rate.  We left it in, however, as a pointer to a wider scope that we could implement at some time in the future.  In fact, in my experience, the time dimension is always the hardest aspect of  computer applications to implement. 

This also illustrates a problem with the "big bang" approach to system development: if you don't have time to "do it right the first time" (you never do), you must build in enough flexibility so that you can move there incrementally, preferably without destroying your working system.   

Date, TimeStamp and Time Zone (TimeTz) classes

This seems like a good time to talk about dates, timestamps and time zones.  Our application had to deal with time zones right around the world, as we had to support someone in Tokyo buying a stock that was listed on the Toronto Stock Exchange on the other side of the planet.   Perhaps in hindsight we should have given our classes different names, as Java has some of these classes, both in the Java.util and Java.sql packages, but in practice this didn't cause confusion as we hid the Java.util classes behind our own.   We couldn't hide the Java.sql classes, but the spelling difference (see below) helped! 

We did have to do a lot of thinking about what times and dates really mean, as this is something that the designers of most business applications never have to think about.   We decided to hold times in UTC (Coordinated Universal Time), which is based on Greenwich, UK, and does not change with Daylight Savings Time (DST).  So we had to know which time zones particular stock exchanges were in, and which time zones our users would be in.  When you are dealing with a 7/24, world-wide application, the only notation that tells you whether two events are simultaneous is UTC.  

A time zone not only determines how many hours ahead of or behind UTC the location is, but also when they switch from and to DST - if in fact they do (Japan does not switch nor does the province of Saskatchewan in Canada).  It turned out that the version of Java we were using had a very incomplete set of time zones, but an excellent mechanism for building new ones!   A major part of the problem, as Java has found out, is that there is no generally agreed on standard for time zone names.  Java (from 1.2 on) seems to use a convention of "area/city", but one of the areas is America, so there are zones with names like America/Winnipeg, which is not really acceptable in a Canadian application!  Not to mention America/Manaus, America/Tortola and America/St_Kitts, but for some reason Atlantic/Bermuda!   And Java certainly does not seem to know much about Newfoundland, which is famous (at least up here) for being 1/2 hour out of step with the next time zone (honest!) - it is actually 3.5 hours behind UTC (not counting DST) - Java has it as 4 hours behind, but it does say Canada/Newfoundland (I think because it treats it as a zone, rather than a city).  We therefore used the commonly used Canadian abbreviations where possible, but these are only really unique within Canada  and I do not know whether they are encoded in any standards document.  The problem of coming up with unique, worldwide zone designations needs to be addressed, but I don't really feel that the Java approach is adequate.  However, we should give them credit for trying!  In case you were wondering, it is not enough to just use the offset in hours from UTC, as different  time zones may have the same offset but different rules for beginning and ending DST.  

The Java Date class includes time, but ours did not, which I feel is more logical.  Our TimeStamp class was more similar to the Java Date class, except that the Java Date class has a default time zone, which we felt would be confusing.  It's better to always have to state the time zone explicitly... when it matters....  Since all timestamps were held in UTC, we only needed time zones when handling input from, or output to, humans.   Our time zone class is actually a simple one: we just used the Java SimpleTimeZone class to build a list of time zones, identified by a 3-character abbreviation, "CST", "SST", etc., and then used the abbreviation as an optional part of a time stamp (default was UTC), e.g. 20021021T13:10:40678!CST.   Note that this can only be converted into a UTC time stamp if the date portion is present.

It actually took a little effort for old-guard programmers to start thinking in terms of time zones.  For example, the date does depend on the time zone: it can be Tuesday in Tokyo while it's Monday in Toronto, so you can convert from date plus time (UTC) to the local date, if you have the time zone, but you can't go from a date by itself  to UTC unless you know the time and time zone.  Actually there is an hour during the year, in time zones with DST, when the same local time repeats itself.

To make things even more interesting, the Java.sql package has Date and Timestamp (note the lower case 's'):  the SQL Date is very similar to ours, while Timestamp goes down to nanoseconds, which we really didn't need.  We provided conversion methods between our classes and the corresponding Java.sql ones, so that we could store our data in relational databases.

Bool class

Just to get this class out of the way, I will give a brief description of this class.  We decided we needed a Bool class mostly because we built a rules-driven decision tool which specified its rules in XML.  A patent is pending on this work: "Rules-Based Engine for Validating Financial Transactions".  I hope you can read legalese, as I can't, and I helped to write the thing!  

A couple of interesting attributes of this class are:

• its serialized form is "1" or "0" - this is because "1" and "0" are more suitable for multi-language support than "true" and "false"
• in its constructor we treated the null string as a true value.

The equals() method returns true if and only if the argument is not null and is a Boolean object that contains the same boolean value as this object.   For obvious reasons, we defined two public static final objects called TRUE and FALSE.

AccountId, Market, InstrumentId, and Symbol classes

We are now getting into an area which is less standardized (or standardizable). The lack of standardization in the industry means that we cannot specify classes that will be usable world-wide.  However, hopefully the following remarks will give some of the flavour of what we felt was needed for our particular application..

In our case, the account ID object was comprised of three parts:

- identifier (required)
- optional firm
- optional system ID

It was basically used as an identifier.

A Market object was identified by its Reuters code, and had attributes such as time zone, open and close times, list of holidays, country code and quote currency.   The open and close times were reloaded at the start of every day, as occasionally a particular market would be closed unexpectedly, for varying amounts of time, e.g. an hour or a half-day.  In addition the open and close times could be different for different financial instruments, so this information had to be stored, and reflected in the methods we provided.

InstrumentId was constructed out of a schema (a number) and a financial instrument ID. The schema numbers indicate what coding scheme is used for the financial instrument ID. The schema numbers are as follows:

A Symbol object identified something that is traded in a market.  It was constructed out of a market ID, symbol, and country code.  This reflects the fact that a symbol is only unique within a market.  Either market or country will usually be present - if both are missing, we used the default country.