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; 035import javax.measure.UnitConverter; 036 037import tech.units.indriya.AbstractUnit; 038 039import java.util.Map; 040import java.util.Objects; 041 042/** 043 * <p> 044 * This class represents units used in expressions to distinguish between quantities of a different nature but of the same dimensions. 045 * </p> 046 * 047 * <p> 048 * Examples of alternate units: 049 * </p> 050 * 051 * <code> 052 * {@literal Unit<Angle>} RADIAN = AlternateUnit.of(ONE, "rad").asType(Angle.class);<br> 053 * {@literal Unit<Force>} NEWTON = AlternateUnit.of(METRE.multiply(KILOGRAM).divide(SECOND.pow(2)), "N").asType(Force.class);<br> 054 * {@literal Unit<Pressure>} PASCAL = AlternateUnit.of(NEWTON.divide(METRE.pow(2), "Pa").asType(Pressure.class);<br> 055 * </code> 056 * 057 * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a> 058 * @author <a href="mailto:werner@units.tech">Werner Keil</a> 059 * @version 1.5, March 23, 2019 060 * @since 1.0 061 */ 062public final class AlternateUnit<Q extends Quantity<Q>> extends AbstractUnit<Q> { 063 064 /** 065 * 066 */ 067 private static final long serialVersionUID = 4696690756456282705L; 068 069 /** 070 * Holds the parent unit (a system unit). 071 */ 072 private final Unit<?> parentUnit; 073 074 /** 075 * Creates an alternate unit for the specified system unit identified by the specified name and symbol. 076 * 077 * @param parentUnit 078 * the system unit from which this alternate unit is derived. 079 * @param symbol 080 * the symbol for this alternate unit. 081 * @throws IllegalArgumentException 082 * if the specified parent unit is not an {@link AbstractUnit#isSystemUnit() system unit} 083 */ 084 @SuppressWarnings("rawtypes") 085 public AlternateUnit(Unit<?> parentUnit, String symbol) { 086 super(symbol); 087 if (!(parentUnit instanceof AbstractUnit)) 088 throw new IllegalArgumentException("The parent unit: " + parentUnit + " is not an AbstractUnit"); 089 if (!((AbstractUnit) parentUnit).isSystemUnit()) 090 throw new IllegalArgumentException("The parent unit: " + parentUnit + " is not an unscaled SI unit"); 091 this.parentUnit = parentUnit instanceof AlternateUnit ? ((AlternateUnit) parentUnit).getParentUnit() : parentUnit; 092 } 093 094 /** 095 * Returns the parent unit of this alternate unit, always a system unit and never an alternate unit. 096 * 097 * @return the parent unit. 098 */ 099 public Unit<?> getParentUnit() { 100 return parentUnit; 101 } 102 103 @Override 104 public Dimension getDimension() { 105 return parentUnit.getDimension(); 106 } 107 108 @SuppressWarnings("rawtypes") 109 @Override 110 public UnitConverter getSystemConverter() { 111 return ((AbstractUnit) parentUnit).getSystemConverter(); 112 } 113 114 @Override 115 public Unit<Q> toSystemUnit() { 116 return this; // Alternate units are SI units. 117 } 118 119 @Override 120 public Map<? extends Unit<?>, Integer> getBaseUnits() { 121 return parentUnit.getBaseUnits(); 122 } 123 124 @Override 125 public int hashCode() { 126 return Objects.hash(parentUnit, getSymbol()); 127 } 128 129 @SuppressWarnings("rawtypes") 130 @Override 131 public boolean equals(Object obj) { 132 if (this == obj) { 133 return true; 134 } 135 if (obj instanceof AlternateUnit) { 136 AlternateUnit that = (AlternateUnit) obj; 137 return Objects.equals(parentUnit, that.parentUnit) && Objects.equals(getSymbol(), that.getSymbol()); 138 } 139 return false; 140 } 141 142 /** 143 * Creates an alternate unit for the specified system unit identified by the specified name and symbol. 144 * 145 * @param parent 146 * the system unit from which this alternate unit is derived. 147 * @param symbol 148 * the symbol for this alternate unit. 149 * @throws IllegalArgumentException 150 * if the specified parent unit is not an unscaled standard {@link AbstractUnit#isSystemUnit() system unit}. 151 * @throws MeasurementException 152 * if the specified symbol is not valid or is already associated to a different unit. 153 */ 154 public static <Q extends Quantity<Q>> AlternateUnit<Q> of(Unit<?> parent, String symbol) { 155 return new AlternateUnit<>(parent, symbol); 156 } 157}