Quantity and Measure Toolbox

Quantity and Measure Toolbox

The Quantity and Measure Toolbox is conceptually a simple toolbox but with a very complex, cross-cutting concern, implementation. The simple goal is to provide a common interface for all quantities of different mathematical subtypes. Why ? Because business applications deal with quantities all the time (e.g. periods of time, dates, money amounts, lengths, weights ... ). More sophisticated / narrows spectrum applications, may also need to work with coordinates or mathematical structures like vectors and matrices. Engineering oriented applications will need to work with different units for the same quantity and make calculations with them.
All these quantities are expressed in units witch,from an internationalization/localization point of view, vary and must be converted from one to another.

The Quantity and Measure Toolbox is an essential toolbox in MiddleHeaven as it provides the basic data types ,units and conversions. We may think of it as an upgraded version of java.lang basic types.

Quantity , Units and Measurables

When we measure something we are comparing the size of a quantity with another reference size of the same quantity. This reference is called the standard and it size is called unit The standard size for the quantity defines an unit of measure. So, a measure is always a ration between the size of the standard (the unit) and the size of the quantity you are interested in measuring.

In physics if you can measure a certain thing, then you can come up with an unit and a number that relates the size of the measurable to the size of the unit. Not all things that exist are measurable and not all units have the same practical value. The International System of Units ( abbreviated SI) compiles the essential measurables and respective units. For example, second is the unit of time, time is the quantity and time period is the measurable. Kelvin is the unit of (thermodynamic) temperature , temperature is the quantity and temperature interval the measurable.
For simplicity MiddleHeaven calls quantity to the association of the unit with the ratio to the unit; and measurable to the underlying physical property the quantity quantifies. Quantities are thus implementations of Quantity. Quantity only defines a getUnit method that returns a unit of the same measurable than the quantity. So if the quantity is of temperature, the unit also is of temperature.

Quantities can be operable upon by means of operations like sum or multiplication, however some rules apply. The operations made to he numeric part of the quantity must also be made to the unit part of the quantity. Meaning no quantities can be summed together if their units are different and multiplication applies to the units them self (e.g. 2m(meter) x 3m = 6 m² (square-meter)).Understand how the unit is the same (meter) and only its dimension was incremented.

Model

The Quantity and Measure Toolbox type model is quite vast. It would be confusing to show you all the model at once so we are going to break it minor pieces. Each of these pieces concerns a specific subtype of quantity:

• Structures - for working with vectors, matrices, rings, fields, and other types of mathematical structures
• Number - for working with dimensionless quantities like integers, reals and complexes. Operations and relations are based on the real mathematical structures underlying those quantities
• Measure - for working with measures including error propagation operations (it leverage number operations together with unit and dimension operations)
• Money - for working with many and currency related amounts. Introduces Currency and a special unit and provides specific integer based operations ( and not decimal operations) to hand money amounts without loss.
• Time - for working with periods, calendars, days, dates , weekends and other time related quantities. Also includes other objects and concepts like clocks, time zones and ephemeris
• Coordinates - for working with Coordinate and Coordinate Reference Systems and conversions.
• Utilities - several generic utility classes like Interval and Range that can be used in different contexts and are completely compatible with the other Quantity and Measure Toolbox types.

One of MiddleHeaven goals is to embraces and implement common applications design patterns and provide them "out-of-the-box". Money is such an examples. Integrated with the Quantity and Measure Toolbox, Money is supported from the beginning and integrated within a larger concept instead of simply implementing a poor-men version. As business commonly implies money operations we hope Money will simplify daily complex money based operations.

Under the Hood

All the concepts in the Quantity and Measure Toolbox may be familiar to you if have some knowledge of science - specially physics - or if you have crossed paths with the JScience project. Some may wonder why Quantity and Measure Toolbox is so close to JScience but MiddleHeaven in not implemented on top of it. Well, this is a twofold trade-off. First JScience is based on the use of double for numeric type and not objects. This is a problem as encapsulation is impossible. You can put a double inside any object, but not an object inside double. On the other hand JScience has goals concerning speed and real-time computing that MiddleHeaven has not. However MiddleHeaven's Quantity and Measure Toolbox is based on factories (NumberFactory) in order to provide the real implementation for the data types, specifically the numeric types. So, it is possible to conceive an engine using JScience under the hood for performance issues. If you really want it you are free to implement and contribute it to the project. This is true for any extension you can think of for MiddleHeaven. This is the main reason it's open source.

As a development insight: MiddleHeaven is a one men efford to encapculate good thrid party API, bind them onto a single simple API and promote design patterns and implementation for extensibility and decoupling. Its really an atlantic job, so the project is bound to be very "curved around it self". The design was carefully thought and analysed - and some times even redone - to cope with the simple objectives.

For those with their eyes on Java 1.7 and JSR 310 - Date and Time API may wonder why MiddleHeaven has its own time API. When MiddleHeaven development started no such JSR existed, only Joda Time , Time and Money and other API existed. On the other hand, Quantity and Measure Toolbox starts from a concept : quantity , so all quantities and units can relate to each other. Time being a very important quantity in business systems ( along with money) was not conceivable to implement the API without support for time operations, specially because no such support exist in standard java. So, we needed integration and abstraction.
Because JSR 310 does not have quantity unification concern in mind it will never be directly compatible with MiddleHeaven. An abstraction on top of JSR 310 will always be necessary in order to use its functionality can be used from MiddleHeaven. Thus the choice was made to create a simple, elegant, practical interface for time manipulation and all calculations where delegated to classes that can be changed and implemented for different underlying technology.
This façade API resulted in one very similar to JSR 310 and this is no coincidence, both, MiddleHeaven Time toolbox and JRS 310 models are brewed from the same inspirations sources ( like Joda Time API and Time and Money API) and baked with he same well establish international standards and other scientific knowledge. The result is bound to be similar. Also if MiddleHeaven is to be used in the daily routines, its syntax and types must be simple and mnenomic.
MiddleHeaven is not designed to supplant third party API but to flourish upon them and feel the gaps. JSR 310 is a great example of this. Before JSR 310 and Java 1.7 MiddleHeaven can leverage Java standard Date and Calendar classes to implements all the time calculations but when JSR 310 comes out, MiddleHeaven can implement a new time engine based upon the new constructs. In the future this can be true for any other not currently foreseen API.
Is important to remember that reutilization and API stability and third party API independence is the main goal for MiddleHeaven. We will see this concept at work in many other toolboxes as we visit them (e.g. Report Toolbox and Chart Toolbox). Keep in mind MiddleHeaven is design to resist time. Leveragering third party API with a clean simple façade API is the most simpler, object oriented, elegant, way to do this. Encapsulation allow for a complete change and modification of the underlying engines without altering the API your application use. so, if, some time in the future some better API spawns you application can take advantage of it without changing any code, just upgrading the MiddleHeaven jar and dependencies.

A Joda Time based implementations was also possible, but because JSR 310 is so near no effort was made to support Joda Time.