< prev index next >

src/java.base/share/classes/java/util/Objects.java

Print this page

  8  * particular file as subject to the "Classpath" exception as provided
  9  * by Oracle in the LICENSE file that accompanied this code.
 10  *
 11  * This code is distributed in the hope that it will be useful, but WITHOUT
 12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 14  * version 2 for more details (a copy is included in the LICENSE file that
 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package java.util;
 27 

 28 import jdk.internal.util.Preconditions;
 29 import jdk.internal.vm.annotation.ForceInline;

 30 
 31 import java.util.function.Supplier;
 32 
 33 /**
 34  * This class consists of {@code static} utility methods for operating
 35  * on objects, or checking certain conditions before operation.  These utilities
 36  * include {@code null}-safe or {@code null}-tolerant methods for computing the
 37  * hash code of an object, returning a string for an object, comparing two
 38  * objects, and checking if indexes or sub-range values are out of bounds.
 39  *
 40  * @since 1.7
 41  */
 42 public final class Objects {
 43     private Objects() {
 44         throw new AssertionError("No java.util.Objects instances for you!");
 45     }
 46 
 47     /**
 48      * Returns {@code true} if the arguments are equal to each other
 49      * and {@code false} otherwise.

171      *
172      * @implNote
173      * This method constructs a string for an object without calling
174      * any overridable methods of the object.
175      *
176      * @implSpec
177      * The method returns a string equivalent to:<br>
178      * {@code o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o))}
179      *
180      * @param o an object
181      * @throws NullPointerException if the argument is null
182      * @see Object#toString
183      * @see System#identityHashCode(Object)
184      * @since 19
185      */
186     public static String toIdentityString(Object o) {
187         requireNonNull(o);
188         return o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o));
189     }
190 






















































































191     /**
192      * Returns 0 if the arguments are identical and {@code
193      * c.compare(a, b)} otherwise.
194      * Consequently, if both arguments are {@code null} 0
195      * is returned.
196      *
197      * <p>Note that if one of the arguments is {@code null}, a {@code
198      * NullPointerException} may or may not be thrown depending on
199      * what ordering policy, if any, the {@link Comparator Comparator}
200      * chooses to have for {@code null} values.
201      *
202      * @param <T> the type of the objects being compared
203      * @param a an object
204      * @param b an object to be compared with {@code a}
205      * @param c the {@code Comparator} to compare the first two arguments
206      * @return 0 if the arguments are identical and {@code
207      * c.compare(a, b)} otherwise.
208      * @see Comparable
209      * @see Comparator
210      */

420      * inequalities is true:
421      * <ul>
422      *  <li>{@code fromIndex < 0}</li>
423      *  <li>{@code size < 0}</li>
424      *  <li>{@code fromIndex + size > length}, taking into account integer overflow</li>
425      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
426      * </ul>
427      *
428      * @param fromIndex the lower-bound (inclusive) of the sub-interval
429      * @param size the size of the sub-range
430      * @param length the upper-bound (exclusive) of the range
431      * @return {@code fromIndex} if the sub-range within bounds of the range
432      * @throws IndexOutOfBoundsException if the sub-range is out of bounds
433      * @since 9
434      */
435     public static
436     int checkFromIndexSize(int fromIndex, int size, int length) {
437         return Preconditions.checkFromIndexSize(fromIndex, size, length, null);
438     }
439 











440     /**
441      * Checks if the {@code index} is within the bounds of the range from
442      * {@code 0} (inclusive) to {@code length} (exclusive).
443      *
444      * <p>The {@code index} is defined to be out of bounds if any of the
445      * following inequalities is true:
446      * <ul>
447      *  <li>{@code index < 0}</li>
448      *  <li>{@code index >= length}</li>
449      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
450      * </ul>
451      *
452      * @param index the index
453      * @param length the upper-bound (exclusive) of the range
454      * @return {@code index} if it is within bounds of the range
455      * @throws IndexOutOfBoundsException if the {@code index} is out of bounds
456      * @since 16
457      */
458     @ForceInline
459     public static

  8  * particular file as subject to the "Classpath" exception as provided
  9  * by Oracle in the LICENSE file that accompanied this code.
 10  *
 11  * This code is distributed in the hope that it will be useful, but WITHOUT
 12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 14  * version 2 for more details (a copy is included in the LICENSE file that
 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package java.util;
 27 
 28 import jdk.internal.misc.ValhallaFeatures;
 29 import jdk.internal.util.Preconditions;
 30 import jdk.internal.vm.annotation.ForceInline;
 31 import jdk.internal.misc.Unsafe;
 32 
 33 import java.util.function.Supplier;
 34 
 35 /**
 36  * This class consists of {@code static} utility methods for operating
 37  * on objects, or checking certain conditions before operation.  These utilities
 38  * include {@code null}-safe or {@code null}-tolerant methods for computing the
 39  * hash code of an object, returning a string for an object, comparing two
 40  * objects, and checking if indexes or sub-range values are out of bounds.
 41  *
 42  * @since 1.7
 43  */
 44 public final class Objects {
 45     private Objects() {
 46         throw new AssertionError("No java.util.Objects instances for you!");
 47     }
 48 
 49     /**
 50      * Returns {@code true} if the arguments are equal to each other
 51      * and {@code false} otherwise.

173      *
174      * @implNote
175      * This method constructs a string for an object without calling
176      * any overridable methods of the object.
177      *
178      * @implSpec
179      * The method returns a string equivalent to:<br>
180      * {@code o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o))}
181      *
182      * @param o an object
183      * @throws NullPointerException if the argument is null
184      * @see Object#toString
185      * @see System#identityHashCode(Object)
186      * @since 19
187      */
188     public static String toIdentityString(Object o) {
189         requireNonNull(o);
190         return o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o));
191     }
192 
193    /**
194     * {@return {@code true} if the specified object reference is an identity object,
195     * otherwise {@code false}}
196     *
197     * @param obj an object
198     * @throws NullPointerException if {@code obj} is {@code null}
199     */
200 //    @IntrinsicCandidate
201     public static boolean isIdentityObject(Object obj) {
202         requireNonNull(obj);
203         return obj.getClass().isIdentity() ||  // Before Valhalla all classes are identity classes
204                 obj.getClass() == Object.class;
205     }
206 
207     /**
208      * Checks that the specified object reference is an identity object.
209      *
210      * @param obj the object reference to check for identity
211      * @param <T> the type of the reference
212      * @return {@code obj} if {@code obj} is an identity object
213      * @throws NullPointerException if {@code obj} is {@code null}
214      * @throws IdentityException if {@code obj} is not an identity object
215      * @since Valhalla
216      */
217     @ForceInline
218     public static <T> T requireIdentity(T obj) {
219         Objects.requireNonNull(obj);
220         if (!isIdentityObject(obj))
221             throw new IdentityException(obj.getClass());
222         return obj;
223     }
224 
225     /**
226      * Checks that the specified object reference is an identity object.
227      *
228      * @param obj the object reference to check for identity
229      * @param message detail message to be used in the event that an
230      *        {@code IdentityException} is thrown; may be null
231      * @param <T> the type of the reference
232      * @return {@code obj} if {@code obj} is an identity object
233      * @throws NullPointerException if {@code obj} is {@code null}
234      * @throws IdentityException if {@code obj} is not an identity object
235      * @since Valhalla
236      */
237     @ForceInline
238     public static <T> T requireIdentity(T obj, String message) {
239         Objects.requireNonNull(obj);
240         if (!isIdentityObject(obj))
241             throw new IdentityException(message);
242         return obj;
243     }
244 
245     /**
246      * Checks that the specified object reference is an identity object.
247      *
248      * @param obj the object reference to check for identity
249      * @param messageSupplier supplier of the detail message to be
250      *        used in the event that an {@code IdentityException} is thrown; may be null
251      * @param <T> the type of the reference
252      * @return {@code obj} if {@code obj} is an identity object
253      * @throws NullPointerException if {@code obj} is {@code null}
254      * @throws IdentityException if {@code obj} is not an identity object
255      * @since Valhalla
256      */
257     @ForceInline
258     public static <T> T requireIdentity(T obj, Supplier<String> messageSupplier) {
259         Objects.requireNonNull(obj);
260         if (!isIdentityObject(obj))
261             throw new IdentityException(messageSupplier == null ?
262                     null : messageSupplier.get());
263         return obj;
264     }
265 
266    /**
267     * {@return {@code true} if the specified object is a {@linkplain Class#isValue value object},
268     * otherwise {@code false}}
269     *
270     * @param obj an object
271     * @throws NullPointerException if {@code obj} is {@code null}
272     */
273 //    @IntrinsicCandidate
274     public static boolean isValueObject(Object obj) {
275         requireNonNull(obj, "obj");
276         return obj.getClass().isValue();
277     }
278 
279     /**
280      * Returns 0 if the arguments are identical and {@code
281      * c.compare(a, b)} otherwise.
282      * Consequently, if both arguments are {@code null} 0
283      * is returned.
284      *
285      * <p>Note that if one of the arguments is {@code null}, a {@code
286      * NullPointerException} may or may not be thrown depending on
287      * what ordering policy, if any, the {@link Comparator Comparator}
288      * chooses to have for {@code null} values.
289      *
290      * @param <T> the type of the objects being compared
291      * @param a an object
292      * @param b an object to be compared with {@code a}
293      * @param c the {@code Comparator} to compare the first two arguments
294      * @return 0 if the arguments are identical and {@code
295      * c.compare(a, b)} otherwise.
296      * @see Comparable
297      * @see Comparator
298      */

508      * inequalities is true:
509      * <ul>
510      *  <li>{@code fromIndex < 0}</li>
511      *  <li>{@code size < 0}</li>
512      *  <li>{@code fromIndex + size > length}, taking into account integer overflow</li>
513      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
514      * </ul>
515      *
516      * @param fromIndex the lower-bound (inclusive) of the sub-interval
517      * @param size the size of the sub-range
518      * @param length the upper-bound (exclusive) of the range
519      * @return {@code fromIndex} if the sub-range within bounds of the range
520      * @throws IndexOutOfBoundsException if the sub-range is out of bounds
521      * @since 9
522      */
523     public static
524     int checkFromIndexSize(int fromIndex, int size, int length) {
525         return Preconditions.checkFromIndexSize(fromIndex, size, length, null);
526     }
527 
528     /**
529      * Return the size of the object in the heap.
530      *
531      * @param o an object
532      * @return the objects's size
533      * @since Valhalla
534      */
535     public static long getObjectSize(Object o) {
536         return Unsafe.getUnsafe().getObjectSize(o);
537     }
538 
539     /**
540      * Checks if the {@code index} is within the bounds of the range from
541      * {@code 0} (inclusive) to {@code length} (exclusive).
542      *
543      * <p>The {@code index} is defined to be out of bounds if any of the
544      * following inequalities is true:
545      * <ul>
546      *  <li>{@code index < 0}</li>
547      *  <li>{@code index >= length}</li>
548      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
549      * </ul>
550      *
551      * @param index the index
552      * @param length the upper-bound (exclusive) of the range
553      * @return {@code index} if it is within bounds of the range
554      * @throws IndexOutOfBoundsException if the {@code index} is out of bounds
555      * @since 16
556      */
557     @ForceInline
558     public static
< prev index next >