001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.lang3.builder; 018 019import java.lang.reflect.AccessibleObject; 020import java.lang.reflect.Field; 021import java.lang.reflect.Modifier; 022import java.util.Collection; 023import java.util.Comparator; 024 025import org.apache.commons.lang3.ArrayUtils; 026 027/** 028 * Assists in implementing {@link java.lang.Comparable#compareTo(Object)} methods. 029 * 030 * It is consistent with <code>equals(Object)</code> and 031 * <code>hashcode()</code> built with {@link EqualsBuilder} and 032 * {@link HashCodeBuilder}.</p> 033 * 034 * <p>Two Objects that compare equal using <code>equals(Object)</code> should normally 035 * also compare equal using <code>compareTo(Object)</code>.</p> 036 * 037 * <p>All relevant fields should be included in the calculation of the 038 * comparison. Derived fields may be ignored. The same fields, in the same 039 * order, should be used in both <code>compareTo(Object)</code> and 040 * <code>equals(Object)</code>.</p> 041 * 042 * <p>To use this class write code as follows:</p> 043 * 044 * <pre> 045 * public class MyClass { 046 * String field1; 047 * int field2; 048 * boolean field3; 049 * 050 * ... 051 * 052 * public int compareTo(Object o) { 053 * MyClass myClass = (MyClass) o; 054 * return new CompareToBuilder() 055 * .appendSuper(super.compareTo(o) 056 * .append(this.field1, myClass.field1) 057 * .append(this.field2, myClass.field2) 058 * .append(this.field3, myClass.field3) 059 * .toComparison(); 060 * } 061 * } 062 * </pre> 063 * 064 * <p>Alternatively, there are {@link #reflectionCompare(Object, Object) reflectionCompare} methods that use 065 * reflection to determine the fields to append. Because fields can be private, 066 * <code>reflectionCompare</code> uses {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} to 067 * bypass normal access control checks. This will fail under a security manager, 068 * unless the appropriate permissions are set up correctly. It is also 069 * slower than appending explicitly.</p> 070 * 071 * <p>A typical implementation of <code>compareTo(Object)</code> using 072 * <code>reflectionCompare</code> looks like:</p> 073 074 * <pre> 075 * public int compareTo(Object o) { 076 * return CompareToBuilder.reflectionCompare(this, o); 077 * } 078 * </pre> 079 * 080 * @see java.lang.Comparable 081 * @see java.lang.Object#equals(Object) 082 * @see java.lang.Object#hashCode() 083 * @see EqualsBuilder 084 * @see HashCodeBuilder 085 * @since 1.0 086 * @version $Id: CompareToBuilder.java 1436770 2013-01-22 07:09:45Z ggregory $ 087 */ 088public class CompareToBuilder implements Builder<Integer> { 089 090 /** 091 * Current state of the comparison as appended fields are checked. 092 */ 093 private int comparison; 094 095 /** 096 * <p>Constructor for CompareToBuilder.</p> 097 * 098 * <p>Starts off assuming that the objects are equal. Multiple calls are 099 * then made to the various append methods, followed by a call to 100 * {@link #toComparison} to get the result.</p> 101 */ 102 public CompareToBuilder() { 103 super(); 104 comparison = 0; 105 } 106 107 //----------------------------------------------------------------------- 108 /** 109 * <p>Compares two <code>Object</code>s via reflection.</p> 110 * 111 * <p>Fields can be private, thus <code>AccessibleObject.setAccessible</code> 112 * is used to bypass normal access control checks. This will fail under a 113 * security manager unless the appropriate permissions are set.</p> 114 * 115 * <ul> 116 * <li>Static fields will not be compared</li> 117 * <li>Transient members will be not be compared, as they are likely derived 118 * fields</li> 119 * <li>Superclass fields will be compared</li> 120 * </ul> 121 * 122 * <p>If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, 123 * they are considered equal.</p> 124 * 125 * @param lhs left-hand object 126 * @param rhs right-hand object 127 * @return a negative integer, zero, or a positive integer as <code>lhs</code> 128 * is less than, equal to, or greater than <code>rhs</code> 129 * @throws NullPointerException if either (but not both) parameters are 130 * <code>null</code> 131 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible 132 * with <code>lhs</code> 133 */ 134 public static int reflectionCompare(final Object lhs, final Object rhs) { 135 return reflectionCompare(lhs, rhs, false, null); 136 } 137 138 /** 139 * <p>Compares two <code>Object</code>s via reflection.</p> 140 * 141 * <p>Fields can be private, thus <code>AccessibleObject.setAccessible</code> 142 * is used to bypass normal access control checks. This will fail under a 143 * security manager unless the appropriate permissions are set.</p> 144 * 145 * <ul> 146 * <li>Static fields will not be compared</li> 147 * <li>If <code>compareTransients</code> is <code>true</code>, 148 * compares transient members. Otherwise ignores them, as they 149 * are likely derived fields.</li> 150 * <li>Superclass fields will be compared</li> 151 * </ul> 152 * 153 * <p>If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, 154 * they are considered equal.</p> 155 * 156 * @param lhs left-hand object 157 * @param rhs right-hand object 158 * @param compareTransients whether to compare transient fields 159 * @return a negative integer, zero, or a positive integer as <code>lhs</code> 160 * is less than, equal to, or greater than <code>rhs</code> 161 * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code> 162 * (but not both) is <code>null</code> 163 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible 164 * with <code>lhs</code> 165 */ 166 public static int reflectionCompare(final Object lhs, final Object rhs, final boolean compareTransients) { 167 return reflectionCompare(lhs, rhs, compareTransients, null); 168 } 169 170 /** 171 * <p>Compares two <code>Object</code>s via reflection.</p> 172 * 173 * <p>Fields can be private, thus <code>AccessibleObject.setAccessible</code> 174 * is used to bypass normal access control checks. This will fail under a 175 * security manager unless the appropriate permissions are set.</p> 176 * 177 * <ul> 178 * <li>Static fields will not be compared</li> 179 * <li>If <code>compareTransients</code> is <code>true</code>, 180 * compares transient members. Otherwise ignores them, as they 181 * are likely derived fields.</li> 182 * <li>Superclass fields will be compared</li> 183 * </ul> 184 * 185 * <p>If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, 186 * they are considered equal.</p> 187 * 188 * @param lhs left-hand object 189 * @param rhs right-hand object 190 * @param excludeFields Collection of String fields to exclude 191 * @return a negative integer, zero, or a positive integer as <code>lhs</code> 192 * is less than, equal to, or greater than <code>rhs</code> 193 * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code> 194 * (but not both) is <code>null</code> 195 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible 196 * with <code>lhs</code> 197 * @since 2.2 198 */ 199 public static int reflectionCompare(final Object lhs, final Object rhs, final Collection<String> excludeFields) { 200 return reflectionCompare(lhs, rhs, ReflectionToStringBuilder.toNoNullStringArray(excludeFields)); 201 } 202 203 /** 204 * <p>Compares two <code>Object</code>s via reflection.</p> 205 * 206 * <p>Fields can be private, thus <code>AccessibleObject.setAccessible</code> 207 * is used to bypass normal access control checks. This will fail under a 208 * security manager unless the appropriate permissions are set.</p> 209 * 210 * <ul> 211 * <li>Static fields will not be compared</li> 212 * <li>If <code>compareTransients</code> is <code>true</code>, 213 * compares transient members. Otherwise ignores them, as they 214 * are likely derived fields.</li> 215 * <li>Superclass fields will be compared</li> 216 * </ul> 217 * 218 * <p>If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, 219 * they are considered equal.</p> 220 * 221 * @param lhs left-hand object 222 * @param rhs right-hand object 223 * @param excludeFields array of fields to exclude 224 * @return a negative integer, zero, or a positive integer as <code>lhs</code> 225 * is less than, equal to, or greater than <code>rhs</code> 226 * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code> 227 * (but not both) is <code>null</code> 228 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible 229 * with <code>lhs</code> 230 * @since 2.2 231 */ 232 public static int reflectionCompare(final Object lhs, final Object rhs, final String... excludeFields) { 233 return reflectionCompare(lhs, rhs, false, null, excludeFields); 234 } 235 236 /** 237 * <p>Compares two <code>Object</code>s via reflection.</p> 238 * 239 * <p>Fields can be private, thus <code>AccessibleObject.setAccessible</code> 240 * is used to bypass normal access control checks. This will fail under a 241 * security manager unless the appropriate permissions are set.</p> 242 * 243 * <ul> 244 * <li>Static fields will not be compared</li> 245 * <li>If the <code>compareTransients</code> is <code>true</code>, 246 * compares transient members. Otherwise ignores them, as they 247 * are likely derived fields.</li> 248 * <li>Compares superclass fields up to and including <code>reflectUpToClass</code>. 249 * If <code>reflectUpToClass</code> is <code>null</code>, compares all superclass fields.</li> 250 * </ul> 251 * 252 * <p>If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, 253 * they are considered equal.</p> 254 * 255 * @param lhs left-hand object 256 * @param rhs right-hand object 257 * @param compareTransients whether to compare transient fields 258 * @param reflectUpToClass last superclass for which fields are compared 259 * @param excludeFields fields to exclude 260 * @return a negative integer, zero, or a positive integer as <code>lhs</code> 261 * is less than, equal to, or greater than <code>rhs</code> 262 * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code> 263 * (but not both) is <code>null</code> 264 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible 265 * with <code>lhs</code> 266 * @since 2.2 (2.0 as <code>reflectionCompare(Object, Object, boolean, Class)</code>) 267 */ 268 public static int reflectionCompare( 269 final Object lhs, 270 final Object rhs, 271 final boolean compareTransients, 272 final Class<?> reflectUpToClass, 273 final String... excludeFields) { 274 275 if (lhs == rhs) { 276 return 0; 277 } 278 if (lhs == null || rhs == null) { 279 throw new NullPointerException(); 280 } 281 Class<?> lhsClazz = lhs.getClass(); 282 if (!lhsClazz.isInstance(rhs)) { 283 throw new ClassCastException(); 284 } 285 final CompareToBuilder compareToBuilder = new CompareToBuilder(); 286 reflectionAppend(lhs, rhs, lhsClazz, compareToBuilder, compareTransients, excludeFields); 287 while (lhsClazz.getSuperclass() != null && lhsClazz != reflectUpToClass) { 288 lhsClazz = lhsClazz.getSuperclass(); 289 reflectionAppend(lhs, rhs, lhsClazz, compareToBuilder, compareTransients, excludeFields); 290 } 291 return compareToBuilder.toComparison(); 292 } 293 294 /** 295 * <p>Appends to <code>builder</code> the comparison of <code>lhs</code> 296 * to <code>rhs</code> using the fields defined in <code>clazz</code>.</p> 297 * 298 * @param lhs left-hand object 299 * @param rhs right-hand object 300 * @param clazz <code>Class</code> that defines fields to be compared 301 * @param builder <code>CompareToBuilder</code> to append to 302 * @param useTransients whether to compare transient fields 303 * @param excludeFields fields to exclude 304 */ 305 private static void reflectionAppend( 306 final Object lhs, 307 final Object rhs, 308 final Class<?> clazz, 309 final CompareToBuilder builder, 310 final boolean useTransients, 311 final String[] excludeFields) { 312 313 final Field[] fields = clazz.getDeclaredFields(); 314 AccessibleObject.setAccessible(fields, true); 315 for (int i = 0; i < fields.length && builder.comparison == 0; i++) { 316 final Field f = fields[i]; 317 if (!ArrayUtils.contains(excludeFields, f.getName()) 318 && (f.getName().indexOf('$') == -1) 319 && (useTransients || !Modifier.isTransient(f.getModifiers())) 320 && (!Modifier.isStatic(f.getModifiers()))) { 321 try { 322 builder.append(f.get(lhs), f.get(rhs)); 323 } catch (final IllegalAccessException e) { 324 // This can't happen. Would get a Security exception instead. 325 // Throw a runtime exception in case the impossible happens. 326 throw new InternalError("Unexpected IllegalAccessException"); 327 } 328 } 329 } 330 } 331 332 //----------------------------------------------------------------------- 333 /** 334 * <p>Appends to the <code>builder</code> the <code>compareTo(Object)</code> 335 * result of the superclass.</p> 336 * 337 * @param superCompareTo result of calling <code>super.compareTo(Object)</code> 338 * @return this - used to chain append calls 339 * @since 2.0 340 */ 341 public CompareToBuilder appendSuper(final int superCompareTo) { 342 if (comparison != 0) { 343 return this; 344 } 345 comparison = superCompareTo; 346 return this; 347 } 348 349 //----------------------------------------------------------------------- 350 /** 351 * <p>Appends to the <code>builder</code> the comparison of 352 * two <code>Object</code>s.</p> 353 * 354 * <ol> 355 * <li>Check if <code>lhs == rhs</code></li> 356 * <li>Check if either <code>lhs</code> or <code>rhs</code> is <code>null</code>, 357 * a <code>null</code> object is less than a non-<code>null</code> object</li> 358 * <li>Check the object contents</li> 359 * </ol> 360 * 361 * <p><code>lhs</code> must either be an array or implement {@link Comparable}.</p> 362 * 363 * @param lhs left-hand object 364 * @param rhs right-hand object 365 * @return this - used to chain append calls 366 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible 367 * with <code>lhs</code> 368 */ 369 public CompareToBuilder append(final Object lhs, final Object rhs) { 370 return append(lhs, rhs, null); 371 } 372 373 /** 374 * <p>Appends to the <code>builder</code> the comparison of 375 * two <code>Object</code>s.</p> 376 * 377 * <ol> 378 * <li>Check if <code>lhs == rhs</code></li> 379 * <li>Check if either <code>lhs</code> or <code>rhs</code> is <code>null</code>, 380 * a <code>null</code> object is less than a non-<code>null</code> object</li> 381 * <li>Check the object contents</li> 382 * </ol> 383 * 384 * <p>If <code>lhs</code> is an array, array comparison methods will be used. 385 * Otherwise <code>comparator</code> will be used to compare the objects. 386 * If <code>comparator</code> is <code>null</code>, <code>lhs</code> must 387 * implement {@link Comparable} instead.</p> 388 * 389 * @param lhs left-hand object 390 * @param rhs right-hand object 391 * @param comparator <code>Comparator</code> used to compare the objects, 392 * <code>null</code> means treat lhs as <code>Comparable</code> 393 * @return this - used to chain append calls 394 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible 395 * with <code>lhs</code> 396 * @since 2.0 397 */ 398 public CompareToBuilder append(final Object lhs, final Object rhs, final Comparator<?> comparator) { 399 if (comparison != 0) { 400 return this; 401 } 402 if (lhs == rhs) { 403 return this; 404 } 405 if (lhs == null) { 406 comparison = -1; 407 return this; 408 } 409 if (rhs == null) { 410 comparison = +1; 411 return this; 412 } 413 if (lhs.getClass().isArray()) { 414 // switch on type of array, to dispatch to the correct handler 415 // handles multi dimensional arrays 416 // throws a ClassCastException if rhs is not the correct array type 417 if (lhs instanceof long[]) { 418 append((long[]) lhs, (long[]) rhs); 419 } else if (lhs instanceof int[]) { 420 append((int[]) lhs, (int[]) rhs); 421 } else if (lhs instanceof short[]) { 422 append((short[]) lhs, (short[]) rhs); 423 } else if (lhs instanceof char[]) { 424 append((char[]) lhs, (char[]) rhs); 425 } else if (lhs instanceof byte[]) { 426 append((byte[]) lhs, (byte[]) rhs); 427 } else if (lhs instanceof double[]) { 428 append((double[]) lhs, (double[]) rhs); 429 } else if (lhs instanceof float[]) { 430 append((float[]) lhs, (float[]) rhs); 431 } else if (lhs instanceof boolean[]) { 432 append((boolean[]) lhs, (boolean[]) rhs); 433 } else { 434 // not an array of primitives 435 // throws a ClassCastException if rhs is not an array 436 append((Object[]) lhs, (Object[]) rhs, comparator); 437 } 438 } else { 439 // the simple case, not an array, just test the element 440 if (comparator == null) { 441 @SuppressWarnings("unchecked") // assume this can be done; if not throw CCE as per Javadoc 442 final Comparable<Object> comparable = (Comparable<Object>) lhs; 443 comparison = comparable.compareTo(rhs); 444 } else { 445 @SuppressWarnings("unchecked") // assume this can be done; if not throw CCE as per Javadoc 446 final Comparator<Object> comparator2 = (Comparator<Object>) comparator; 447 comparison = comparator2.compare(lhs, rhs); 448 } 449 } 450 return this; 451 } 452 453 //------------------------------------------------------------------------- 454 /** 455 * Appends to the <code>builder</code> the comparison of 456 * two <code>long</code>s. 457 * 458 * @param lhs left-hand value 459 * @param rhs right-hand value 460 * @return this - used to chain append calls 461 */ 462 public CompareToBuilder append(final long lhs, final long rhs) { 463 if (comparison != 0) { 464 return this; 465 } 466 comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0)); 467 return this; 468 } 469 470 /** 471 * Appends to the <code>builder</code> the comparison of 472 * two <code>int</code>s. 473 * 474 * @param lhs left-hand value 475 * @param rhs right-hand value 476 * @return this - used to chain append calls 477 */ 478 public CompareToBuilder append(final int lhs, final int rhs) { 479 if (comparison != 0) { 480 return this; 481 } 482 comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0)); 483 return this; 484 } 485 486 /** 487 * Appends to the <code>builder</code> the comparison of 488 * two <code>short</code>s. 489 * 490 * @param lhs left-hand value 491 * @param rhs right-hand value 492 * @return this - used to chain append calls 493 */ 494 public CompareToBuilder append(final short lhs, final short rhs) { 495 if (comparison != 0) { 496 return this; 497 } 498 comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0)); 499 return this; 500 } 501 502 /** 503 * Appends to the <code>builder</code> the comparison of 504 * two <code>char</code>s. 505 * 506 * @param lhs left-hand value 507 * @param rhs right-hand value 508 * @return this - used to chain append calls 509 */ 510 public CompareToBuilder append(final char lhs, final char rhs) { 511 if (comparison != 0) { 512 return this; 513 } 514 comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0)); 515 return this; 516 } 517 518 /** 519 * Appends to the <code>builder</code> the comparison of 520 * two <code>byte</code>s. 521 * 522 * @param lhs left-hand value 523 * @param rhs right-hand value 524 * @return this - used to chain append calls 525 */ 526 public CompareToBuilder append(final byte lhs, final byte rhs) { 527 if (comparison != 0) { 528 return this; 529 } 530 comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0)); 531 return this; 532 } 533 534 /** 535 * <p>Appends to the <code>builder</code> the comparison of 536 * two <code>double</code>s.</p> 537 * 538 * <p>This handles NaNs, Infinities, and <code>-0.0</code>.</p> 539 * 540 * <p>It is compatible with the hash code generated by 541 * <code>HashCodeBuilder</code>.</p> 542 * 543 * @param lhs left-hand value 544 * @param rhs right-hand value 545 * @return this - used to chain append calls 546 */ 547 public CompareToBuilder append(final double lhs, final double rhs) { 548 if (comparison != 0) { 549 return this; 550 } 551 comparison = Double.compare(lhs, rhs); 552 return this; 553 } 554 555 /** 556 * <p>Appends to the <code>builder</code> the comparison of 557 * two <code>float</code>s.</p> 558 * 559 * <p>This handles NaNs, Infinities, and <code>-0.0</code>.</p> 560 * 561 * <p>It is compatible with the hash code generated by 562 * <code>HashCodeBuilder</code>.</p> 563 * 564 * @param lhs left-hand value 565 * @param rhs right-hand value 566 * @return this - used to chain append calls 567 */ 568 public CompareToBuilder append(final float lhs, final float rhs) { 569 if (comparison != 0) { 570 return this; 571 } 572 comparison = Float.compare(lhs, rhs); 573 return this; 574 } 575 576 /** 577 * Appends to the <code>builder</code> the comparison of 578 * two <code>booleans</code>s. 579 * 580 * @param lhs left-hand value 581 * @param rhs right-hand value 582 * @return this - used to chain append calls 583 */ 584 public CompareToBuilder append(final boolean lhs, final boolean rhs) { 585 if (comparison != 0) { 586 return this; 587 } 588 if (lhs == rhs) { 589 return this; 590 } 591 if (lhs == false) { 592 comparison = -1; 593 } else { 594 comparison = +1; 595 } 596 return this; 597 } 598 599 //----------------------------------------------------------------------- 600 /** 601 * <p>Appends to the <code>builder</code> the deep comparison of 602 * two <code>Object</code> arrays.</p> 603 * 604 * <ol> 605 * <li>Check if arrays are the same using <code>==</code></li> 606 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 607 * <li>Check array length, a short length array is less than a long length array</li> 608 * <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li> 609 * </ol> 610 * 611 * <p>This method will also will be called for the top level of multi-dimensional, 612 * ragged, and multi-typed arrays.</p> 613 * 614 * @param lhs left-hand array 615 * @param rhs right-hand array 616 * @return this - used to chain append calls 617 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible 618 * with <code>lhs</code> 619 */ 620 public CompareToBuilder append(final Object[] lhs, final Object[] rhs) { 621 return append(lhs, rhs, null); 622 } 623 624 /** 625 * <p>Appends to the <code>builder</code> the deep comparison of 626 * two <code>Object</code> arrays.</p> 627 * 628 * <ol> 629 * <li>Check if arrays are the same using <code>==</code></li> 630 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 631 * <li>Check array length, a short length array is less than a long length array</li> 632 * <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li> 633 * </ol> 634 * 635 * <p>This method will also will be called for the top level of multi-dimensional, 636 * ragged, and multi-typed arrays.</p> 637 * 638 * @param lhs left-hand array 639 * @param rhs right-hand array 640 * @param comparator <code>Comparator</code> to use to compare the array elements, 641 * <code>null</code> means to treat <code>lhs</code> elements as <code>Comparable</code>. 642 * @return this - used to chain append calls 643 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible 644 * with <code>lhs</code> 645 * @since 2.0 646 */ 647 public CompareToBuilder append(final Object[] lhs, final Object[] rhs, final Comparator<?> comparator) { 648 if (comparison != 0) { 649 return this; 650 } 651 if (lhs == rhs) { 652 return this; 653 } 654 if (lhs == null) { 655 comparison = -1; 656 return this; 657 } 658 if (rhs == null) { 659 comparison = +1; 660 return this; 661 } 662 if (lhs.length != rhs.length) { 663 comparison = (lhs.length < rhs.length) ? -1 : +1; 664 return this; 665 } 666 for (int i = 0; i < lhs.length && comparison == 0; i++) { 667 append(lhs[i], rhs[i], comparator); 668 } 669 return this; 670 } 671 672 /** 673 * <p>Appends to the <code>builder</code> the deep comparison of 674 * two <code>long</code> arrays.</p> 675 * 676 * <ol> 677 * <li>Check if arrays are the same using <code>==</code></li> 678 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 679 * <li>Check array length, a shorter length array is less than a longer length array</li> 680 * <li>Check array contents element by element using {@link #append(long, long)}</li> 681 * </ol> 682 * 683 * @param lhs left-hand array 684 * @param rhs right-hand array 685 * @return this - used to chain append calls 686 */ 687 public CompareToBuilder append(final long[] lhs, final long[] rhs) { 688 if (comparison != 0) { 689 return this; 690 } 691 if (lhs == rhs) { 692 return this; 693 } 694 if (lhs == null) { 695 comparison = -1; 696 return this; 697 } 698 if (rhs == null) { 699 comparison = +1; 700 return this; 701 } 702 if (lhs.length != rhs.length) { 703 comparison = (lhs.length < rhs.length) ? -1 : +1; 704 return this; 705 } 706 for (int i = 0; i < lhs.length && comparison == 0; i++) { 707 append(lhs[i], rhs[i]); 708 } 709 return this; 710 } 711 712 /** 713 * <p>Appends to the <code>builder</code> the deep comparison of 714 * two <code>int</code> arrays.</p> 715 * 716 * <ol> 717 * <li>Check if arrays are the same using <code>==</code></li> 718 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 719 * <li>Check array length, a shorter length array is less than a longer length array</li> 720 * <li>Check array contents element by element using {@link #append(int, int)}</li> 721 * </ol> 722 * 723 * @param lhs left-hand array 724 * @param rhs right-hand array 725 * @return this - used to chain append calls 726 */ 727 public CompareToBuilder append(final int[] lhs, final int[] rhs) { 728 if (comparison != 0) { 729 return this; 730 } 731 if (lhs == rhs) { 732 return this; 733 } 734 if (lhs == null) { 735 comparison = -1; 736 return this; 737 } 738 if (rhs == null) { 739 comparison = +1; 740 return this; 741 } 742 if (lhs.length != rhs.length) { 743 comparison = (lhs.length < rhs.length) ? -1 : +1; 744 return this; 745 } 746 for (int i = 0; i < lhs.length && comparison == 0; i++) { 747 append(lhs[i], rhs[i]); 748 } 749 return this; 750 } 751 752 /** 753 * <p>Appends to the <code>builder</code> the deep comparison of 754 * two <code>short</code> arrays.</p> 755 * 756 * <ol> 757 * <li>Check if arrays are the same using <code>==</code></li> 758 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 759 * <li>Check array length, a shorter length array is less than a longer length array</li> 760 * <li>Check array contents element by element using {@link #append(short, short)}</li> 761 * </ol> 762 * 763 * @param lhs left-hand array 764 * @param rhs right-hand array 765 * @return this - used to chain append calls 766 */ 767 public CompareToBuilder append(final short[] lhs, final short[] rhs) { 768 if (comparison != 0) { 769 return this; 770 } 771 if (lhs == rhs) { 772 return this; 773 } 774 if (lhs == null) { 775 comparison = -1; 776 return this; 777 } 778 if (rhs == null) { 779 comparison = +1; 780 return this; 781 } 782 if (lhs.length != rhs.length) { 783 comparison = (lhs.length < rhs.length) ? -1 : +1; 784 return this; 785 } 786 for (int i = 0; i < lhs.length && comparison == 0; i++) { 787 append(lhs[i], rhs[i]); 788 } 789 return this; 790 } 791 792 /** 793 * <p>Appends to the <code>builder</code> the deep comparison of 794 * two <code>char</code> arrays.</p> 795 * 796 * <ol> 797 * <li>Check if arrays are the same using <code>==</code></li> 798 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 799 * <li>Check array length, a shorter length array is less than a longer length array</li> 800 * <li>Check array contents element by element using {@link #append(char, char)}</li> 801 * </ol> 802 * 803 * @param lhs left-hand array 804 * @param rhs right-hand array 805 * @return this - used to chain append calls 806 */ 807 public CompareToBuilder append(final char[] lhs, final char[] rhs) { 808 if (comparison != 0) { 809 return this; 810 } 811 if (lhs == rhs) { 812 return this; 813 } 814 if (lhs == null) { 815 comparison = -1; 816 return this; 817 } 818 if (rhs == null) { 819 comparison = +1; 820 return this; 821 } 822 if (lhs.length != rhs.length) { 823 comparison = (lhs.length < rhs.length) ? -1 : +1; 824 return this; 825 } 826 for (int i = 0; i < lhs.length && comparison == 0; i++) { 827 append(lhs[i], rhs[i]); 828 } 829 return this; 830 } 831 832 /** 833 * <p>Appends to the <code>builder</code> the deep comparison of 834 * two <code>byte</code> arrays.</p> 835 * 836 * <ol> 837 * <li>Check if arrays are the same using <code>==</code></li> 838 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 839 * <li>Check array length, a shorter length array is less than a longer length array</li> 840 * <li>Check array contents element by element using {@link #append(byte, byte)}</li> 841 * </ol> 842 * 843 * @param lhs left-hand array 844 * @param rhs right-hand array 845 * @return this - used to chain append calls 846 */ 847 public CompareToBuilder append(final byte[] lhs, final byte[] rhs) { 848 if (comparison != 0) { 849 return this; 850 } 851 if (lhs == rhs) { 852 return this; 853 } 854 if (lhs == null) { 855 comparison = -1; 856 return this; 857 } 858 if (rhs == null) { 859 comparison = +1; 860 return this; 861 } 862 if (lhs.length != rhs.length) { 863 comparison = (lhs.length < rhs.length) ? -1 : +1; 864 return this; 865 } 866 for (int i = 0; i < lhs.length && comparison == 0; i++) { 867 append(lhs[i], rhs[i]); 868 } 869 return this; 870 } 871 872 /** 873 * <p>Appends to the <code>builder</code> the deep comparison of 874 * two <code>double</code> arrays.</p> 875 * 876 * <ol> 877 * <li>Check if arrays are the same using <code>==</code></li> 878 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 879 * <li>Check array length, a shorter length array is less than a longer length array</li> 880 * <li>Check array contents element by element using {@link #append(double, double)}</li> 881 * </ol> 882 * 883 * @param lhs left-hand array 884 * @param rhs right-hand array 885 * @return this - used to chain append calls 886 */ 887 public CompareToBuilder append(final double[] lhs, final double[] rhs) { 888 if (comparison != 0) { 889 return this; 890 } 891 if (lhs == rhs) { 892 return this; 893 } 894 if (lhs == null) { 895 comparison = -1; 896 return this; 897 } 898 if (rhs == null) { 899 comparison = +1; 900 return this; 901 } 902 if (lhs.length != rhs.length) { 903 comparison = (lhs.length < rhs.length) ? -1 : +1; 904 return this; 905 } 906 for (int i = 0; i < lhs.length && comparison == 0; i++) { 907 append(lhs[i], rhs[i]); 908 } 909 return this; 910 } 911 912 /** 913 * <p>Appends to the <code>builder</code> the deep comparison of 914 * two <code>float</code> arrays.</p> 915 * 916 * <ol> 917 * <li>Check if arrays are the same using <code>==</code></li> 918 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 919 * <li>Check array length, a shorter length array is less than a longer length array</li> 920 * <li>Check array contents element by element using {@link #append(float, float)}</li> 921 * </ol> 922 * 923 * @param lhs left-hand array 924 * @param rhs right-hand array 925 * @return this - used to chain append calls 926 */ 927 public CompareToBuilder append(final float[] lhs, final float[] rhs) { 928 if (comparison != 0) { 929 return this; 930 } 931 if (lhs == rhs) { 932 return this; 933 } 934 if (lhs == null) { 935 comparison = -1; 936 return this; 937 } 938 if (rhs == null) { 939 comparison = +1; 940 return this; 941 } 942 if (lhs.length != rhs.length) { 943 comparison = (lhs.length < rhs.length) ? -1 : +1; 944 return this; 945 } 946 for (int i = 0; i < lhs.length && comparison == 0; i++) { 947 append(lhs[i], rhs[i]); 948 } 949 return this; 950 } 951 952 /** 953 * <p>Appends to the <code>builder</code> the deep comparison of 954 * two <code>boolean</code> arrays.</p> 955 * 956 * <ol> 957 * <li>Check if arrays are the same using <code>==</code></li> 958 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li> 959 * <li>Check array length, a shorter length array is less than a longer length array</li> 960 * <li>Check array contents element by element using {@link #append(boolean, boolean)}</li> 961 * </ol> 962 * 963 * @param lhs left-hand array 964 * @param rhs right-hand array 965 * @return this - used to chain append calls 966 */ 967 public CompareToBuilder append(final boolean[] lhs, final boolean[] rhs) { 968 if (comparison != 0) { 969 return this; 970 } 971 if (lhs == rhs) { 972 return this; 973 } 974 if (lhs == null) { 975 comparison = -1; 976 return this; 977 } 978 if (rhs == null) { 979 comparison = +1; 980 return this; 981 } 982 if (lhs.length != rhs.length) { 983 comparison = (lhs.length < rhs.length) ? -1 : +1; 984 return this; 985 } 986 for (int i = 0; i < lhs.length && comparison == 0; i++) { 987 append(lhs[i], rhs[i]); 988 } 989 return this; 990 } 991 992 //----------------------------------------------------------------------- 993 /** 994 * Returns a negative integer, a positive integer, or zero as 995 * the <code>builder</code> has judged the "left-hand" side 996 * as less than, greater than, or equal to the "right-hand" 997 * side. 998 * 999 * @return final comparison result 1000 * @see #build() 1001 */ 1002 public int toComparison() { 1003 return comparison; 1004 } 1005 1006 /** 1007 * Returns a negative Integer, a positive Integer, or zero as 1008 * the <code>builder</code> has judged the "left-hand" side 1009 * as less than, greater than, or equal to the "right-hand" 1010 * side. 1011 * 1012 * @return final comparison result as an Integer 1013 * @see #toComparison() 1014 * @since 3.0 1015 */ 1016 @Override 1017 public Integer build() { 1018 return Integer.valueOf(toComparison()); 1019 } 1020} 1021