JSRs: Java Specification Requests
JSR 363: Units of Measurement API
JCP version in use: 2.9
Java Specification Participation Agreement version in use: 2.0
This JSR specifies Java packages for modeling and working with measurement values, quantities and their corresponding units.
Expert Group Transparency:
Public Project Page
The following changes have been made to the original proposal.
2016.02.16: All references to "unitsofmeasurement.org" have been replaced with "unitsofmeasurement.github.io."
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, and a BSD 3-Clause License for the RI and TCK.
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. We target stand-alone releases.
The minimum Java version for ME will be CLDC 8, making it compatible with Java SE 7 (Embedded).
Section 1. Identification
Submitting Member: Werner Keil
E-Mail Address: werner.keil
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
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:
Supporting this JSR:
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:
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.)
2.8 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?
2.9 Are there any security issues that cannot be addressed by the current security model?
2.10 Are there any internationalization or localization issues?
There are some internationalization issues that this JSR will address:
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 email@example.com for EG Members and similar active contributors and firstname.lastname@example.org 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:
These projects are already publicly visible and accessible. In addition, the following communications already exist or will be established:
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.
(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.
Note that this section has been updated from this original proposal.
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 email@example.com for EG Members and similar active contributors and firstname.lastname@example.org 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 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.
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.