Package org.apache.sis.measure

# Class UnitServices

Object
ServiceProvider
UnitServices

All Implemented Interfaces:
  `SystemOfUnitsService`, `UnitFormatService`

public class UnitServices extends ServiceProvider implements SystemOfUnitsService, UnitFormatService
The central point from which all unit services (parsing, formatting, listing, etc) can be obtained. Apache SIS does not use this class (SIS rather uses `Units` pre-defined constants and `UnitFormat` directly since they are designed specifically for SIS needs). This class is provided for allowing other applications to discover Apache SIS implementation of JSR-363 without direct dependency. A `UnitServices` instance can be obtained by call to `ServiceProvider​.current()`.

Since:
  0.8

Defined in the `sis-utility` module

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UnitServices()`
  Creates a new service provider.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Set<String>`
  `getAvailableFormatNames()`
  Returns a list of available format names.
  `Collection<SystemOfUnits>`
  `getAvailableSystemsOfUnits()`
  Returns the list of all available systems of units.
  `<Q extends Quantity<Q>>
  QuantityFactory<Q>`
  `getQuantityFactory(Class<Q> type)`
  Return a factory for the given `Quantity` type.
  `SystemOfUnits`
  `getSystemOfUnits()`
  Returns the default system of units used by Apache SIS.
  `SystemOfUnits`
  `getSystemOfUnits(String name)`
  Returns the system of units having the specified name, or `null` if none.
  `SystemOfUnitsService`
  `getSystemOfUnitsService()`
  Returns the service to obtain a `SystemOfUnits` instances.
  `UnitFormat`
  `getUnitFormat()`
  Returns an unit format instance for human-readable unit symbols in the default locale.
  `UnitFormat`
  `getUnitFormat(String name)`
  Returns the unit format for the given name.
  `UnitFormatService`
  `getUnitFormatService()`
  Returns the service to obtain a `UnitFormat` instances.

  ### Methods inherited from class ServiceProvider

  `available, current, getPriority, setCurrent`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### UnitServices

    public UnitServices()
    Creates a new service provider. `UnitServices` should not be instantiated directly unless the caller wants specifically the Apache SIS implementation. For obtaining the default implementation, use `ServiceProvider​.current()` instead.

- ## Method Details

  - ### getSystemOfUnits

    public SystemOfUnits getSystemOfUnits()
    Returns the default system of units used by Apache SIS. This include the International System of Units (SI) together with some imperial units and other units. This system includes at least all the constants defined in the `Units` class.
    Specified by:
      `getSystemOfUnits` in interface `SystemOfUnitsService`
    Returns:
      the system of units used by Apache SIS.

  - ### getSystemOfUnits

    public SystemOfUnits getSystemOfUnits(String name)
    Returns the system of units having the specified name, or `null` if none. The argument can be any name in the following table:

    Available system of units
    Name | Examples
    --- | ---
    SI | m, km, m³, s, m∕s, K, °C, hPa, rad, µrad
    SI + accepted | s, min, h, m∕s, km∕h, °, ′, ″, ha
    Imperial | in, ft, mi (statute mile)
    SI + other | m, m∕s, km∕h, ft, mi, M (nautical mile)

    The search for name is case-insensitive and ignore whitespaces.
    Specified by:
      `getSystemOfUnits` in interface `SystemOfUnitsService`
    Parameters:
      `name` - the name of the desired system of units.
    Returns:
      the system of units for the given name, or `null` if none.

  - ### getAvailableSystemsOfUnits

    public Collection<SystemOfUnits> getAvailableSystemsOfUnits()
    Returns the list of all available systems of units.
    Specified by:
      `getAvailableSystemsOfUnits` in interface `SystemOfUnitsService`
    Returns:
      list of available systems of units.

  - ### getSystemOfUnitsService

    public SystemOfUnitsService getSystemOfUnitsService()
    Returns the service to obtain a `SystemOfUnits` instances. The default implementation returns `this` since this `UnitServices` class implements directly all relevant interfaces. The methods related to system of units are:
    - `getSystemOfUnits()`
    - `getSystemOfUnits(String)`
    - `getAvailableSystemsOfUnits()`
    Specified by:
      `getSystemOfUnitsService` in class `ServiceProvider`
    Returns:
      the service to obtain a `SystemOfUnits`, or `null` if none.

  - ### getUnitFormat

    public UnitFormat getUnitFormat()
    Returns an unit format instance for human-readable unit symbols in the default locale. The format style is `UnitFormat​.Style​.SYMBOL`. This style requires support for Unicode characters; for example square metres are formatted as “m²”, not “m2”.
    Specified by:
      `getUnitFormat` in interface `UnitFormatService`
    Returns:
      a `UnitFormat` instance for unit symbols.

  - ### getUnitFormat

    public UnitFormat getUnitFormat(String name)
    Returns the unit format for the given name. The argument can be the name of any value in the `UnitFormat​.Style` enumeration. The argument can be any name in the following table:

    Available unit format name
    Name | Examples
    --- | ---
    SYMBOL | km, m³, m∕s, N⋅m, K, °C, hPa, rad, µrad
    UCUM | km, m3, m/s, N.m
    NAME | kilometre, cubic metre, metres per second

    The `"NAME"` format is locale-sensitive. The format locale can be modified by a call to `UnitFormat​.setLocale(Locale)` on the returned object.
    Specified by:
      `getUnitFormat` in interface `UnitFormatService`
    Parameters:
      `name` - the name of the desired format.
    Returns:
      the corresponding unit format, or `null` if none.

  - ### getAvailableFormatNames

    public Set<String> getAvailableFormatNames()
    Returns a list of available format names. The default implementation returns the names of all values in the `UnitFormat​.Style` enumeration.
    Specified by:
      `getAvailableFormatNames` in interface `UnitFormatService`
    Returns:
      list of available formats.

  - ### getUnitFormatService

    public UnitFormatService getUnitFormatService()
    Returns the service to obtain a `UnitFormat` instances. The default implementation returns `this` since this `UnitServices` class implements directly all relevant interfaces. The methods related to unit formats are:
    - `getUnitFormat()`
    - `getUnitFormat(String)`
    - `getAvailableFormatNames()`
    Specified by:
      `getUnitFormatService` in class `ServiceProvider`
    Returns:
      the service to obtain a `UnitFormat`, or `null` if none.

  - ### getQuantityFactory

    public <Q extends Quantity<Q>> QuantityFactory<Q> getQuantityFactory(Class<Q> type)
    Return a factory for the given `Quantity` type. In the particular case of Apache SIS implementation, `Quantities​.create(double, Unit)` provides a more direct way to instantiate quantities.
    Specified by:
      `getQuantityFactory` in class `ServiceProvider`
    Type Parameters:
      `Q` - compile-time value of the `type` argument.
    Parameters:
      `type` - type of the desired the quantity.
    Returns:
      the service to obtain `Quantity` instances.
    See Also:
      - `Quantities​.create(double, Unit)`