The Quantity and Measure Toolbox is conceptually a simple toobox but with a very complex, crosscutting 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 sofisticaded / 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 internacionalization/localization point of view, vary and must be converted
from 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.
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 bettween 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 ( abreviated SI) compiles the essencial
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<M extends Measurable>. 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 m2 (square-meter)).Understand how the unit is the same (meter) and only its dimension was incremented.
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:
Interval and Range that can be used in different contexts
and are completely compatible with the other Quantity and Measure Toolbox types.
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 JSience
project.
Some may wonder why Quantity and Measure Toolbox is so close to JSience 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 carfully thought and analized - 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 suport 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 sintax 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. Leveraging 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.