Use of JCP site is subject to the JCP Terms of Use and the Oracle Privacy Policy

JSRs: Java Specification Requests

JSR 363: Units of Measurement API

Stage Access Start Finish Final Release Download page 13 Sep, 2016 Final Approval Ballot View results 23 Aug, 2016 05 Sep, 2016 Proposed Final Draft Download page 19 Jul, 2016 Public Review Ballot View results 12 Jan, 2016 25 Jan, 2016 Public Review Download page 18 Nov, 2015 11 Jan, 2016 Early Draft Review Download page 29 Dec, 2014 27 Jan, 2015 Expert Group Formation 08 Apr, 2014 27 Oct, 2014 JSR Review Ballot View results 25 Mar, 2014 07 Apr, 2014 JSR Review 11 Mar, 2014 24 Mar, 2014

Status: Final

JCP version in use: 2.10

Java Specification Participation Agreement version in use: 2.0





Description:

This JSR specifies Java packages for modeling and working with measurement values, quantities and their corresponding units.



Expert Group Transparency:

Public Project Page

Public Communications

Issue Tracking



2.0This JSR specifies Java packages for modeling and working with measurement values, quantities and their corresponding units.

Team



Specification Leads Jean-Marie Dautelle Dautelle, Jean-Marie Werner Keil Keil, Werner Leonardo Lima V2COM Expert Group Jean-Marie Dautelle Desruisseaux, Martin

: Martin Desruisseaux JUG Chennai

: Rajmahendra Hegde Werner Keil Legrand, Karen

: Karen Legrand Otavio Santana Senior, Chris

: Chris Senior Almas Shaikh Mohamed Taman V2COM

: Leonardo Lima Contributors Red Hat

: Nathan Scott

List of compatible implementations for JSR 363

The following changes have been made to the original proposal.

2017.07.14 :

All links to java.net have been updated/replaced.

2016.02.16 :

All references to "unitsofmeasurement.org" have been replaced with "unitsofmeasurement.github.io."

2014.10.20 :

2.17 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

2014.06.10 :



2.15 Please describe how the RI and TCK will de delivered, i.e. as part of a profile or platform edition, or stand-alone, or both. Include version information for the profile or platform in your answer.

The minimum Java version for ME will be CLDC 8, making it compatible with Java SE 7 (Embedded).

Original Java Specification Request (JSR)

Identification | Request | Contributions



Section 1. Identification

Submitting Member: Werner Keil

E-Mail Address: werner.keil @ gmail.com

Telephone Number: +43 676 484 1153

Fax Number: -

Specification Leads: Jean-Marie Dautelle, Werner Keil, Leonardo de Moura Rocha Lima (V2COM)

E-Mail Addresses: jean-marie.dautelle @ airbus.com, werner.keil @ gmail.com, llima @ v2com.mobi

Telephone Numbers: +33 6 45 45 40 63, +49 176 36954273, +55 11 3031 3322

Fax Numbers: +33 1 69 75 58 85, -, +55 11 3031 3322

Initial Expert Group Membership:

Jean-Marie Dautelle

Martin Desruisseaux

Werner Keil

Karen Legrand

Daniel Leuck

Chris Senior

Mohamed Taman

V2COM

Supporting this JSR:

Alcatel Lucent

Austrian Standards Institute

British Telecom

Bundesamt für Eich- und Vermessungswesen (BEV)

CERN

ENEA (Italian National Agency for new technologies, Energy and Environment)

Fraunhofer-Gesellschaft

Gemalto M2M

Jeff Genender

Geomatys

IEM

ISO/TC 12

JUG Chennai

Guillaume Laforge

John Paul Morrison

MoroccoJUG

O2 Telefonica

The Open Geospatial Consortium (OGC)

Opower

Samsung

SFR Group

SouJava

Thales Group

Verticon, Inc.



Section 2: Request

2.1 Please describe the proposed Specification:

This JSR specifies one or more Java packages for the programmatic handling of physical quantities and their expression as numbers of units. The specification includes:

Interfaces and abstract classes for unit of measurement operations: Checking of unit compatibility Expression of a quantity in various units Arithmetic operations on units and quantities

Concrete classes implementing the standard types of units (such as base, supplementary, and derived) and unit conversions.

Classes for parsing unit specifications in string form and for formatting string representations of quantities

A set of predefined units based on at least one of ISO 80000 UN/CEFACT Unified Code for Units of Measure (UCUM) Unicode CLDR 24 and above



The API is targeted to the resource-constrained devices such as smart meters, medical devices, or similar and needs to be memory-efficient to run on. On the other hand it must perform to cope with incoming sensor data.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

Embedded (ME, SE)

2.3 The Executive Committees would like to ensure JSR submitters think about how their proposed technology relates to all of the Java platform editions. Please provide details here for which platform editions are being targeted by this JSR, and how this JSR has considered the relationship with the other platform editions.

The packages are primarily targeted at Java ME Embedded (CLDC, MEEP). This JSR should have few or no dependencies outside the packages and types defined by CLDC 8. Where applicable a RI may have dependencies in a different platform, if such specialized RI for Java SE Embedded was desired. The core API must be portable across all supported platforms and profiles.

2.4 What need of the Java community will be addressed by the proposed specification?

Java developers who work with physical quantities (such as developers in the scientific, engineering, medical, and manufacturing domains) need to be able to handle measurements of these quantities in their programs. Inadequate models of physical measurements can lead to significant programmatic errors. In particular, the practice of modeling a measure as a simple number with no regard to the units it represents creates fragile code. Another developer or another part of the code may misinterpret the number as representing a different unit of measurement. For example, it may be unclear whether a person's mass is expressed in pounds, kilograms, or stones.

Developers must either use inadequate models of measurements, or must create their own solutions. It is less than ideal for every developer to solve this problem. A common solution can be safer and can save development time for domain-specific work. This JSR proposes to establish safe and useful methods for modeling physical quantities.

Several popular programming languages like C++, F# (both natively) or C# (through extra libraries) provide this functionality now. We'd like to leverage Java especially in the IoT and Embedded sector with similar Units of Measurement support.

2.5 Why isn't this need met by existing specifications?

There are no specifications or common standards for handling units in Java.

The closest could be ICU4J version 52.1 and above, but the footprint of the entire library is significant (10MB), making it too big for even many Java SE Embedded use cases. Its creators aim at i18n and formatting, parsing, but deliberately left out other aspects like type-consistency or arithmetic operations as they are not in scope of Unicode. The Java Mobile Sensor API (JSR 256) had a similar rudimentary notion of units for look-up and parsing, but lacked e.g. a Quantity or Measure type ICU4J defines. JSR 256 is no longer supported by Java ME Embedded in CLDC 8 / MEEP 8, which is where this JSR comes into play.

2.6 Please give a short description of the underlying technology or technologies:

Developers frequently encounter the need to model units of measure, because objects in the real world are subject to these measures. When working with units, developers need to understand the mathematics of units, how to convert between systems, and how to format and parse string representations of units. Most of this work can be consolidated into one or two Java packages, which is a primary aim of this JSR. This package will help developers create safe, correct software to deal with common problem of modeling units.

Units give us a way to measure the physical world. There are many different units, partly because the world has different types of properties, such as length and mass, which are not interchangeable in normal physics. This type of property is sometimes called a "quantity" or a "dimension". The word "dimension" fits because of the orthogonality of these properties. For example "mass" and "length" cannot be exchanged. Further, when we multiply physical measures the dimensions add up as exponents. For example, length times length becomes length².

A large body of work exists that specifies the dimensions, meanings, and names of various physical quantities. In particular, the 11th General Conference on Weights and Measures in 1960 recommended a practical system of units of measurement, and gave it the name Systeme International d'Units (SI). SI defines units for the base dimensions of length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. SI also recognizes names and meaning of derived dimensions, such as area, volume, and force. For some (but not all) of these derived dimensions SI defines units, such as "liter" for a unit of volume and "newton" for a unit of force. SI does not have a special name for area, although other systems of measurement do (as in "acre").

Despite the rising prominence of the metric system (the SI system), many developers have to work with non-SI units, such as feet, miles, acres, and gallons. A measurement can be expressed as a number of any unit, so long as the unit has the same dimension as the measured quantity. For example, any measure of volume can be expressed as a number of liters or gallons, because liters and gallons are units of volume, and all volumes have the dimension of length3. Therefore, a measure expressed as a number of liters can be 'converted' to a number of gallons. Converting measures from one system of units to another is a common problem, but is subject to mathematics that can help to eliminate errors.

2.7 Is there a proposed package name for the API Specification? (i.e., javapi.something , org.something , etc.)

javax.measure

2.8 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?

No

2.9 Are there any security issues that cannot be addressed by the current security model?

No

2.10 Are there any internationalization or localization issues?

There are some internationalization issues that this JSR will address:

Which systems of units should be supported: The RI should support units in the SI system The British Imperial System and U.S. Customary Units may also be supported, at least by optional modules (similar to JSR 361 / MEEP parts of API can be optional to suit smaller devices)

Some units have locale-dependent spellings, such as 'liter' and 'litre'. Where it won't exceed available footprint the JSR will use Unicode CLDR like selected parts of the JDK or other JSRs already do. CLDR 24 or above support all relevant SI and other units including spelling and pluralization in at least 70 different languages. What suits the needs of the JSR we intend to leverage.



2.11 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?

Not directly. To some extent this JSR is a replacement for JSR 275, which was rejected for various reasons, many process-related, see https://jcp.org/en/jsr/detail?id=275 with a large number of even those voting against it recommending a successor to be filed. As Java ME Embedded (CLDC 8/MEEP) won't use JSR 256 it aims at some of its goals, too, but in a "Sensor Web" way rather than for a single device or JVM.

2.12 Please describe the anticipated schedule for the development of this specification.

Q1 2014: finalize expert group

Q2 2014: Early Draft of spec and API

Q3 2014: Public Review

Q1 2015: Final Release

2.13 Please describe the anticipated working model for the Expert Group working on developing this specification.

The primary means of communication will be via mailing lists units-dev@googlegroups.com for EG Members and similar active contributors and units-users@googlegroups.com for observers and other users of the API) and conference calls/hangouts, or meetings on IRC channels if deemed appropriate. Face-to-face meetings will be scheduled if needed and accessible by enough members.

2.14 Provide detailed answers to the transparency checklist, making sure to include URLs as appropriate:

The Units Of Measurement interfaces and their implementation in the JScience and UOMo projects are developed in an open source process. We intend to use the existing infrastructures:

https://code.google.com/p/unitsofmeasure/ as an inspiration for the API.

CI server and Maven repository provided by the GeoAPI project.

Wiki on Java.net:

Wiki on GitHub: http://unitsofmeasurement.java.netWiki on GitHub: https://github.com/unitsofmeasurement/unit-api/wiki

These projects are already publicly visible and accessible. In addition, the following communications already exist or will be established:

The Expert Group business is regularly reported on publicly readable aliases units-dev@googlegroups.com , units-users@googlegroups.com .

The schedule for the JSR is publicly available and updated regularly.

An issue-tracker can be shared with the Unit of Measurement project on Google Code: https://code.google.com/p/unitsofmeasure/issues/list . Where better suited we may use GitHub ( https://github.com/unitsofmeasurement ) or Java.net (JIRA) instead.

The unitsofmeasurement project has a track record in using open-source processes for almost half a decade.

The spec leaders demonstrated responsiveness to posts on the discussion board in JSR-275, which had the most active discussion board on jcp.org so far.

Werner Keil is a respected speaker at numerous conferences and JCP EC Member since 2008. He joined JSR-275 as EG Member and Co Spec Lead in 2005 and has spoken about that JSR and subsequent projects like Unit-API or Eclipse UOMo ever since. Jean-Marie Dautelle has been involved in Java and the JCP since JSR-1 (Real Time) and gained reputation e.g. as the only Individual EC Member to ever host an EC F2F (the "Boston Barn Meeting") Leonardo de Moura Rocha Lima spoke at JavaOne 2013 about related topics like Java ME and Smart Grid.

The terms of use required by the collaboration tools are the Google code ones (https://code.google.com/intl/de/projecthosting/terms.html) and GitHub Terms of Use (https://help.github.com/articles/github-terms-of-service)

2.15 Please describe how the RI and TCK will de delivered, i.e. as part of a profile or platform edition, or stand-alone, or both. Include version information for the profile or platform in your answer.

The RI will be implemented inside the open source project 'unitsofmeasurement.github.io'. We target stand-alone releases.

The minimum Java version for ME will be CLDC 8, for SE the minimum version is Java SE (Embedded) 8.

The minimum Java version for ME will be CLDC 8, making it compatible with Java SE 7 (Embedded).

( Note that this information has been updated from this original proposal on 2014.06.10)

2.16 Please state the rationale if previous versions are available stand-alone and you are now proposing in 2.13 to only deliver RI and TCK as part of a profile or platform edition (See sections 1.1.5 and 1.1.6 of the JCP 2 document).

There is no previous version.

2.17 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

We will be using the Standard Spec License for the JSR specification: http://jcp.org/aboutJava/communityprocess/speclead/final-license.txt, and the Apache 2.0 License for the RI and TCK:> http://www.apache.org/licenses/LICENSE-2.0.html

Note that this section has been updated from this original proposal.

We will be using the Standard Spec License for the JSR specification, and a BSD 3-Clause License for the RI and TCK.

2.18 Please describe the communications channel you have established for the public to observe Expert Group deliberations, provide feedback, and view archives of all Expert Group communications.

The communication channels will be forum/mailing lists units-dev@googlegroups.com for EG Members and similar active contributors and units-users@googlegroups.com for users/observers. As well as Twitter via @UnitAPI.

2.19 What is the URL of the Issue Tracker that the public can read, and how does the public log issues in the Issue Tracker?

An issue-tracker can be shared with the Unit of Measurement project on Google Code: https://code.google.com/p/unitsofmeasure/issues/list. Where better suited we may use GitHub (https://github.com/unitsofmeasurement) or Java.net (JIRA) The only requirement to log issues is a working user account.

2.20 Please provide the location of the publicly accessible document archive you have created for the Expert Group.

The 'unitsofmeasurement.github.io' project uses the publicly accessible archive at Google Code: https://code.google.com/p/unitsofmeasure/downloads/list In addition to that java.net https://java.net/projects/unitsofmeasurement/downloads Bintray https://bintray.com/unitsofmeasurement/downloads and hosting provided by the GeoAPI project may offer additional storage where required.

Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

Units of Measurement API

Eclipse UOMo

JScience

GeoAPI

ICU – International Components for Unicode

Underlying standards and specifications

ISO/IEC 80000

UN/CEFACT Common Codes

OGC Sensor Web Enablement

Martin Fowler: Quantity

Unicode CLDR

Unified Code for Units of Measure

HL7 FHIR: Quantity

3.2 Explanation of how these items might be used as a starting point for the work.

All authors and active contributors to above frameworks are involved. Those supporting the JSR are interested in contributing their solutions, already use one or more of the APIs mentioned or earlier JSRs like 275.