@UnitAPI#JSR363

The First IoT JSR: Units of Measurement

JSR-363Werner Keil | Otávio Santana@wernerkeil | @otaviojava@UnitAPIhttps://www.jcp.org/en/jsr/detail?id=363http://unitsofmeasurement.github.io

@UnitAPI#JSR363

What is JSR-363?

6,370.98 milesA Quantity

A Unit

@UnitAPI#JSR363

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);

@UnitAPI#JSR363

What is JSR-363?

Interfaces and abstract classes supporting unit operations including:Checking of unit compatibility;Expression of measurement in various units; andArithmetic operations on units.

Concrete classes implementing standard unit types (base, derived), unit conversion and representation.

A framework supporting robust representation and correct handling of quantities.JSR 363 establishes safe and useful methods for modeling physical quantities.

@UnitAPI#JSR363

System of UnitsSystem 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…

Système

International d'Unités

@UnitAPI#JSR363

DimensionAllows 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!)

@UnitAPI#JSR363

QuantityA 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 …

… ∞

@UnitAPI#JSR363

Unit ConversionThe 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

@UnitAPI#JSR363

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.)

@UnitAPI#JSR363

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

@UnitAPI#JSR363

Conversion problemsThese 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 UK28 Days … Day Sidereal / Day Calendar38 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;

@UnitAPI#JSR363

What is the problem, in code?

float distance = 6370.98; //in milesfloat speed = airplane.getSpeed(); //in km/hSystem.out.println(“TTD: “ + (distance/speed) + “ h”);

6,370.98 milesA Quantity

A Unit

@UnitAPI#JSR363

What is JSR-363, in code?

Quantity<Length> distance = Quantities.getQuantity(6370.98, USCustomary.MILE);Quantity<Speed> airplaneSpeed = getAirplaneSpeed();Quantity<Time> timeToDest = (Quantity<Time>)distance.divide(airplaneSpeed);System.out.println(“TTD: “ + timeToDest.to(Units.HOUR));

TTD: 10.84983093613525 h

@UnitAPI#JSR363

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.

@UnitAPI#JSR363

JSR-363: Internal StructureJSR-363 is broken down into the following packages:

Package Descriptionjavax.measure Core API interfaces (e.g. Dimension, Quantity, Unit)javax.measure.format [optional] Interfaces for quantity/unit formatting and parsingjavax.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.)

@UnitAPI#JSR363

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, modularlibraries, we live and sometimes forestallthe ideas behind Java ME 8 or Jigsaw andoffer great flexibility to IoT solutions

@UnitAPI#JSR363

JSR-363 timelineMarch 11, 2014: SubmittedApril 7, 2014: Creation approvedDec 2014 – January 2015: Early Draft (done)Q3/2015 – Q4/2015: Public Review (approved)Q2/2016 : Final DraftQ3/2016 : Final Release

@YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363

Action

!

Images: Showtime / Fox 21

@UnitAPI#JSR363

Links to JSR-363Public mailing list(s) and/or forum(s)

Units-Dev on Google GroupsUnits-Users on Google GroupsEG only mailing list on java.net, archive fully visible (while

java.net exists)JSR detail page on JCP.org: https://www.jcp.org/en/jsr/detail?id=363

Project website on GitHub: unitsofmeasurement.github.io

@YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363

Q & A