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;
031
032import java.io.Serializable;
033
034import javax.measure.Quantity;
035import javax.measure.Unit;
036
037import tech.uom.lib.common.function.QuantityConverter;
038
039/**
040 * Quantity specialized for the Java SE platform. It extends {@link Quantity} with {@linkplain Comparable} and {@linkplain Serializable }
041 * 
042 * @see {@link Quantity}
043 * @author otaviojava
044 * @author werner
045 * @param <Q>
046 * @version 1.1, July 2, 2019
047 * @since 1.0
048 */
049public interface ComparableQuantity<Q extends Quantity<Q>> extends Quantity<Q>, Comparable<Quantity<Q>>, QuantityConverter<Q>, Serializable {
050
051  /**
052   * @see Quantity#add(Quantity)
053   */
054  ComparableQuantity<Q> add(Quantity<Q> that);
055
056  /**
057   * @see Quantity#subtract(Quantity)
058   */
059  ComparableQuantity<Q> subtract(Quantity<Q> that);
060
061  /**
062   * @see Quantity#divide(Quantity)
063   */
064  ComparableQuantity<?> divide(Quantity<?> that);
065
066  /**
067   * @see Quantity#divide(Number)
068   */
069  ComparableQuantity<Q> divide(Number that);
070
071  /**
072   * @see Quantity#multiply(Quantity)
073   */
074  ComparableQuantity<?> multiply(Quantity<?> multiplier);
075
076  /**
077   * @see Quantity#multiply(Number)
078   */
079  ComparableQuantity<Q> multiply(Number multiplier);
080
081  /**
082   * @see Quantity#inverse()
083   */
084  ComparableQuantity<?> inverse();
085
086  /**
087   * invert and already cast to defined quantityClass
088   * 
089   * @param quantityClass
090   *          Quantity to be converted
091   * @see Quantity#inverse()
092   * @see Quantity#asType(Class)
093   */
094  <T extends Quantity<T>> ComparableQuantity<T> inverse(Class<T> quantityClass);
095
096  /**
097   * @see Quantity#to(Unit)
098   */
099  ComparableQuantity<Q> to(Unit<Q> unit);
100
101  /**
102   * @see Quantity#asType(Class)
103   */
104  <T extends Quantity<T>> ComparableQuantity<T> asType(Class<T> type) throws ClassCastException;
105
106  /**
107   * Compares two instances of {@link Quantity <Q>}. Conversion of unit can happen if necessary
108   *
109   * @param that
110   *          the {@code quantity<Q>} to be compared with this instance.
111   * @return {@code true} if {@code that > this}.
112   * @throws NullPointerException
113   *           if the that is null
114   */
115  boolean isGreaterThan(Quantity<Q> that);
116
117  /**
118   * Compares two instances of {@link Quantity <Q>}, doing the conversion of unit if necessary.
119   *
120   * @param that
121   *          the {@code quantity<Q>} to be compared with this instance.
122   * @return {@code true} if {@code that >= this}.
123   * @throws NullPointerException
124   *           if the that is null
125   */
126  boolean isGreaterThanOrEqualTo(Quantity<Q> that);
127
128  /**
129   * Compares two instances of {@link Quantity <Q>}, doing the conversion of unit if necessary.
130   *
131   * @param that
132   *          the {@code quantity<Q>} to be compared with this instance.
133   * @return {@code true} if {@code that < this}.
134   * @throws NullPointerException
135   *           if the quantity is null
136   */
137  boolean isLessThan(Quantity<Q> that);
138
139  /**
140   * Compares two instances of {@link Quantity <Q>}, doing the conversion of unit if necessary.
141   *
142   * @param that
143   *          the {@code quantity<Q>} to be compared with this instance.
144   * @return {@code true} if {@code that < this}.
145   * @throws NullPointerException
146   *           if the quantity is null
147   */
148  boolean isLessThanOrEqualTo(Quantity<Q> that);
149
150  /**
151   * Compares two instances of {@code Quantity <Q>}, doing the conversion of unit if necessary.
152   *
153   * @param that
154   *          the {@code quantity<Q>} to be compared with this instance.
155   * @return {@code true} if {@code that < this}.
156   * @throws NullPointerException
157   *           if the quantity is null
158   *           
159   * @see <a href= "https://dictionary.cambridge.org/dictionary/english/equivalent">Cambridge Dictionary: equivalent</a>
160   * @see <a href= "https://www.lexico.com/en/definition/equivalent">LEXICO: equivalent</a>       
161   */
162  boolean isEquivalentTo(Quantity<Q> that);
163
164  /**
165   * Multiply and cast the {@link ComparableQuantity}
166   * 
167   * @param that
168   *          quantity to be multiplied
169   * @param asTypeQuantity
170   *          quantity to be converted
171   * @return the QuantityOperations multiplied and converted
172   * @see Quantity#divide(Quantity)
173   * @see Quantity#asType(Class)
174   * @exception NullPointerException
175   */
176  <T extends Quantity<T>, E extends Quantity<E>> ComparableQuantity<E> divide(Quantity<T> that, Class<E> asTypeQuantity);
177
178  /**
179   * Divide and cast the {@link ComparableQuantity}
180   * 
181   * @param that
182   *          quantity to be divided
183   * @param asTypeQuantity
184   *          quantity to be converted
185   * @return the QuantityOperations multiplied and converted
186   * @see QuantityOperations
187   * @see QuantityOperations#of(Quantity, Class)
188   * @see Quantity#asType(Class)
189   * @see Quantity#multiply(Quantity)
190   * @exception NullPointerException
191   */
192  <T extends Quantity<T>, E extends Quantity<E>> ComparableQuantity<E> multiply(Quantity<T> that, Class<E> asTypeQuantity);
193}