Util


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.jface.util;
13  
14  import java.util.Collections  ;
15  import java.util.List  ;
16  import java.util.MissingResourceException  ;
17  import java.util.ResourceBundle  ;
18  import java.util.SortedSet  ;
19  import java.util.TreeSet  ;
20  
21  /**
22   * <p>
23   * A static class providing utility methods to all of JFace.
24   * </p>
25   * 
26   * @since 3.1
27   */
28  public final class Util {
29  
30      /**
31       * An unmodifiable, empty, sorted set. This value is guaranteed to never
32       * change and never be <code>null</code>.
33       */
34      public static final SortedSet   EMPTY_SORTED_SET = Collections
35              .unmodifiableSortedSet(new TreeSet  ());
36  
37      /**
38       * A common zero-length string. It avoids needing write <code>NON-NLS</code>
39       * next to code fragments. It's also a bit clearer to read.
40       */
41      public static final String   ZERO_LENGTH_STRING = ""; //$NON-NLS-1$
42  
43      /**
44       * Verifies that the given object is an instance of the given class.
45       * 
46       * @param object
47       *            The object to check; may be <code>null</code>.
48       * @param c
49       *            The class which the object should be; must not be
50       *            <code>null</code>.
51       */
52      public static final void assertInstance(final Object   object, final Class   c) {
53          assertInstance(object, c, false);
54      }
55  
56      /**
57       * Verifies the given object is an instance of the given class. It is
58       * possible to specify whether the object is permitted to be
59       * <code>null</code>.
60       * 
61       * @param object
62       *            The object to check; may be <code>null</code>.
63       * @param c
64       *            The class which the object should be; must not be
65       *            <code>null</code>.
66       * @param allowNull
67       *            Whether the object is allowed to be <code>null</code>.
68       */
69      private static final void assertInstance(final Object   object,
70              final Class   c, final boolean allowNull) {
71          if (object == null && allowNull) {
72              return;
73          }
74  
75          if (object == null || c == null) {
76              throw new NullPointerException  ();
77          } else if (!c.isInstance(object)) {
78              throw new IllegalArgumentException  ();
79          }
80      }
81  
82      /**
83       * Compares two boolean values. <code>false</code> is considered to be
84       * "less than" <code>true</code>.
85       * 
86       * @param left
87       *            The left value to compare
88       * @param right
89       *            The right value to compare
90       * @return <code>-1</code> if the left is <code>false</code> and the
91       *         right is <code>true</code>. <code>1</code> if the opposite
92       *         is true. If they are equal, then it returns <code>0</code>.
93       */
94      public static final int compare(final boolean left, final boolean right) {
95          return left == false ? (right == true ? -1 : 0) : 1;
96      }
97  
98      /**
99       * Compares two integer values.
100      * 
101      * @param left
102      *            The left value to compare
103      * @param right
104      *            The right value to compare
105      * @return <code>left - right</code>
106      */
107     public static final int compare(final int left, final int right) {
108         return left - right;
109     }
110 
111     /**
112      * Compares to comparable objects -- defending against <code>null</code>.
113      * 
114      * @param left
115      *            The left object to compare; may be <code>null</code>.
116      * @param right
117      *            The right object to compare; may be <code>null</code>.
118      * @return The result of the comparison. <code>null</code> is considered
119      *         to be the least possible value.
120      */
121     public static final int compare(final Comparable   left,
122             final Comparable   right) {
123         if (left == null && right == null) {
124             return 0;
125         } else if (left == null) {
126             return -1;
127         } else if (right == null) {
128             return 1;
129         } else {
130             return left.compareTo(right);
131         }
132     }
133 
134     /**
135      * Compares two arrays of comparable objects -- accounting for
136      * <code>null</code>.
137      * 
138      * @param left
139      *            The left array to be compared; may be <code>null</code>.
140      * @param right
141      *            The right array to be compared; may be <code>null</code>.
142      * @return The result of the comparison. <code>null</code> is considered
143      *         to be the least possible value. A shorter array is considered
144      *         less than a longer array.
145      */
146     public static final int compare(final Comparable  [] left,
147             final Comparable  [] right) {
148         if (left == null && right == null) {
149             return 0;
150         } else if (left == null) {
151             return -1;
152         } else if (right == null) {
153             return 1;
154         } else {
155             int l = left.length;
156             int r = right.length;
157 
158             if (l != r) {
159                 return l - r;
160             }
161 
162             for (int i = 0; i < l; i++) {
163                 int compareTo = compare(left[i], right[i]);
164 
165                 if (compareTo != 0) {
166                     return compareTo;
167                 }
168             }
169 
170             return 0;
171         }
172     }
173 
174     /**
175      * Compares two lists -- account for <code>null</code>. The lists must
176      * contain comparable objects.
177      * 
178      * @param left
179      *            The left list to compare; may be <code>null</code>. This
180      *            list must only contain instances of <code>Comparable</code>.
181      * @param right
182      *            The right list to compare; may be <code>null</code>. This
183      *            list must only contain instances of <code>Comparable</code>.
184      * @return The result of the comparison. <code>null</code> is considered
185      *         to be the least possible value. A shorter list is considered less
186      *         than a longer list.
187      */
188     public static final int compare(final List   left, final List   right) {
189         if (left == null && right == null) {
190             return 0;
191         } else if (left == null) {
192             return -1;
193         } else if (right == null) {
194             return 1;
195         } else {
196             int l = left.size();
197             int r = right.size();
198 
199             if (l != r) {
200                 return l - r;
201             }
202 
203             for (int i = 0; i < l; i++) {
204                 int compareTo = compare((Comparable  ) left.get(i),
205                         (Comparable  ) right.get(i));
206 
207                 if (compareTo != 0) {
208                     return compareTo;
209                 }
210             }
211 
212             return 0;
213         }
214     }
215 
216     /**
217      * Tests whether the first array ends with the second array.
218      * 
219      * @param left
220      *            The array to check (larger); may be <code>null</code>.
221      * @param right
222      *            The array that should be a subsequence (smaller); may be
223      *            <code>null</code>.
224      * @param equals
225      *            Whether the two array are allowed to be equal.
226      * @return <code>true</code> if the second array is a subsequence of the
227      *         array list, and they share end elements.
228      */
229     public static final boolean endsWith(final Object  [] left,
230             final Object  [] right, final boolean equals) {
231         if (left == null || right == null) {
232             return false;
233         }
234 
235         int l = left.length;
236         int r = right.length;
237 
238         if (r > l || !equals && r == l) {
239             return false;
240         }
241 
242         for (int i = 0; i < r; i++) {
243             if (!equals(left[l - i - 1], right[r - i - 1])) {
244                 return false;
245             }
246         }
247 
248         return true;
249     }
250 
251     /**
252      * Checks whether the two objects are <code>null</code> -- allowing for
253      * <code>null</code>.
254      * 
255      * @param left
256      *            The left object to compare; may be <code>null</code>.
257      * @param right
258      *            The right object to compare; may be <code>null</code>.
259      * @return <code>true</code> if the two objects are equivalent;
260      *         <code>false</code> otherwise.
261      */
262     public static final boolean equals(final Object   left, final Object   right) {
263         return left == null ? right == null : ((right != null) && left
264                 .equals(right));
265     }
266 
267     /**
268      * Tests whether two arrays of objects are equal to each other. The arrays
269      * must not be <code>null</code>, but their elements may be
270      * <code>null</code>.
271      * 
272      * @param leftArray
273      *            The left array to compare; may be <code>null</code>, and
274      *            may be empty and may contain <code>null</code> elements.
275      * @param rightArray
276      *            The right array to compare; may be <code>null</code>, and
277      *            may be empty and may contain <code>null</code> elements.
278      * @return <code>true</code> if the arrays are equal length and the
279      *         elements at the same position are equal; <code>false</code>
280      *         otherwise.
281      */
282     public static final boolean equals(final Object  [] leftArray,
283             final Object  [] rightArray) {
284         if (leftArray == rightArray) {
285             return true;
286         }
287 
288         if (leftArray == null) {
289             return (rightArray == null);
290         } else if (rightArray == null) {
291             return false;
292         }
293 
294         if (leftArray.length != rightArray.length) {
295             return false;
296         }
297 
298         for (int i = 0; i < leftArray.length; i++) {
299             final Object   left = leftArray[i];
300             final Object   right = rightArray[i];
301             final boolean equal = (left == null) ? (right == null) : (left
302                     .equals(right));
303             if (!equal) {
304                 return false;
305             }
306         }
307 
308         return true;
309     }
310 
311     /**
312      * Provides a hash code based on the given integer value.
313      * 
314      * @param i
315      *            The integer value
316      * @return <code>i</code>
317      */
318     public static final int hashCode(final int i) {
319         return i;
320     }
321 
322     /**
323      * Provides a hash code for the object -- defending against
324      * <code>null</code>.
325      * 
326      * @param object
327      *            The object for which a hash code is required.
328      * @return <code>object.hashCode</code> or <code>0</code> if
329      *         <code>object</code> if <code>null</code>.
330      */
331     public static final int hashCode(final Object   object) {
332         return object != null ? object.hashCode() : 0;
333     }
334 
335     /**
336      * Computes the hash code for an array of objects, but with defense against
337      * <code>null</code>.
338      * 
339      * @param objects
340      *            The array of objects for which a hash code is needed; may be
341      *            <code>null</code>.
342      * @return The hash code for <code>objects</code>; or <code>0</code> if
343      *         <code>objects</code> is <code>null</code>.
344      */
345     public static final int hashCode(final Object  [] objects) {
346         if (objects == null) {
347             return 0;
348         }
349 
350         int hashCode = 89;
351         for (int i = 0; i < objects.length; i++) {
352             final Object   object = objects[i];
353             if (object != null) {
354                 hashCode = hashCode * 31 + object.hashCode();
355             }
356         }
357 
358         return hashCode;
359     }
360 
361     /**
362      * Checks whether the second array is a subsequence of the first array, and
363      * that they share common starting elements.
364      * 
365      * @param left
366      *            The first array to compare (large); may be <code>null</code>.
367      * @param right
368      *            The second array to compare (small); may be <code>null</code>.
369      * @param equals
370      *            Whether it is allowed for the two arrays to be equivalent.
371      * @return <code>true</code> if the first arrays starts with the second
372      *         list; <code>false</code> otherwise.
373      */
374     public static final boolean startsWith(final Object  [] left,
375             final Object  [] right, final boolean equals) {
376         if (left == null || right == null) {
377             return false;
378         }
379 
380         int l = left.length;
381         int r = right.length;
382 
383         if (r > l || !equals && r == l) {
384             return false;
385         }
386 
387         for (int i = 0; i < r; i++) {
388             if (!equals(left[i], right[i])) {
389                 return false;
390             }
391         }
392 
393         return true;
394     }
395 
396     /**
397      * Converts an array into a string representation that is suitable for
398      * debugging.
399      * 
400      * @param array
401      *            The array to convert; may be <code>null</code>.
402      * @return The string representation of the array; never <code>null</code>.
403      */
404     public static final String   toString(final Object  [] array) {
405         if (array == null) {
406             return "null"; //$NON-NLS-1$
407         }
408 
409         final StringBuffer   buffer = new StringBuffer  ();
410         buffer.append('[');
411 
412         final int length = array.length;
413         for (int i = 0; i < length; i++) {
414             if (i != 0) {
415                 buffer.append(',');
416             }
417             final Object   object = array[i];
418             final String   element = String.valueOf(object);
419             buffer.append(element);
420         }
421         buffer.append(']');
422 
423         return buffer.toString();
424     }
425 
426     /**
427      * Provides a translation of a particular key from the resource bundle.
428      * 
429      * @param resourceBundle
430      *            The key to look up in the resource bundle; should not be
431      *            <code>null</code>.
432      * @param key
433      *            The key to look up in the resource bundle; should not be
434      *            <code>null</code>.
435      * @param defaultString
436      *            The value to return if the resource cannot be found; may be
437      *            <code>null</code>.
438      * @return The value of the translated resource at <code>key</code>. If
439      *         the key cannot be found, then it is simply the
440      *         <code>defaultString</code>.
441      */
442     public static final String   translateString(
443             final ResourceBundle   resourceBundle, final String   key,
444             final String   defaultString) {
445         if (resourceBundle != null && key != null) {
446             try {
447                 final String   translatedString = resourceBundle.getString(key);
448 
449                 if (translatedString != null) {
450                     return translatedString;
451                 }
452             } catch (MissingResourceException   eMissingResource) {
453                 // Such is life. We'll return the key
454             }
455         }
456 
457         return defaultString;
458     }
459 
460     /**
461      * This class should never be constructed.
462      */
463     private Util() {
464         // Not allowed.
465     }
466 }
467
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags