001/*
002 * Units of Measurement API
003 * Copyright (c) 2014-2023, Jean-Marie Dautelle, Werner Keil, Otavio Santana.
004 *
005 * All rights reserved.
006 *
007 * Redistribution and use in source and binary forms, with or without modification,
008 * are permitted provided that the following conditions are met:
009 *
010 * 1. Redistributions of source code must retain the above copyright notice,
011 *    this list of conditions and the following disclaimer.
012 *
013 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions
014 *    and the following disclaimer in the documentation and/or other materials provided with the distribution.
015 *
016 * 3. Neither the name of JSR-385 nor the names of its contributors may be used to endorse or promote products
017 *    derived from this software without specific prior written permission.
018 *
019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
021 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
022 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
023 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
024 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
025 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
026 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
027 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
028 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 */
030package javax.measure.spi;
031
032import java.util.Set;
033
034import javax.measure.Dimension;
035import javax.measure.Quantity;
036import javax.measure.Unit;
037
038/**
039 * A system of units grouped together for historical or cultural reasons.<br>
040 * Common system of units are "SI" (System International), "Imperial" (British), "US" (US Customary). Nothing prevents a unit from belonging to
041 * several systems of units at the same time (for example an {@code Imperial} system would have many of the units held by the {@code US} Customary
042 * system).
043 *
044 * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
045 * @author <a href="mailto:werner@uom.technology">Werner Keil</a>
046 * @version 1.1, June 21, 2018
047 * @since 1.0
048 *
049 * @see <a href="http://en.wikipedia.org/wiki/International_System_of_Units"> Wikipedia: International System of Units</a>
050 * @see <a href="http://en.wikipedia.org/wiki/Systems_of_measurement"> Wikipedia: System of measurement</a>
051 */
052public interface SystemOfUnits {
053
054    /**
055     * @return a name
056     */
057    String getName();
058
059    /**
060     * Returns the default unit for the specified quantity or {@code null} if none is defined for the given quantity in this unit system.
061     *
062     * @param <Q>
063     *          the compile-time quantity type.
064     * @param quantityType
065     *          the quantity type.
066     * @return the unit for the specified quantity.
067     */
068    <Q extends Quantity<Q>> Unit<Q> getUnit(Class<Q> quantityType);
069
070    /**
071     * Returns a unit with the given {@linkplain String string} representation or {@code null} if none is found in this unit system.
072     *
073     * @param string
074     *          the string representation of a unit, not {@code null}.
075     * @return the unit with the given string representation.
076     * @since 2.0
077     */
078    Unit<?> getUnit(String string);
079
080    /**
081     * Returns a read only view over the units explicitly defined by this system. This include the base and derived units which are assigned a special
082     * name and symbol. This set does not include new units created by arithmetic or other operations.
083     *
084     * @return the defined collection of units.
085     */
086    Set<? extends Unit<?>> getUnits();
087
088    /**
089     * Returns the units defined in this system having the specified dimension (convenience method).
090     *
091     * @param dimension
092     *          the dimension of the units to be returned.
093     * @return the collection of units of specified dimension.
094     */
095    Set<? extends Unit<?>> getUnits(Dimension dimension);
096}