001/**
002 * Unit-API - Units of Measurement API for Java
003 * Copyright (c) 2014 Jean-Marie Dautelle, Werner Keil, V2COM
004 * All rights reserved.
005 *
006 * See LICENSE.txt for details.
007 */
008package javax.measure;
009
010import java.util.Map;
011
012/**
013 * Represents the dimension of a unit.
014 *
015 * <p>Concrete dimensions are obtained through the {@link Unit#getDimension()} method.</p>
016 *
017 * <p>Two units {@code u1} and {@code u2} are {@linkplain Unit#isCompatible(Unit) compatible}
018 * if and only if {@code u1.getDimension().equals(u2.getDimension())}.</p>
019 *
020 * @author <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
021 * @author <a href="mailto:[email protected]">Werner Keil</a>
022 * @version 0.13, December 6, 2014
023 *
024 * @see <a href="http://en.wikipedia.org/wiki/Dimensional_analysis">Wikipedia: Dimensional Analysis</a>
025 */
026public interface Dimension {
027    /**
028     * Returns the product of this dimension with the one specified.
029     *
030     * @param  multiplicand the dimension multiplicand.
031     * @return {@code this * multiplicand}
032     */
033    Dimension multiply(Dimension multiplicand);
034
035    /**
036     * Returns the quotient of this dimension with the one specified.
037     *
038     * @param  divisor the dimension divisor.
039     * @return {@code this / divisor}
040     */
041    Dimension divide(Dimension divisor);
042
043    /**
044     * Returns this dimension raised to an exponent.
045     * <tt>(this<sup>n</sup>)</tt>
046     *
047     * @param  n power to raise this {@code Dimension} to.
048     * @return <tt>this<sup>n</sup></tt>
049     */
050    Dimension pow(int n);
051
052    /**
053     * Returns the given root of this dimension.
054     *
055     * @param  n the root's order.
056     * @return the result of taking the given root of this dimension.
057     * @throws ArithmeticException if {@code n == 0}.
058     */
059    Dimension root(int n);
060
061    /**
062     * Returns the fundamental dimensions and their exponent whose product is
063     * this dimension, or {@code null} if this dimension is a fundamental dimension.
064     *
065     * @return the mapping between the fundamental dimensions and their exponent.
066     */
067    Map<? extends Dimension, Integer> getProductDimensions();
068}