Find JSRs
Submit this Search

Ad Banner

JSRs: Java Specification Requests
JSR 108: Units Specification

This JSR has been Withdrawn
Reason: Withdrawn after the Spec Lead left the JCP and none of the Expert Group took over as Spec Lead.

Original Java Specification Request (JSR)

Identification | Request | Contributions

Section 1. Identification

Submitting Member: University Corporation for Atmospheric Research

Name of Contact Person: Steven R. Emmerson

E-Mail Address:

Telephone Number: (303)497-8648

Fax Number: (303)497-8690

Specification Lead: Steven R. Emmerson

E-Mail Address:

Telephone Number: (303)497-8648

Fax Number: (303)497-8648

Initial Expert Group Membership:

  • Steven R. Emmerson, University Corporation for Atmospheric Research
  • Martin Desruisseaux, Institut de Recherche pour le D?loppement
  • Bill Hibbard, University of Wisconsin at Madison
  • Barry Taylor, National Institute of Standards and Technology
  • Bob Dragoset, National Institute of Standards and Technology

Section 2: Request

2.1 Please describe the proposed Specification:

This Specification defines a Java package for the programmatic, run-time handling of units of physical quantities. Included in the Specification are the following:

  • Abstract classes with methods for the following unit operations:
    • Checking of unit compatibility
    • Conversion of numeric values
    • Arithmetic operations on units (scaling, multiplication, etc.)
  • Concrete classes implementing the standard types of units (base, supplementary, derived, etc.) and unit conversions.
  • An abstract class for parsing unit specifications in string form and a concrete implementation for parsing unit specifications in standard form (e.g. furlongs/fortnight).
  • A database of pre-defined units.

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

The package is primarily targeted at desktop and server platforms. Personal or embedded systems might, however, wish to use the package.

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

Java developers who work with physical quantities (e.g. developers in the scientific, engineering, medical, and manufacturing domains) need to be able to handle units in their programs -- otherwise, they must assume that every numerical value is in a fixed, compile-time unit. This assumption is error-prone in large or cooperative software (recall the unit-tragedy that doomed the late Mars Polar Lander) and can be extremely problematical if the units cannot be determined at compile-time.

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

There are no specifications for handling units in Java.

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

The International System of Units (SI) defines the base quantities of length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. A unit may be defined by the exponents it uses for these quantities (the unit's dimension). For example, the SI unit watt is a unit for the physical quantity of power and has the dimension mass.length2.time-3. The exponents of the dimensional components may be stored in the internal representation of the unit. Two units are convertible if their dimensions are the same, i.e. if they have the same set of exponents for the base quantities in their internal representation. Additionally, the unit operations of multiplication, division, and exponentiation become simple arithmetic operations on the dimensional exponents.

If the International System of Units (SI) is used as the foundation for representing units, then unit conversions are simplified. For example, horsepower is also a unit for the physical quantity of power and is approximately equal to 745.6999 watt. This scaling factor may be stored in the internal representation of the horsepower unit. The compatibility of horsepower and watt can be determined from their dimensional exponents and the conversion procedure can be determined from the scaling factor.

Parsing a unit specification in string form (e.g. consists of recognizing the individual tokens, obtaining their internal representations from a database, and performing the unit arithmetic specified in the string (multiplication in this case).

Given the above and the java.util package, A unit database may easily be constructed.

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


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


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


2.9 Are there any internationalization or localization issues?

The following are locale issues for units:

  • Formatting of certain units into locale-dependent spellings (e.g. liter vs. litre).
  • Interpretation of locale-dependent unit specifications. For example, an Imperial gallon is larger than a US gallon.

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


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

2001-03 Expert Group Formed
2001-12 First Public Review

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.

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 later package is a stand-alone package for the programatic handling of units that implements all the features listed in section 2.1 of this JSR. It is hoped that the JSR process might primarilly consist of turning the ucar.units package into the reference implementation -- by modifying both its abstract API and its implementation.