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.core.internal.commands.util;
13  
14  import java.util.Collections  ;
15  import java.util.HashMap  ;
16  import java.util.HashSet  ;
17  import java.util.Iterator  ;
18  import java.util.Map  ;
19  import java.util.Set  ;
20  import java.util.SortedMap  ;
21  import java.util.SortedSet  ;
22  import java.util.TreeMap  ;
23  import java.util.TreeSet  ;
24  
25  /**
26   * A class providing utility functions for the commands plug-in.
27   * 
28   * @since 3.1
29   */
30  public final class Util {
31  
32      /**
33       * A shared, unmodifiable, empty, sorted map. This value is guaranteed to
34       * always be the same.
35       */
36      public final static SortedMap   EMPTY_SORTED_MAP = Collections
37              .unmodifiableSortedMap(new TreeMap  ());
38  
39      /**
40       * A shared, unmodifiable, empty, sorted set. This value is guaranteed to
41       * always be the same.
42       */
43      public final static SortedSet   EMPTY_SORTED_SET = Collections
44              .unmodifiableSortedSet(new TreeSet  ());
45  
46      /**
47       * A shared, zero-length string -- for avoiding non-externalized string
48       * tags. This value is guaranteed to always be the same.
49       */
50      public final static String   ZERO_LENGTH_STRING = ""; //$NON-NLS-1$
51  
52      /**
53       * Asserts the the given object is an instance of the given class --
54       * optionally allowing the object to be <code>null</code>.
55       * 
56       * @param object
57       *            The object for which the type should be checked.
58       * @param c
59       *            The class that the object must be; fails if the class is
60       *            <code>null</code>.
61       * @param allowNull
62       *            Whether the object being <code>null</code> will not cause a
63       *            failure.
64       */
65      public static final void assertInstance(final Object   object, final Class   c,
66              final boolean allowNull) {
67          if (object == null && allowNull) {
68              return;
69          }
70  
71          if (object == null || c == null) {
72              throw new NullPointerException  ();
73          } else if (!c.isInstance(object)) {
74              throw new IllegalArgumentException  ();
75          }
76      }
77  
78      /**
79       * Compares two boolean values. <code>false</code> is considered to be
80       * less than <code>true</code>.
81       * 
82       * @param left
83       *            The left value to compare.
84       * @param right
85       *            The right value to compare.
86       * @return <code>-1</code> if <code>left</code> is <code>false</code>
87       *         and <code>right</code> is <code>true</code>;<code>0</code>
88       *         if they are equal; <code>1</code> if <code>left</code> is
89       *         <code>true</code> and <code>right</code> is
90       *         <code>false</code>
91       */
92      public static final int compare(final boolean left, final boolean right) {
93          return left == false ? (right == true ? -1 : 0) : (right == true ? 0
94                  : 1);
95      }
96  
97      /**
98       * Compares two comparable objects, but with protection against
99       * <code>null</code>.
100      * 
101      * @param left
102      *            The left value to compare; may be <code>null</code>.
103      * @param right
104      *            The right value to compare; may be <code>null</code>.
105      * @return <code>-1</code> if <code>left</code> is <code>null</code>
106      *         and <code>right</code> is not <code>null</code>;
107      *         <code>0</code> if they are both <code>null</code>;
108      *         <code>1</code> if <code>left</code> is not <code>null</code>
109      *         and <code>right</code> is <code>null</code>. Otherwise, the
110      *         result of <code>left.compareTo(right)</code>.
111      */
112     public static final int compare(final Comparable   left,
113             final Comparable   right) {
114         if (left == null && right == null) {
115             return 0;
116         } else if (left == null) {
117             return -1;
118         } else if (right == null) {
119             return 1;
120         } else {
121             return left.compareTo(right);
122         }
123     }
124 
125     /**
126      * Compares two integer values. This method fails if the distance between
127      * <code>left</code> and <code>right</code> is greater than
128      * <code>Integer.MAX_VALUE</code>.
129      * 
130      * @param left
131      *            The left value to compare.
132      * @param right
133      *            The right value to compare.
134      * @return <code>left - right</code>
135      */
136     public static final int compare(final int left, final int right) {
137         return left - right;
138     }
139 
140     /**
141      * Compares two objects that are not otherwise comparable. If neither object
142      * is <code>null</code>, then the string representation of each object is
143      * used.
144      * 
145      * @param left
146      *            The left value to compare. The string representation of this
147      *            value must not be <code>null</code>.
148      * @param right
149      *            The right value to compare. The string representation of this
150      *            value must not be <code>null</code>.
151      * @return <code>-1</code> if <code>left</code> is <code>null</code>
152      *         and <code>right</code> is not <code>null</code>;
153      *         <code>0</code> if they are both <code>null</code>;
154      *         <code>1</code> if <code>left</code> is not <code>null</code>
155      *         and <code>right</code> is <code>null</code>. Otherwise, the
156      *         result of
157      *         <code>left.toString().compareTo(right.toString())</code>.
158      */
159     public static final int compare(final Object   left, final Object   right) {
160         if (left == null && right == null) {
161             return 0;
162         } else if (left == null) {
163             return -1;
164         } else if (right == null) {
165             return 1;
166         } else {
167             return left.toString().compareTo(right.toString());
168         }
169     }
170 
171     /**
172      * Decides whether two booleans are equal.
173      * 
174      * @param left
175      *            The first boolean to compare; may be <code>null</code>.
176      * @param right
177      *            The second boolean to compare; may be <code>null</code>.
178      * @return <code>true</code> if the booleans are equal; <code>false</code>
179      *         otherwise.
180      */
181     public static final boolean equals(final boolean left, final boolean right) {
182         return left == right;
183     }
184 
185     /**
186      * Decides whether two objects are equal -- defending against
187      * <code>null</code>.
188      * 
189      * @param left
190      *            The first object to compare; may be <code>null</code>.
191      * @param right
192      *            The second object to compare; may be <code>null</code>.
193      * @return <code>true</code> if the objects are equals; <code>false</code>
194      *         otherwise.
195      */
196     public static final boolean equals(final Object   left, final Object   right) {
197         return left == null ? right == null : ((right != null) && left
198                 .equals(right));
199     }
200 
201     /**
202      * Tests whether two arrays of objects are equal to each other. The arrays
203      * must not be <code>null</code>, but their elements may be
204      * <code>null</code>.
205      * 
206      * @param leftArray
207      *            The left array to compare; may be <code>null</code>, and
208      *            may be empty and may contain <code>null</code> elements.
209      * @param rightArray
210      *            The right array to compare; may be <code>null</code>, and
211      *            may be empty and may contain <code>null</code> elements.
212      * @return <code>true</code> if the arrays are equal length and the
213      *         elements at the same position are equal; <code>false</code>
214      *         otherwise.
215      */
216     public static final boolean equals(final Object  [] leftArray,
217             final Object  [] rightArray) {
218         if (leftArray == null) {
219             return (rightArray == null);
220         } else if (rightArray == null) {
221             return false;
222         }
223 
224         if (leftArray.length != rightArray.length) {
225             return false;
226         }
227 
228         for (int i = 0; i < leftArray.length; i++) {
229             final Object   left = leftArray[i];
230             final Object   right = rightArray[i];
231             final boolean equal = (left == null) ? (right == null) : (left
232                     .equals(right));
233             if (!equal) {
234                 return false;
235             }
236         }
237 
238         return true;
239     }
240 
241     /**
242      * Computes the hash code for an integer.
243      * 
244      * @param i
245      *            The integer for which a hash code should be computed.
246      * @return <code>i</code>.
247      */
248     public static final int hashCode(final int i) {
249         return i;
250     }
251 
252     /**
253      * Computes the hash code for an object, but with defense against
254      * <code>null</code>.
255      * 
256      * @param object
257      *            The object for which a hash code is needed; may be
258      *            <code>null</code>.
259      * @return The hash code for <code>object</code>; or <code>0</code> if
260      *         <code>object</code> is <code>null</code>.
261      */
262     public static final int hashCode(final Object   object) {
263         return object != null ? object.hashCode() : 0;
264     }
265 
266     /**
267      * Makes a type-safe copy of the given map. This method should be used when
268      * a map is crossing an API boundary (i.e., from a hostile plug-in into
269      * internal code, or vice versa).
270      * 
271      * @param map
272      *            The map which should be copied; must not be <code>null</code>.
273      * @param keyClass
274      *            The class that all the keys must be; must not be
275      *            <code>null</code>.
276      * @param valueClass
277      *            The class that all the values must be; must not be
278      *            <code>null</code>.
279      * @param allowNullKeys
280      *            Whether <code>null</code> keys should be allowed.
281      * @param allowNullValues
282      *            Whether <code>null</code> values should be allowed.
283      * @return A copy of the map; may be empty, but never <code>null</code>.
284      */
285     public static final Map   safeCopy(final Map   map, final Class   keyClass,
286             final Class   valueClass, final boolean allowNullKeys,
287             final boolean allowNullValues) {
288         if (map == null || keyClass == null || valueClass == null) {
289             throw new NullPointerException  ();
290         }
291 
292         final Map   copy = Collections.unmodifiableMap(new HashMap  (map));
293         final Iterator   iterator = copy.entrySet().iterator();
294 
295         while (iterator.hasNext()) {
296             final Map.Entry   entry = (Map.Entry  ) iterator.next();
297             assertInstance(entry.getKey(), keyClass, allowNullKeys);
298             assertInstance(entry.getValue(), valueClass, allowNullValues);
299         }
300 
301         return map;
302     }
303 
304     /**
305      * Makes a type-safe copy of the given set. This method should be used when
306      * a set is crossing an API boundary (i.e., from a hostile plug-in into
307      * internal code, or vice versa).
308      * 
309      * @param set
310      *            The set which should be copied; must not be <code>null</code>.
311      * @param c
312      *            The class that all the values must be; must not be
313      *            <code>null</code>.
314      * @return A copy of the set; may be empty, but never <code>null</code>.
315      *         None of its element will be <code>null</code>.
316      */
317     public static final Set   safeCopy(final Set   set, final Class   c) {
318         return safeCopy(set, c, false);
319     }
320 
321     /**
322      * Makes a type-safe copy of the given set. This method should be used when
323      * a set is crossing an API boundary (i.e., from a hostile plug-in into
324      * internal code, or vice versa).
325      * 
326      * @param set
327      *            The set which should be copied; must not be <code>null</code>.
328      * @param c
329      *            The class that all the values must be; must not be
330      *            <code>null</code>.
331      * @param allowNullElements
332      *            Whether null values should be allowed.
333      * @return A copy of the set; may be empty, but never <code>null</code>.
334      */
335     public static final Set   safeCopy(final Set   set, final Class   c,
336             final boolean allowNullElements) {
337         if (set == null || c == null) {
338             throw new NullPointerException  ();
339         }
340 
341         final Set   copy = Collections.unmodifiableSet(new HashSet  (set));
342         final Iterator   iterator = copy.iterator();
343 
344         while (iterator.hasNext()) {
345             assertInstance(iterator.next(), c, allowNullElements);
346         }
347 
348         return set;
349     }
350 
351     /**
352      * The utility class is meant to just provide static members.
353      */
354     private Util() {
355         // Should not be called.
356     }
357 }
358
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags