1. @UnitAPI#JSR363DevoxxBE
The First IoT JSR: Units of Measurement
JSR-363
Werner Keil | Otávio Santana | Mohamed Taman
@wernerkeil | @otaviojava | @_tamanm
@UnitAPI
https://www.jcp.org/en/jsr/detail?id=363
http://unitsofmeasurement.github.io

2. @UnitAPI#JSR363DevoxxBE
The First IoT JSR: Units of Measurement
Werner Keil
•Consultant – Coach
•Creative Cosmopolitan
•Open Source Evangelist
•Software Architect
•Spec Lead – JSR363
•JCP EC Member
[www.linkedin.com/in/catmedia]
Twitter @wernerkeil | Email werner@catmedia.us

3. @UnitAPI#JSR363DevoxxBE
What is JSR-363?
5,999 miles
A Quantity
A Unit
Brussels
São Paulo

4. @UnitAPI#JSR363DevoxxBE
Why do we need JSR-363?
There are no specifications or standards for handling units in Java.
The current solution is to use primitives, that don’t provide any Type
Safety.
The errors are difficult to find using unit testing:
Interface and Internationalization (e.g. radian/degree, meters/feet);
Arithmetic operations (e.g. overflow);
Conversion between units (e.g. from same domain);

5. @UnitAPI#JSR363DevoxxBE
5,999 miles
A Quantity
A Unit
What is the problem, in code?
int distance = 5999; //in miles
float speed = airplane.getSpeed(); //in km/h
System.out.println(“TTD: “ + (distance/speed) + “ h”);

6. @UnitAPI#JSR363DevoxxBE
What is JSR-363?
A framework supporting robust representation and correct handling of
quantities.
JSR 363 establishes safe and useful methods for modeling physical
quantities.

7. @UnitAPI#JSR363DevoxxBE
What is JSR-363?
Interfaces and abstract classes supporting unit operations including:
Checking of unit compatibility;
Expression of measurement in various units; and
Arithmetic operations on units.
Concrete classes implementing standard unit types (base, derived), unit
conversion and representation.

8. @YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE
CORE THEORY AND CONCEPTS
Some Basic Science behind the API

9. @UnitAPI#JSR363DevoxxBE
What is a Unit?
c. (a) Any determinate quantity, dimension, or magnitude adopted as a
basis or standard of measurement for other quantities of the same kind
and in terms of which their magnitude is calculated or expressed.
Oxford English Dictionary
Or … A well defined standard we all know?
Unit Definition
Second The duration of 9,192,631,770 periods of the radiation corresponding to the
transition between the two hyperfine levels of the ground state of caesium 133 atom
Kilogram The mass of the international prototype kilogram [a very special lump of metal]
Metre The distance travelled by light in a vacuum in
3.3356409519815204957557671447492e-9 seconds

10. @UnitAPI#JSR363DevoxxBE
A Standard Measurement …
“The nice thing about standards is that you have so many to choose
from.”
Andrew S. Tanenbaum,
Computer Networks 2nd ed., p. 254
Foot
Mile
Yard Chain
Fathom
Furlong
InchNautical Mile
Statute Mile
astronomical unit (AU)
Light year
Parsec(or meter)
Passus (roman)
Hand
ångström
Scots/Welsh/English Mile
Metre fermi micron
Thou (or mil)League
rod/perch/pole
nail
Barleycorn
link
ell Cubitfinger
palm
Poppyseed
Milli Centi Kilo

11. @UnitAPI#JSR363DevoxxBE
System of Units
System International d’Unites (SI)
The accepted basis for most scientific and engineering
activities.
Standard units for key physical quantities
(length, time, power etc.)
Standard prefixes
(kilo/micro etc.)
Standard dimensions…

12. @UnitAPI#JSR363DevoxxBE
Dimension
Allows analysis of a quantity by the rational powers of the 7 fundamental
dimensions (quantities are compatible when they have the same
dimensions):
length (L), mass (M), time (T), electric charge (I), absolute temperature
(Θ), amount of substance (N) and luminous intensity (J)
Examples:
Speed = length/time - it’s dimensions are L=1,T=-1 (rest 0) (e.g. metre/second - ms-1)
Acceleration is speed/time (m/s/s or ms-2) L=1, T=-2
Force is mass x acceleration M x ((length/time)/time) or M=1, L=1, T=-2
Molar Entropy: M=1 L=2 T=−2 Θ=−1 N=−1 (trust me!)

13. @UnitAPI#JSR363DevoxxBE
Quantity
A physical attribute of a thing. Something that can be measured and has
units. Compatible quantities have the same dimension…
Examples:
• Time
• Length
• Speed
• Amount of Substance
• Luminous Intensity
• Volume
• Mass
• Force
• Power
• Electrical Current
• Magnetic Flux Density
• Volumetric Flow Rate
• Fuel Economy*
• Percentage
• Eggs per carton
• Sheep per hour
• Bits and bytes …
… ∞

14. @UnitAPI#JSR363DevoxxBE
Unit Conversion
The process of conversion depends on the specific situation and the
intended purpose. This may be governed by regulation, contract,
technical specifications or other published standards.
Wikipedia

15. @YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE
LEARNING FROM THE PAST…
Some examples of how things can go wrong…

16. @UnitAPI#JSR363DevoxxBE
Some real-life mishaps…
NASA “Star Wars” Initiative, 1983
Sea Level

17. @UnitAPI#JSR363DevoxxBE
Some real-life mishaps…
[Cost $125M]
“Preliminary findings indicate that one team used US/English units (e.g.
inches, feet and pounds) while the other used metric units for a key
spacecraft operation.”
NASA Mars Climate Orbiter, 1999

18. @UnitAPI#JSR363DevoxxBE
1983: The Gimli “Glider”
Photo: Wayne Glowacki
Maintenance workers performed a test that estimated that 7,682 litres of
fuel were in the tank. They knew they needed 22,300 kilograms of fuel
for the remaining flight, so the question was, How much fuel, in litres,
should be pumped from the fuel truck into the aircraft? They were
forced to resort to a manual calculation:
They multiplied 7,682 L by 1.77, the density of the fuel provided by the
refuelling company on their documentation: The aircraft, according to
their calculations, currently had 13,597 kg of fuel.
Subtracting from 22,300 kg, they decided they needed to add 8,703 kg of
fuel.
Dividing by 1.77 — the same density used in the previous calculation —
yields 4,916 L, which was pumped into the aircraft.
However, 1.77 was the density of the fuel in pounds per litre (lb/L), not
kilograms per litre (kg/L); the correct figure for kg/L would have been
0.80. As a result, they ended up with less than half of the required
amount of fuel on board. (The fuel's density depends on
characteristics of the fuel, so it's not a constant, and the value must
be taken from documentation accompanying the fuel.)

19. @UnitAPI#JSR363DevoxxBE
2001: Escape of the 250kg tortoise
Los Angeles Zoo lent Clarence, a 250-kilogram, 75-
year-old Galapagos tortoise, to the Exotic Animal
Training and Management Program at Moorpark
College in Moorpark CA.
The first night in his new home, Clarence wrecked it:
“He just pushed one of the fence poles right
over,” said Moorpark's Chuck Brinkman.
The L.A. Zoo warned that Clarence was big, and
needed an enclosure for an animal that “weighs
in at about 250”, so that's what the college
built.
Unfortunately, they thought the zoo meant 250
pounds, so the enclosure wasn't adequate for
holding a 250-kilogram (552 lbs) beast.
Clarence

20. @UnitAPI#JSR363DevoxxBE
Conversion problems
These are examples of confusion on the units in application.
But there is also ambiguity on the unit itself:
10 Gallons … Gallon Dry / Gallon Liquid - Gallon US / Gallon UK
28 Days … Day Sidereal / Day Calendar
38 Degrees … Degree Celsius / Degree Fahrenheit / Degree Angle
And the wrong conversion factors:
static final double PIXEL_TO_INCH = 1 / 72;
double pixels = inches * PIXEL_TO_INCH;

21. @YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE

22. @UnitAPI#JSR363DevoxxBE
What is the problem, in code?
int distance = 5999; //in miles
float speed = airplane.getSpeed(); //in km/h
System.out.println(“TTD: “ + (distance/speed) + “ h”);
5,999 miles
A Quantity
A Unit

23. @UnitAPI#JSR363DevoxxBE
What is JSR-363, in code?
Quantity<Length> distance = Quantities.getQuantity(5999,
US.MILE);
Quantity<Speed> airplaneSpeed = getAirplaneSpeed();
Quantity<Time> timeToDest =
(Quantity<Time>)distance.divide(airplaneSpeed);
System.out.println(“TTD: “ + timeToDest.to(Units.HOUR));
TTD: 10.216345960256564 h

24. @UnitAPI#JSR363DevoxxBE
Who is going to use JSR-363?
Java developers who work with physical quantities need to handle
measurements in their programs.
Inadequate models of physical measurements can lead to significant
programmatic errors.
Platform providers and developers can provide and use a more
well-defined API.
Embedded developers can have less error-prone, more self-
documented code.

25. @UnitAPI#JSR363DevoxxBE
JSR-363: Internal Structure
JSR-363 is broken down into the following packages:
Package Description
javax.measure Core API interfaces (e.g. Dimension, Quantity, Unit)
javax.measure.format [optional] Interfaces for quantity/unit formatting and parsing
javax.measure.quantity [optional] Interfaces for quantity types (e.g. Mass, Length)
javax.measure.spi [optional] Service Provider Interface (implementation discovery)
Reason: We target very small devices running Java ME (CLDC 8) for IoT
applications (e.g. sensors, wearables, gateways etc.)

26. @UnitAPI#JSR363DevoxxBE
JSR-363: Systems and
ExtensionsOn top of JSR-363 we offer support
for various unit systems:
• Reusable Quantities
• SI System
• Common Systems (US, Imperial)
• ISO 80000
• UCUM
Reason: By providing small, modular
libraries, we live and sometimes forestall
the ideas behind Java ME 8 or Jigsaw and
offer great flexibility to IoT solutions

27. @YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE
DIAMONDS ARE FOREVER
ISO / IEC 80000
Images: Eon Production

28. @YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE

29. @UnitAPI#JSR363DevoxxBE
Demo 1: Strongly type your code
V2COM created an embedded power measurement system that tracks
how much individual circuits are using in an industrial application.
We want to:
1. Avoid unit ambiguity
2. Avoid quantity ambiguity that lead
to calculation errors

30. @UnitAPI#JSR363DevoxxBE
Demo 2: Intel Edison
Anticipating Intel’s JavaOne 2015 announcement of full Java support on
IoT devices like Intel Edison, I made
Java SE 8 and JSR 363 work on
Intel Edison in March 2015.
We want to:
1. Avoid unit ambiguity when
receiving
data from sensors or propagating
it to Cloud solutions like
Intel IoT Analytics
2. Format a measurement without
loss of data

31. @YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE Images: Columbia Pictures / Eon Production

32. @UnitAPI#JSR363DevoxxBE
How can YOU make JSR-363 work?
It’s still an active JSR: YOU can get involved.
We are participating in the Adopt-a-JSR program - 3 JUGs have so far
joined the EG! (Morocco JUG, SouJava, JUG Chennai).
You can download the code, file JIRA / GitHub Issues for bugs or needs
and follow the discussion in our mailing lists.
We’re always looking for new ideas and use cases.

33. @YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE

34. @UnitAPI#JSR363DevoxxBE
JSR-363 timeline
March 11, 2014: Submitted
April 7, 2014: Creation approved
Dec 2014 – January 2015: Early Draft (done)
Q3/2015 – Q4/2015: Public Review (tied with DevoXX)
Q2/2016 : Final Draft
Q3/2016: Final Release

35. @UnitAPI#JSR363DevoxxBE
Links to JSR-363
Public mailing list(s) and/or forum(s)
Units-Dev on Google Groups
Units-Users on Google Groups
EG only mailing list on java.net, archive fully visible
The JSR page on JCP.org…
And two other “JSR project websites”:
Main project website is on GitHub (unitsofmeasurement)
Java.net site is used for downloads or JIRA.
And you can get sample code at our GitHub.

36. @UnitAPI#JSR363DevoxxBE
Building JSR-363 for Java SE
You need Java SE 8 SDK + IDE (Like Eclipse)
git clone https://github.com/unitsofmeasurement/unit-api.git
git clone https://github.com/unitsofmeasurement/unit-ri.git
or
git clone https://github.com/unitsofmeasurement/uom-se.git
Use Maven to compile & install
mvn install and you’re done.

37. @UnitAPI#JSR363DevoxxBE
Building JSR-363 for Java ME
You need Windows, Java SE 8 SDK, Eclipse or Netbeans, Java ME 8 SDK
+ Java ME 8 SDK Plugins (Netbeans or Eclipse)
git clone https://github.com/unitsofmeasurement/unit-api.git
git clone https://github.com/unitsofmeasurement/unit-ri.git
Create new Java ME 8 Project for API
Create new Java ME 8 Project for RI
Create new Java ME 8 Project for your App
Or
git clone https://github.com/unitsofmeasurement/uom-demos.git
> javame/medemo (see instructions in README.md)

38. @YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE

39. @YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE