Module org.apache.sis.util
Package org.apache.sis.measure

# Class UnitServices

Object
ServiceProvider
UnitServices

All Implemented Interfaces:
  `FormatService`, `SystemOfUnitsService`

public class UnitServices extends ServiceProvider implements SystemOfUnitsService, FormatService
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` predefined 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-385 without direct dependency. A `UnitServices` instance can be obtained by call to `ServiceProvider​.current()`.

Since:
  0.8

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface FormatService

  `FormatService​.FormatType`

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Set<String>`
  `getAvailableFormatNames(FormatService​.FormatType type)`
  Returns a list of available format names.
  `Collection<SystemOfUnits>`
  `getAvailableSystemsOfUnits()`
  Returns the list of all available systems of units.
  `FormatService`
  `getFormatService()`
  Returns the service to obtain a `UnitFormat` instances.
  `<Q extends Quantity<Q>>
  QuantityFactory<Q>`
  `getQuantityFactory(Class<Q> type)`
  Return a factory for the given `Quantity` type.
  `QuantityFormat`
  `getQuantityFormat()`
  Returns a quantity format for the default locale.
  `QuantityFormat`
  `getQuantityFormat(String name)`
  Returns the quantity format having the specified name or `null` if none.
  `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.
  `UnitFormat`
  `getUnitFormat(String name, String variant)`
  Returns the unit format having the specified name or `null` if none.

  ### Methods inherited from class ServiceProvider

  `available, current, getPriority, of, setCurrent`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface SystemOfUnitsService

  `getPrefixes`

- ## 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 `FormatService`
    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 `FormatService`
    Parameters:
      `name` - the name of the desired format.
    Returns:
      the corresponding unit format, or `null` if none.

  - ### getUnitFormat

    public UnitFormat getUnitFormat(String name, String variant)
    Returns the unit format having the specified name or `null` if none. The variant is an optional argument for requesting e.g. ASCII-only format, or for choosing case-sensitive versus case-insensitive variants. In current implementation the variant argument is ignored.
    Specified by:
      `getUnitFormat` in interface `FormatService`
    Parameters:
      `name` - the name of the desired format.
      `variant` - indicates a variation of a unit format.
    Returns:
      the corresponding unit format, or `null` if none.
    Since:
      1.4

  - ### getQuantityFormat

    public QuantityFormat getQuantityFormat()
    Returns a quantity format for the default locale.
    Specified by:
      `getQuantityFormat` in interface `FormatService`
    Returns:
      a `QuantityFormat` instance for quantities.
    Since:
      1.4

  - ### getQuantityFormat

    public QuantityFormat getQuantityFormat(String name)
    Returns the quantity format having the specified name or `null` if none. The names accepted by this method are those documented in `getUnitFormat(String)`.
    Specified by:
      `getQuantityFormat` in interface `FormatService`
    Parameters:
      `name` - the name of the format.
    Returns:
      the corresponding quantity format, or `null` if none.
    Since:
      1.4

  - ### getAvailableFormatNames

    public Set<String> getAvailableFormatNames(FormatService.FormatType type)
    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 `FormatService`
    Parameters:
      `type` - the type of formats (for units or for quantities).
    Returns:
      list of available formats.

  - ### getFormatService

    public FormatService getFormatService()
    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(FormatType)`
    Specified by:
      `getFormatService` 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)`