Find JSRs
Submit this Search

Ad Banner

JSRs: Java Specification Requests
JSR 275: Units Specification

This JSR has been Rejected
Reason: This JSR was not approved by the SE/EE Executive Committee in the Public Draft Reconsideration Ballot.

Updates to the Original JSR

The following has been updated from the original proposal.

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

We plan to release RI and TCK under a BSD-like license. It should be available for no-fee and without requirement for registration.


The Specification Lead was changed from CapTech Ventures to Werner Keil and Jean-Marie Dautelle.

Specification Lead: Jean-Mariie Dautelle, Werner Keil

E-Mail Address:,

Telephone Number: +33 6 45 45 40 63, +44 0 20 7240 3621

Fax Number: +33 1 69 75 58 85, +44 0 20 7379 7573

Original Java Specification Request (JSR)

Identification | Request | Contributions

Section 1. Identification

Submitting Member: CapTech Ventures

Name of Contact Person: Steve Metsker

E-Mail Address:

Telephone Number: +1 804 852 3164

Fax Number: +1 804 355 4220

NOTE that this information has been updated from this original proposal.

Specification Lead: Steve Metsker, CapTech Ventures

E-Mail Address:

Telephone Number: +1 804 852 3164

Fax Number: +1 804 355 4220

Initial Expert Group Membership:

Agilent Technologies
Jean-Marie Dautelle
Martin Desruisseaux
Michael Grubsch

Supporting this JSR:

Steve Metsker
Bruce Hamilton, through Agilent Technologies
Jean-Marie Dautelle
Michael Grubsch
Martin Desruisseaux

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 with methods for unit operations:
o Checking of unit compatibility
o Expression of a quantity in various units
o Arithmetic operations on units
? 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 database of predefined units.

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


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 J2SE (desktop and server platforms), although personal or embedded systems might wish to use the packages. This JSR should have few dependencies outside the java.lang, java.util, and java.text packages.

2.4 Should this JSR be voted on by both Executive Committees?

(The JCP has two Executive Committees (EC)-Standard/Enterprise & Micro Edition.) Our primary aim is to provide javax.units as part of J2SE, so it is probably most appropriate for the Standard/Enterprise committee to vote on this JSR.

2.5 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 weight 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.

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

There are no specifications for handling units in Java.

2.7 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, that 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?mass and length cannot be exchanged. Further, when we multiply physical measures the dimensions add up as exponents. For example, length times length becomes length2.
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.
Although errors based on confusion or miscommunication about units are common, the mathematics of units is not especially complex. When quantities are multiplied, the exponents of their dimensions are added. For example, acceleration has a dimension of length?time-2. We can multiply a mass by an acceleration to derive a quantity in the dimension mass?length?time-2. The common name for this dimension is 'force'. Quantities with the same dimension can be added and subtracted. For example, we can subtract a cup from a liter and express the result as a number of milliliters or as a number of cubic inches.
A Java package that supports modeling units should allow developers to easily and correctly perform mathematical operations on units. The package should allow developers to specify the dimension (such as volume) of a passed parameter, rather than insisting on any particular unit (such as milliliters). Finally, the package should help with representing physical quantities as strings, with support for parsing and formatting. The existence of such a package will help Java developers to create safe, correct software to deal with common problem of modeling measurements of the physical world.

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

This JSR will propose the creation of one or more javax packages. The names of those packages will depend on the consensus of the expert group on two questions.
The first question is whether we should separate 'units' from 'quantities'. This would separate, for example, the model of a 'meter' from the model of 'length'. With that type of separation, the results of this group would be javax.units and javax. quantities.
The second question is whether this JSR should leave room for other scientific models. For example, a forward-thinking name for the units package might be: javax.physics.units.
Part of the work of the expert group is to arrive at a good decision of what package name or names to propose.

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


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


2.11 Are there any internationalization or localization issues?

There are several internationalization issues that this JSR will address:
? Which systems of units should be supported? The RI will certainly support the SI system; The British Imperial System and U.S. Customary Units may also merit support, and there may be other systems that should be supported. For example, the Swedish linje and Spanish linea are still in use in some parts of the world - should these units be supported?
? Some units have locale-dependent spellings, such as 'liter' and 'litre'.
? Some names have different meanings in different unit systems. For example, an Imperial gallon is larger than a US gallon. There are two Unicode-related issues that this JSR will address:
? Should the reference implementation of javax.units have any restrictions on the Unicode characters used in the source? For example, symbols for pi and infinity may, by the rules of Java, appear in variable names. However, not all text editors and development environments will recognize all characters.
? Should the reference code have limitations on the characters it outputs? For example, should the code output a superscript 3 to indicate 'cubed'?

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

No. This JSR is a replacement for JSR-108, which was withdrawn before completion. The previous JSR was withdrawn because the former lead submitter's company left the JCP. This new JSR proposal addresses the same needs as JSR-108. Most of the members of JSR-108 have kept in communication since JSR-108 was withdrawn, and will form the membership of this new JSR.

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

June 2005 Public CVS or SVN server running with JScience units package as a starting point.
December 2005 A PDF document with definitions of key concepts (dimensions, quantities, scale types, units, base units, derivative units, supplementary units, etc.). The code on CVS or SVN may be used for illustrative purpose. We allow many months for this very important step because JSR-108 experience show that no progress is possible without an agreement on a common basis of well understood definition of terms.
September 2006 Reference implementation and test suite.

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

The primary means of communication for the Expert Group will be the mailing list, facilitated by side emails and conversations. The prospective members of the Expert Group use this list now, and have for some time.

2.15 It is important to the success of the community and each JSR that the work of the Expert Group be handled in a manner which provides the community and the public with insight into the work the Expert Group is doing, and the decisions that the Expert Group has made. The Executive Committees would like to ensure Spec Leads understand the value of this transparency and ask that each JSR have an operating plan in place for how their JSR will address the involvement of the community and the public. Please provide your plan here, and refer to the Spec Lead Guide for a more detailed description and a set of example questions you may wish to answer in your plan.

Our plan is to incubate a units package as an open source development project. While the Expert Group will retain control over the exact contents of the Reference Implementation, our expectation is the open source project will become the RI.

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

We target stand-alone releases.

2.17 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.18 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 information has been updated from this original proposal.

We plan to release RI and TCK under a BSD-like license. It should be available for no-fee and without requirement for registration.

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.

? The brochure on the International System of Units from the Bureau International des Poids et Mesures
? The International System of Units (SI) web page at the US National Institute of Standards and Technology (NIST)
? The units subsytem of the VisAD package
? The legacy JSR-108 project
? The JScience project
? ISO 31-0 (Quantities and units)

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

The "Guide for the Use of the International System of Units (SI)" from the US National Institute of Standards and Technology was used as a starting point for both the above-mentioned units subsystem of the VisAD package and the ucar.units package from the University Corporation for Atmospheric Research. The JScience and JSR-108 projects are derived work. It is hoped that the JSR process might primarily consist of turning those derived work into the reference implementation -- by modifying both its abstract API and its implementation.