View Javadoc

1   package org.apache.torque.om;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.math.BigDecimal;
20  
21  /***
22   * This class can be used as an ObjectKey to uniquely identify an
23   * object within an application where the id  consists
24   * of a single entity such a GUID or the value of a db row's primary key.
25   *
26   * @author <a href="mailto:jmcnally@apache.org">John McNally</a>
27   * @author <a href="mailto:stephenh@chase3000.com">Stephen Haberman</a>
28   * @author <a href="mailto:rg@onepercentsoftware.com">Runako Godfrey</a>
29   * @version $Id: NumberKey.java 239630 2005-08-24 12:25:32Z henning $
30   */
31  public class NumberKey extends SimpleKey
32  {
33      /***
34       * Creates a NumberKey whose internal representation will be
35       * set later, through a set method
36       */
37      public NumberKey()
38      {
39      }
40  
41      /***
42       * Creates a NumberKey equivalent to <code>key</code>.
43       *
44       * @param key the key value
45       */
46      public NumberKey(String key)
47      {
48          this.key = new BigDecimal(key);
49      }
50  
51      /***
52       * Creates a NumberKey equivalent to <code>key</code>.
53       *
54       * @param key the key value
55       */
56      public NumberKey(BigDecimal key)
57      {
58          this.key = key;
59      }
60  
61      /***
62       * Creates a NumberKey equivalent to <code>key</code>.
63       *
64       * @param key the key value
65       */
66      public NumberKey(NumberKey key)
67      {
68          if (key != null)
69          {
70              this.key = key.getValue();
71          }
72          else
73          {
74              this.key = null;
75          }
76      }
77  
78      /***
79       * Creates a NumberKey equivalent to <code>key</code>.
80       *
81       * @param key the key value
82       */
83      public NumberKey(long key)
84      {
85          this.key = BigDecimal.valueOf(key);
86      }
87  
88      /***
89       * Creates a NumberKey equivalent to <code>key</code>.
90       *
91       * @param key the key value
92       */
93      public NumberKey(double key)
94      {
95          this.key = new BigDecimal(key);
96      }
97  
98      /***
99       * Creates a NumberKey equivalent to <code>key</code>.
100      * Convenience only.
101      *
102      * @param key the key value
103      */
104     public NumberKey(int key)
105     {
106         this((long) key);
107     }
108 
109     /***
110      * Creates a NumberKey equivalent to <code>key</code>.
111      * Convenience only.
112      *
113      * @param key the key value
114      */
115     public NumberKey(Number key)
116     {
117         if (key != null)
118         {
119             this.key = new BigDecimal(key.toString());
120         }
121         else
122         {
123             this.key = null;
124         }
125     }
126 
127     /***
128      * Sets the internal representation using a String representation
129      * of a number
130      *
131      * @param key the key value
132      * @throws NumberFormatException if key is not a valid number
133      */
134     public void setValue(String key) throws NumberFormatException
135     {
136         this.key = new BigDecimal(key);
137     }
138 
139     /***
140      * Sets the underlying object
141      *
142      * @param key the key value
143      */
144     public void setValue(BigDecimal key)
145     {
146         this.key = key;
147     }
148 
149     /***
150      * Sets the internal representation to the same object used by key.
151      *
152      * @param key the key value
153      */
154     public void setValue(NumberKey key)
155     {
156         this.key = (key == null ? null : key.getValue());
157     }
158 
159     /***
160      * Access the underlying BigDecimal object.
161      *
162      * @return a <code>BigDecimal</code> value
163      */
164     public BigDecimal getBigDecimal()
165     {
166         return (BigDecimal) key;
167     }
168 
169     /***
170      * Two ObjectKeys that both contain null values <strong>are not</strong>
171      * considered equal.
172      *
173      * @param keyObj the key to compare values to
174      * @return whether the two objects are equal
175      */
176     public boolean equals(Object keyObj)
177     {
178         if (keyObj == this)
179         {
180             return true;
181         }
182 
183         if (!(keyObj instanceof NumberKey))
184         {
185             // NumberKeys used to be comparable to Strings.  This behavior has
186             // been changed, I don't think it is a good idea to fail silently
187             // as code may be dependent on the old behavior.
188             if (keyObj instanceof String)
189             {
190                 throw new IllegalArgumentException(
191                     "NumberKeys are not comparable to Strings");
192             }
193 
194             return false;
195         }
196 
197         if (getValue() != null)
198         {
199             return getValue().equals(((NumberKey) keyObj).getValue());
200         }
201         else
202         {
203             // Even if they are both null...still return false.
204             return false;
205         }
206     }
207 
208     /***
209      * @return a hash code based on the value
210      */
211     public int hashCode()
212     {
213         if (getValue() == null)
214         {
215             return super.hashCode();
216         }
217         else
218         {
219             return getValue().hashCode();
220         }
221     }
222 
223     /***
224      * @param o the comparison value
225      * @return a numeric comparison of the two values
226      */
227     public int compareTo(Object o)
228     {
229         return getBigDecimal().compareTo(((NumberKey) o).getBigDecimal());
230     }
231 
232     /***
233      * Invokes the toString() method on the object.  An empty string
234      * is returned is the value is null.
235      *
236      * @return a String representation of the key value
237      */
238     public String toString()
239     {
240         if (key != null)
241         {
242             return key.toString();
243         }
244         return "";
245     }
246 
247     /***
248      * Returns the value of this NumberKey as a byte. This value is subject
249      * to the conversion rules set out in
250      * {@link java.math.BigDecimal#byteValue()}
251      *
252      * @return the NumberKey converted to a byte
253      */
254     public byte byteValue()
255     {
256         return getBigDecimal().byteValue();
257     }
258 
259     /***
260      * Returns the value of this NumberKey as an int. This value is subject
261      * to the conversion rules set out in
262      * {@link java.math.BigDecimal#intValue()}, importantly any fractional part
263      * will be discarded and if the underlying value is too big to fit in an
264      * int, only the low-order 32 bits are returned. Note that this
265      * conversion can lose information about the overall magnitude and
266      * precision of the NumberKey value as well as return a result with the
267      * opposite sign.
268      *
269      * @return the NumberKey converted to an int
270      */
271     public int intValue()
272     {
273         return getBigDecimal().intValue();
274     }
275 
276     /***
277      * Returns the value of this NumberKey as a short. This value is subject
278      * to the conversion rules set out in
279      * {@link java.math.BigDecimal#intValue()}, importantly any fractional part
280      *  will be discarded and if the underlying value is too big to fit
281      * in a long, only the low-order 64 bits are returned. Note that this
282      * conversion can lose information about the overall magnitude and
283      * precision of the NumberKey value as well as return a result with the
284      * opposite sign.
285      *
286      * @return the NumberKey converted to a short
287      */
288     public short shortValue()
289     {
290         return getBigDecimal().shortValue();
291     }
292 
293     /***
294      * Returns the value of this NumberKey as a long. This value is subject
295      * to the conversion rules set out in
296      * {@link java.math.BigDecimal#intValue()}
297      *
298      * @return the NumberKey converted to a long
299      */
300     public long longValue()
301     {
302         return getBigDecimal().longValue();
303     }
304 
305     /***
306      * Returns the value of this NumberKey as a float. This value is subject to
307      * the conversion rules set out in
308      * {@link java.math.BigDecimal#floatValue()}, most importantly if the
309      * underlying value has too great a magnitude to represent as a
310      * float, it will be converted to Float.NEGATIVE_INFINITY
311      * or Float.POSITIVE_INFINITY as appropriate.
312      *
313      * @return the NumberKey converted to a float
314      */
315     public float floatValue()
316     {
317         return getBigDecimal().floatValue();
318     }
319 
320     /***
321      * Returns the value of this NumberKey as a double. This value is subject
322      * to the conversion rules set out in
323      * {@link java.math.BigDecimal#doubleValue()}, most importantly if the
324      * underlying value has too great a magnitude to represent as a
325      * double, it will be converted to Double.NEGATIVE_INFINITY
326      * or Double.POSITIVE_INFINITY as appropriate.
327      *
328      * @return the NumberKey converted to a double
329      */
330     public double doubleValue()
331     {
332         return getBigDecimal().doubleValue();
333     }
334 }