KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > measure > converters > UnitConverter


1 /*
2  * JScience - Java(TM) Tools and Libraries for the Advancement of Sciences.
3  * Copyright (C) 2006 - JScience (http://jscience.org/)
4  * All rights reserved.
5  *
6  * Permission to use, copy, modify, and distribute this software is
7  * freely granted, provided that this notice is preserved.
8  */
9 package javax.measure.converters;
10
11 import java.io.Serializable JavaDoc;
12
13 /**
14  * <p> This class represents a converter of numeric values.</p>
15  *
16  * <p> It is not required for sub-classes to be immutable
17  * (e.g. currency converter).</p>
18  *
19  * <p> Sub-classes must ensure unicity of the {@link #IDENTITY identity}
20  * converter. In other words, if the result of an operation is equivalent
21  * to the identity converter, then the unique {@link #IDENTITY} instance
22  * should be returned.</p>
23  *
24  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
25  * @version 3.1, April 22, 2006
26  */
27 public abstract class UnitConverter implements Serializable JavaDoc {
28
29     /**
30      * Holds the identity converter (unique). This converter does nothing
31      * (<code>IDENTITY.convert(x) == x</code>).
32      */
33     public static final UnitConverter IDENTITY = new Identity();
34
35     /**
36      * Default constructor.
37      */
38     protected UnitConverter() {
39     }
40
41     /**
42      * Returns the inverse of this converter. If <code>x</code> is a valid
43      * value, then <code>x == inverse().convert(convert(x))</code> to within
44      * the accuracy of computer arithmetic.
45      *
46      * @return the inverse of this converter.
47      */
48     public abstract UnitConverter inverse();
49
50     /**
51      * Converts a double value.
52      *
53      * @param x the numeric value to convert.
54      * @return the converted numeric value.
55      * @throws ConversionException if an error occurs during conversion.
56      */
57     public abstract double convert(double x) throws ConversionException;
58
59     /**
60      * Indicates if this converter is linear. A converter is linear if
61      * <code>convert(u + v) == convert(u) + convert(v)</code> and
62      * <code>convert(r * u) == r * convert(u)</code>.
63      * For linear converters the following property always hold:[code]
64      * y1 = c1.convert(x1);
65      * y2 = c2.convert(x2);
66      * then y1*y2 = c1.concatenate(c2).convert(x1*x2)[/code]
67      *
68      * @return <code>true</code> if this converter is linear;
69      * <code>false</code> otherwise.
70      */
71     public abstract boolean isLinear();
72
73     /**
74      * Indicates whether this converter is considered the same as the
75      * converter specified (they must be of same types).
76      *
77      * @param cvtr the converter with which to compare.
78      * @return <code>true</code> if the specified object is a converter
79      * considered equals to this converter;<code>false</code> otherwise.
80      */
81     public abstract boolean equals(Object JavaDoc cvtr);
82
83     /**
84      * Returns a hash code value for this converter. Equals object have equal
85      * hash codes.
86      *
87      * @return this converter hash code value.
88      * @see #equals
89      */
90     public abstract int hashCode();
91
92     /**
93      * Concatenates this converter with another converter. The resulting
94      * converter is equivalent to first converting by the specified converter,
95      * and then converting by this converter.
96      *
97      * <p>Note: Implementations must ensure that the {@link #IDENTITY} instance
98      * is returned if the resulting converter is an identity
99      * converter.</p>
100      *
101      * @param converter the other converter.
102      * @return the concatenation of this converter with the other converter.
103      */
104     public UnitConverter concatenate(UnitConverter converter) {
105         return (converter == IDENTITY) ? this : new Compound(converter, this);
106     }
107
108     /**
109      * This inner class represents the identity converter (singleton).
110      */
111     private static final class Identity extends UnitConverter {
112
113         @Override JavaDoc
114         public UnitConverter inverse() {
115             return this;
116         }
117
118         @Override JavaDoc
119         public double convert(double x) {
120             return x;
121         }
122
123         @Override JavaDoc
124         public boolean isLinear() {
125             return true;
126         }
127
128         @Override JavaDoc
129         public UnitConverter concatenate(UnitConverter converter) {
130             return converter;
131         }
132
133         @Override JavaDoc
134         public boolean equals(Object JavaDoc obj) {
135             return this == obj;
136         }
137
138         @Override JavaDoc
139         public int hashCode() {
140             return 0;
141         }
142
143         private static final long serialVersionUID = 1L;
144
145     }
146
147     /**
148      * This inner class represents a compound converter.
149      */
150     private static final class Compound extends UnitConverter {
151
152         /**
153          * Holds the first converter.
154          */
155         private final UnitConverter _first;
156
157         /**
158          * Holds the second converter.
159          */
160         private final UnitConverter _second;
161
162         /**
163          * Creates a compound converter resulting from the combined
164          * transformation of the specified converters.
165          *
166          * @param first the first converter.
167          * @param second the second converter.
168          */
169         private Compound(UnitConverter first, UnitConverter second) {
170             _first = first;
171             _second = second;
172         }
173
174         @Override JavaDoc
175         public UnitConverter inverse() {
176             return new Compound(_second.inverse(), _first.inverse());
177         }
178
179         @Override JavaDoc
180         public double convert(double x) {
181             return _second.convert(_first.convert(x));
182         }
183
184         @Override JavaDoc
185         public boolean isLinear() {
186             return _first.isLinear() && _second.isLinear();
187         }
188
189         @Override JavaDoc
190         public boolean equals(Object JavaDoc cvtr) {
191             return (cvtr instanceof Compound)
192                     && _first.equals(((Compound) cvtr)._first)
193                     && _second.equals(((Compound) cvtr)._second);
194         }
195
196         @Override JavaDoc
197         public int hashCode() {
198             return _first.hashCode() + _second.hashCode();
199         }
200
201         private static final long serialVersionUID = 1L;
202
203     }
204 }
Popular Tags