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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### 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 Detail

    - #### 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, or `null` if none.
      See Also:
        `Quantities​.create(double, Unit)`