Download The First IoT JSR: Units of Measurement JSR-363

The First IoT JSR: Units of Measurement
JSR-363
Leonardo Lima & Otávio Santana
@leomrlima & @otaviojava & @UnitAPI
https://www.jcp.org/en/jsr/detail?id=363
http://unitsofmeasurement.github.io
www.v2com.mobi
#JSR363JavaOne
@leomrlima & @otaviojava
The First IoT JSR: Units of Measurement
Otávio Santana
[about.me/otaviojava]
• Software engineer
• From Salvador, Brazil
• Java Champion, SouJava JUG Leader
• Apache and OpenJDK Committer
• JSR 363 Expert Group member
• Representative at JCP Executive Committee
#JSR363JavaOne
@leomrlima & @otaviojava
The First IoT JSR: Units of Measurement
Leonardo Lima
[www.linkedin.com/in/leomrlima]
• Computer engineer, server & embedded sw developer
• From São Paulo, Brasil
• CTO at
• Spec Lead – JSR363
• Representative at JCP Executive Committee
#JSR363JavaOne
@leomrlima & @otaviojava
London
A Unit
5,898 ??????
A Measurement
São Paulo
#JSR363JavaOne
@leomrlima & @otaviojava
What is the problem, in code?
A Unit
5,898 ??????
A Measurement
int distance = 5898; //in miles
float speed = airplane.getSpeed(); //in km/h
System.out.println(“ETA: “ + (distance/speed)
hours”);
#JSR363JavaOne
+ “
@leomrlima & @otaviojava
Some examples of how things can go wrong…
LEARNING FROM THE PAST…
#JSR363JavaOne
#DVXFR14{session hashtag}
@leomrlima
@YourTwitterHandle
& @otaviojava
Some real-life mishaps…
NASA “Star Wars” Initiative, 1983
Sea Level
#JSR363JavaOne
@leomrlima & @otaviojava
Some real-life mishaps…
NASA Mars Orbiter, 1999
[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.”
#JSR363JavaOne
@leomrlima & @otaviojava
1983 The Gimli “Glider”
maintenance workers performed a test that estimated that 7,682 liters 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 liters, 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 refueling
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 liter (lb/L), not
kilograms per liter (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.)
#JSR363JavaOne
Fotos: Wayne Glowacki | Wikia „Herr der Ringe“
@leomrlima & @otaviojava
2001: Escape of the 250Kg tortoise
Clarence
Los Angeles Zoo lent Clarence, a 250-kilogram, 75-yearold 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.
#JSR363JavaOne
@leomrlima & @otaviojava
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;
#JSR363JavaOne
@leomrlima & @otaviojava
Why do we need a specification?
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);
#JSR363JavaOne
@leomrlima & @otaviojava
WHAT IS JSR-363?
#JSR363JavaOne
#DVXFR14{session hashtag}
@leomrlima
@YourTwitterHandle
& @otaviojava
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.
#JSR363JavaOne
@leomrlima & @otaviojava
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) and unit
conversion.
#JSR363JavaOne
@leomrlima & @otaviojava
Some Basic Science behind the API
CORE THEORY AND CONCEPTS
#JSR363JavaOne
#DVXFR14{session hashtag}
@leomrlima
@YourTwitterHandle
& @otaviojava
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
#JSR363JavaOne
@leomrlima & @otaviojava
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
Scots/Welsh/English Mile
Mile
Metre
(or meter)
#JSR363JavaOne
Chain
Furlong
Poppyseed
Barleycorn
Nautical Mile
Inch
Thou (or mil)
Passus (roman)
League Fathom
Foot finger
ell
Cubit
astronomical unit (AU)
Hand palm rod/perch/pole
Light year fermi
nail
micron
Parsec
ångström
Milli Centi Kilo
Statute Mile
Yard
link
@leomrlima & @otaviojava
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…
#JSR363JavaOne
@leomrlima & @otaviojava
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!)
#JSR363JavaOne
@leomrlima & @otaviojava
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
#JSR363JavaOne
• 
• 
Magnetic Flux Density
Volumetric Flow Rate
• 
• 
Fuel Economy*
Percentage
• 
• 
• 
Eggs per carton
Sheep per hour
Bits and bytes …
…
∞
@leomrlima & @otaviojava
#JSR363JavaOne
#DVXFR14{session hashtag}
@leomrlima
@YourTwitterHandle
& @otaviojava
What is the problem, in code?
A Unit
5,898 miles
A Measurement
int distance = 5898; //in miles
float speed = airplane.getSpeed(); //in km/h
System.out.println(“ETA: “ + (distance/speed)
hours”);
#JSR363JavaOne
+ “
@leomrlima & @otaviojava
What is JSR-363, in code?
Quantity<Length> distance = Quantities.getQuantity(5898,
US.MILE);
Quantity<Speed> airplaneSpeed = getAirplaneSpeed();
Quantity<Time> eta =
(Quantity<Time>)distance.divide(airplaneSpeed);
System.out.println(“ETA: “+ eta.to(SI.HOUR));
ETA: 10.54655… h
#JSR363JavaOne
@leomrlima & @otaviojava
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 better defined API
Embedded developers can have less error-prone, more self-documented
code
#JSR363JavaOne
@leomrlima & @otaviojava
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 Java ME (CLDC 8) for IoT applications
(e.g. sensors, wearables, gateways etc.)
#JSR363JavaOne
@leomrlima & @otaviojava
#JSR363JavaOne
#DVXFR14{session hashtag}
@leomrlima
@YourTwitterHandle
& @otaviojava
Demo 1: Strongly type your code
We have 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
#JSR363JavaOne
@leomrlima & @otaviojava
Demo 2: Data Transmission
We want to transmit a measurement over the wire to another receiver.
We want to:
1.  Avoid unit ambiguity on receiver
2.  Format a measurement without loss
of data
#JSR363JavaOne
@leomrlima & @otaviojava
#JSR363JavaOne
#DVXFR14{session hashtag}
@leomrlima
@YourTwitterHandle
& @otaviojava
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 Issues for bugs or needs and follow the
discussion in our mailing lists.
We’re always looking for new ideas and use cases.
#JSR363JavaOne
@leomrlima & @otaviojava
JSR-363 timeline
March 11, 2014:
Submitted
April 7, 2014:
Creation approved
Dec 2014 – January 2015:
Early Draft (approved)
Q3/2015 – Q4/2015:
Public Draft (tied with JavaOne)
Q1/2016 :
Final Draft
Q2/2016:
Final Release
#JSR363JavaOne
@leomrlima & @otaviojava
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.
#JSR363JavaOne
@leomrlima & @otaviojava
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.
#JSR363JavaOne
@leomrlima & @otaviojava
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
this will compile!
Create new Java ME 8 Project for RI
this will break! We’re still Work in Progress J
Create new Java ME 8 Project for your App
#JSR363JavaOne
@leomrlima & @otaviojava
#JSR363JavaOne
#DVXFR14{session hashtag}
@leomrlima
@YourTwitterHandle
& @otaviojava
#JSR363JavaOne
#DVXFR14{session hashtag}
@leomrlima
@YourTwitterHandle
& @otaviojava