001/*
002 * Units of Measurement API
003 * Copyright (c) 2014-2016, Jean-Marie Dautelle, Werner Keil, V2COM.
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-363 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;
031
032import java.util.Map;
033
034/**
035 * Represents the dimension of a unit.
036 *
037 * <p>
038 * Concrete dimensions are obtained through the {@link Unit#getDimension()} method.
039 * </p>
040 *
041 * <p>
042 * Two units {@code u1} and {@code u2} are {@linkplain Unit#isCompatible(Unit) compatible} if and only if
043 * {@code u1.getDimension().equals(u2.getDimension())}.
044 * </p>
045 *
046 * @author <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
047 * @author <a href="mailto:[email protected]">Werner Keil</a>
048 * @version 1.0, August 8, 2016
049 * @since 1.0
050 * @see Unit
051 * @see <a href="http://en.wikipedia.org/wiki/Dimensional_analysis">Wikipedia: Dimensional Analysis</a>
052 */
053public interface Dimension {
054  /**
055   * Returns the product of this dimension with the one specified.
056   *
057   * @param multiplicand
058   *          the dimension multiplicand.
059   * @return {@code this * multiplicand}
060   */
061  Dimension multiply(Dimension multiplicand);
062
063  /**
064   * Returns the quotient of this dimension with the one specified.
065   *
066   * @param divisor
067   *          the dimension divisor.
068   * @return {@code this / divisor}
069   */
070  Dimension divide(Dimension divisor);
071
072  /**
073   * Returns this dimension raised to an exponent. <tt>(this<sup>n</sup>)</tt>
074   *
075   * @param n
076   *          power to raise this {@code Dimension} to.
077   * @return <tt>this<sup>n</sup></tt>
078   */
079  Dimension pow(int n);
080
081  /**
082   * Returns the given root of this dimension.
083   *
084   * @param n
085   *          the root's order.
086   * @return the result of taking the given root of this dimension.
087   * @throws ArithmeticException
088   *           if {@code n == 0}.
089   */
090  Dimension root(int n);
091
092  /**
093   * Returns the (fundamental) base dimensions and their exponent whose product is this dimension, or {@code null} if this dimension is a base
094   * dimension.
095   *
096   * @return the mapping between the fundamental dimensions and their exponent.
097   */
098  Map<? extends Dimension, Integer> getBaseDimensions();
099}