001/*
002 * Units of Measurement Reference Implementation
003 * Copyright (c) 2005-2020, Units of Measurement project.
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, Indriya nor the names of their 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 tech.units.indriya.unit;
031
032import javax.measure.Dimension;
033import javax.measure.Quantity;
034import javax.measure.Unit;
035
036import tech.units.indriya.AbstractUnit;
037import tech.units.indriya.unit.BaseUnit;
038import tech.units.indriya.unit.ProductUnit;
039import tech.units.indriya.unit.Units;
040
041import java.io.Serializable;
042import java.util.HashMap;
043import java.util.Map;
044import java.util.Objects;
045import java.util.logging.Level;
046import java.util.logging.Logger;
047
048/**
049 * <p>
050 * This class represents a dimension of a unit of measurement.
051 * </p>
052 *
053 * <p>
054 * The dimension associated to any given quantity are given by the published
055 * {@link Dimension} instances. For convenience, a static method
056 * <code>UnitDimension.of(Class)</code> aggregating the results of all
057 * 
058 * {@link Dimension} instances is provided.<br>
059 * <br>
060 * <code>
061 *        Dimension speedDimension
062 *            = UnitDimension.of(Speed.class);
063 *     </code>
064 * </p>
065 *
066 * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
067 * @author <a href="mailto:werner@units.tech">Werner Keil</a>
068 * @author  Martin Desruisseaux (Geomatys)
069 * @version 1.0, $Date: 2019-07-05 $
070 * @since 2.0
071 */
072public class UnitDimension implements Dimension, Serializable {
073        /**
074        * 
075        */
076        private static final long serialVersionUID = 7806787530512644696L;
077
078        private static final Logger LOGGER = Logger.getLogger(UnitDimension.class.getName());
079
080        /**
081         * Holds dimensionless.
082         * 
083         * @since 1.0
084         */
085        public static final Dimension NONE = new UnitDimension(AbstractUnit.ONE);
086
087        /**
088         * Holds length dimension (L).
089         * 
090         * @since 1.0
091         */
092        public static final Dimension LENGTH = new UnitDimension('L');
093
094        /**
095         * Holds mass dimension (M).
096         * 
097         * @since 1.0
098         */
099        public static final Dimension MASS = new UnitDimension('M');
100
101        /**
102         * Holds time dimension (T).
103         * 
104         * @since 1.0
105         */
106        public static final Dimension TIME = new UnitDimension('T');
107
108        /**
109         * Holds electric current dimension (I).
110         * 
111         * @since 1.0
112         */
113        public static final Dimension ELECTRIC_CURRENT = new UnitDimension('I');
114
115        /**
116         * Holds temperature dimension (Θ).
117         * 
118         * @since 1.0
119         */
120        public static final Dimension TEMPERATURE = new UnitDimension('\u0398');
121
122        /**
123         * Holds amount of substance dimension (N).
124         * 
125         * @since 1.0
126         */
127        public static final Dimension AMOUNT_OF_SUBSTANCE = new UnitDimension('N');
128
129        /**
130         * Holds luminous intensity dimension (J).
131         */
132        public static final Dimension LUMINOUS_INTENSITY = new UnitDimension('J');
133
134        /**
135         * Holds the pseudo unit associated to this dimension.
136         */
137        private final Unit<?> pseudoUnit;
138
139        /**
140         * Returns the dimension for the specified quantity type by aggregating the
141         * results of {@link DimensionService} or <code>null</code> if the specified
142         * quantity is unknown.
143         *
144         * @param quantityType the quantity type.
145         * @return the dimension for the quantity type or <code>null</code>.
146         * @since 1.1
147         */
148        public static <Q extends Quantity<Q>> Dimension of(Class<Q> quantityType) {
149                // TODO: Track services and aggregate results (register custom
150                // types)
151                Unit<Q> siUnit = Units.getInstance().getUnit(quantityType);
152                if (siUnit == null) {
153                        LOGGER.log(Level.FINER, "Quantity type: " + quantityType + " unknown");
154                        // we're logging but probably FINER is enough?
155                }
156                return (siUnit != null) ? siUnit.getDimension() : null;
157        }
158
159        /**
160         * Returns the dimension for the specified symbol.
161         *
162         * @param sambol the quantity symbol.
163         * @return the dimension for the given symbol.
164         * @since 1.0.1
165         */
166        public static Dimension parse(char symbol) {
167                return new UnitDimension(symbol);
168        }
169
170        /**
171         * Returns the unit dimension having the specified symbol.
172         *
173         * @param symbol the associated symbol.
174         */
175        @SuppressWarnings("rawtypes")
176        private UnitDimension(char symbol) {
177                pseudoUnit = new BaseUnit("[" + symbol + ']', NONE);
178        }
179
180        /**
181         * Constructor from pseudo-unit (not visible).
182         *
183         * @param pseudoUnit the pseudo-unit.
184         */
185        private UnitDimension(Unit<?> pseudoUnit) {
186                this.pseudoUnit = pseudoUnit;
187        }
188        
189        /**
190         * Default Constructor (not visible).
191         *
192         */
193        protected UnitDimension() {
194                this(AbstractUnit.ONE);
195        }
196        
197
198        /**
199         * Returns the product of this dimension with the one specified. If the
200         * specified dimension is not a physics dimension, then
201         * <code>that.multiply(this)</code> is returned.
202         *
203         * @param that the dimension multiplicand.
204         * @return <code>this * that</code>
205         * @since 1.0
206         */
207        public Dimension multiply(Dimension that) {
208                return that instanceof UnitDimension ? this.multiply((UnitDimension) that) : this.multiply(that);
209        }
210
211        /**
212         * Returns the product of this dimension with the one specified.
213         *
214         * @param that the dimension multiplicand.
215         * @return <code>this * that</code>
216         * @since 1.0
217         */
218        private UnitDimension multiply(UnitDimension that) {
219                return new UnitDimension(this.pseudoUnit.multiply(that.pseudoUnit));
220        }
221
222        /**
223         * Returns the quotient of this dimension with the one specified.
224         *
225         * @param that the dimension divisor.
226         * @return <code>this.multiply(that.pow(-1))</code>
227         * @since 1.0
228         */
229        public Dimension divide(Dimension that) {
230                return that instanceof UnitDimension ? this.divide((UnitDimension) that) : this.divide(that);
231        }
232
233        /**
234         * Returns the quotient of this dimension with the one specified.
235         *
236         * @param that the dimension divisor.
237         * @return <code>this.multiply(that.pow(-1))</code>
238         * @since 1.0
239         */
240        private UnitDimension divide(UnitDimension that) {
241                return new UnitDimension(ProductUnit.ofQuotient(pseudoUnit, that.pseudoUnit));
242        }
243
244        /**
245         * Returns this dimension raised to an exponent.
246         *
247         * @param n the exponent.
248         * @return the result of raising this dimension to the exponent.
249         * @since 1.0
250         */
251        public UnitDimension pow(int n) {
252                return new UnitDimension(this.pseudoUnit.pow(n));
253        }
254
255        /**
256         * Returns the given root of this dimension.
257         *
258         * @param n the root's order.
259         * @return the result of taking the given root of this dimension.
260         * @throws ArithmeticException if <code>n == 0</code>.
261         * @since 1.0
262         */
263        public UnitDimension root(int n) {
264                return new UnitDimension(this.pseudoUnit.root(n));
265        }
266
267        /**
268         * Returns the fundamental (base) dimensions and their exponent whose product is
269         * this dimension or <code>null</code> if this dimension is a fundamental
270         * dimension.
271         *
272         * @return the mapping between the base dimensions and their exponent.
273         * @since 1.0
274         */
275        @SuppressWarnings("rawtypes")
276        public Map<? extends Dimension, Integer> getBaseDimensions() {
277                Map<? extends Unit, Integer> pseudoUnits = pseudoUnit.getBaseUnits();
278                if (pseudoUnits == null) {
279                        return null;
280                }
281                final Map<UnitDimension, Integer> baseDimensions = new HashMap<>();
282                for (Map.Entry<? extends Unit, Integer> entry : pseudoUnits.entrySet()) {
283                        baseDimensions.put(new UnitDimension(entry.getKey()), entry.getValue());
284                }
285                return baseDimensions;
286        }
287
288        @Override
289        public String toString() {
290                return pseudoUnit.toString();
291        }
292
293        @Override
294        public boolean equals(Object obj) {
295                if (this == obj) {
296                        return true;
297                }
298                if (obj instanceof UnitDimension) {
299                        UnitDimension other = (UnitDimension) obj;
300                        return Objects.equals(pseudoUnit, other.pseudoUnit);
301                }
302                return false;
303        }
304
305        @Override
306        public int hashCode() {
307                return Objects.hashCode(pseudoUnit);
308        }
309}