Apache
/
commons-lang
mirror of https://github.com/apache/commons-lang.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Javadoc style fix, from Fredrik Westermarck 

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137135 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stephen Colebourne 2002-11-17 21:46:42 +00:00
parent 7184f0650c
commit 97883eec49
6 changed files with 1414 additions and 915 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

270
src/java/org/apache/commons/lang/builder/CompareToBuilder.java
View File

@ -58,21 +58,22 @@ import java.lang.reflect.Modifier;
import org.apache.commons.lang.NumberUtils;
/**
* <code>CompareTo</code> generation routines.
* <p>
* This class provides methods to build a good <comde>compareTo()</code> method for any class.
* It is consistent with the <code>equals</code> and <code>hashcode</code> built
* with EqualsBuilder and HashCodeBuilder.
* <p>
* Two object that compare equal using equals should compare equals using
* compareTo.
* <p>
* All relevant fields should be included in the calculation of the comparison. Derived
* fields may be ignored. The same fields, in the same order, should be used in
* both <code>compareTo</code> and <code>equals</code>.
* <p>
* Typical use for the code is as follows:
* <p><code>CompareTo</code> generation routines.</p>
*
* <p>This class provides methods to build a good <comde>compareTo()</code>
* method for any class. It is consistent with the <code>equals</code> and
* <code>hashcode</code> built with {@link EqualsBuilder} and
* {@link HashCodeBuilder}.</p>
*
* <p>Two object that compare equal using equals should compare equals using
* compareTo</p>.
*
* <p>All relevant fields should be included in the calculation of the
* comparison. Derived fields may be ignored. The same fields, in the same
* order, should be used in both <code>compareTo</code> and
* <code>equals</code>.</p>
*
* <p>Typical use for the code is as follows:</p>
* <pre>
* public int comapareTo(Object o) {
* MyClass rhs = (MyClass) o;
@ -83,23 +84,24 @@ import org.apache.commons.lang.NumberUtils;
* .toComparison();
* }
* </pre>
* <p>
* Alternatively, there is a method that uses reflection to determine
*
* <p>Alternatively, there is a method that uses reflection to determine
* the fields to test. Because these fields are usually private, the method,
* <code>reflectionCompare</code>, uses <code>Field.setAccessible</code> to change
* the visibility of the fields. This will fail under a security manager,
* unless the appropriate permissions are set. It is also slower than testing
* explicitly.
* <p>
* A typical invocation for this method would look like:
* explicitly.</p>
*
* <p>A typical invocation for this method would look like:</p>
* <pre>
* public int compareTo(Object o) {
* return CompareToBuilder.reflectionCompare(this, obj);
* }
* </pre>
*
* @author <a href="mailto:steve.downey@netfolio.com">Steve Downey</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: CompareToBuilder.java,v 1.4 2002/09/28 10:44:51 scolebourne Exp $
* @version $Id: CompareToBuilder.java,v 1.5 2002/11/17 21:46:42 scolebourne Exp $
*/
public class CompareToBuilder {
/**
@ -108,8 +110,10 @@ public class CompareToBuilder {
private int comparison;
/**
* Constructor for CompareToBuilder.
* Starts off assuming that the objects are equal.
* <p>Constructor for CompareToBuilder.</p>
*
* <p>Starts off assuming that the objects are equal.</p>
*
* @see java.lang.Object#Object()
*/
public CompareToBuilder() {
@ -120,47 +124,56 @@ public class CompareToBuilder {
//-------------------------------------------------------------------------
/**
* This method uses reflection to determine the ordering between two objects.
* <p>
* It uses Field.setAccessible to gain access to private fields. This means
* that it will throw a security exception if run under a security manger, if
* the permissions are not set up.
* It is also not as efficient as testing explicitly.
* Transient members will be not be tested, as they are likely derived
* fields, and not part of the value of the object.
* Static fields will not be tested.
* <p>This method uses reflection to determine the ordering between two
* Objects.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
* a security manger, if the permissions are not set up correctly. It is
* also not as efficient as testing explicitly.</p>
*
* <p>Transient members will be not be tested, as they are likely derived
* fields, and not part of the value of the object.</p>
*
* <p>Static fields will not be tested.</p>
*
* @param lhs Left Hand Side
* @param rhs Right Hand Side
* @return a negative integer, zero, or a positive integer as this
* object is less than, equal to, or greater than the specified object.
* @throws NullPointerException if either (but not both) parameter is null
* @throws ClassCastException if the specified object's type prevents it
* from being compared to this Object.
* Object is less than, equal to, or greater than the specified Object.
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
* @throws ClassCastException if the specified Object's type prevents it
* from being compared to this Object.
*/
public static int reflectionCompare(Object lhs, Object rhs) {
return reflectionCompare(lhs, rhs, false);
}
/**
* This method uses reflection to determine if the two object are equal.
* <p>
* It uses Field.setAccessible to gain access to private fields. This means
* that it will throw a security exception if run under a security manger, if
* the permissions are not set up.
* It is also not as efficient as testing explicitly.
* If the TestTransients parameter is set to true, transient members will be
* tested, otherwise they are ignored, as they are likely derived fields, and
* not part of the value of the object.
* Static fields will not be tested.
* <p>This method uses reflection to determine if the two Objects are
* equal.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
* a security manger, if the permissions are not set up correctly. It is
* also not as efficient as testing explicitly.</p>
*
* <p>If the <code>testTransients</code> is set to <code>true</code>,
* transient members will be tested, otherwise they are ignored, as they
* are likely derived fields, and not part of the value of the object.</p>
*
* <p>Static fields will not be tested.</p>
*
* @param lhs Left Hand Side
* @param rhs Right Hand Side
* @param testTransients whether to include transient fields
* @return a negative integer, zero, or a positive integer as this
* object is less than, equal to, or greater than the specified object.
* @throws NullPointerException if either (but not both) parameter is null
* @throws ClassCastException if the specified object's type prevents it
* from being compared to this Object.
* Object is less than, equal to, or greater than the specified Object.
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
* @throws ClassCastException if the specified Object's type prevents it
* from being compared to this Object.
*/
public static int reflectionCompare(Object lhs, Object rhs,
boolean testTransients) {
@ -196,17 +209,20 @@ public class CompareToBuilder {
//-------------------------------------------------------------------------
/** Test if two <code>Object</code>s are equal using either the
/**
* <p>Test if two <code>Object</code>s are equal using either the
* <code>compareTo</code> method, or native comparison if the Objects are
* actually arrays.
* <p>
* The objects must be <code>Comparable</code>. If they are not, the method
* will throw a <code>ClassCastException</code>.
* actually arrays.</p>
*
* <p>The objects must be <code>Comparable</code>. If they are not, the
* method will throw a <code>ClassCastException</code>.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws ClassCastException if the specified object's type prevents it
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
* @throws ClassCastException if the specified Object's type prevents it
* from being compared to this Object.
*/
public CompareToBuilder append(Object lhs, Object rhs) {
@ -251,7 +267,8 @@ public class CompareToBuilder {
}
/**
* Test if two <code>long</code>s are <, > or ==.
* <p>Test if two <code>long</code>s are <, > or ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
@ -265,7 +282,8 @@ public class CompareToBuilder {
}
/**
* Test if two <code>int</code>s are <, > or ==.
* <p>Test if two <code>int</code>s are <, > or ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
@ -279,7 +297,7 @@ public class CompareToBuilder {
}
/**
* Test if two <code>short</code>s are <, > or ==.
* <p>Test if two <code>short</code>s are <, > or ==.</p>
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
@ -293,7 +311,8 @@ public class CompareToBuilder {
}
/**
* Test if two <code>char</code>s are <, > or ==.
* <p>Test if two <code>char</code>s are <, > or ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
@ -307,7 +326,7 @@ public class CompareToBuilder {
}
/**
* Test if two <code>byte</code>s are <, > or ==.
* <p>Test if two <code>byte</code>s are <, > or ==.</p>
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
@ -321,9 +340,13 @@ public class CompareToBuilder {
}
/**
* Test if two <code>double</code>s are <, > or ==. This handles NaNs,
* Infinties, and -0.0. It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.
* <p>Test if two <code>double</code>s are <, > or ==.</p>
*
* <p>This handles NaNs, Infinties, and <code>-0.0</code>.</p>
*
* <p>It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
@ -337,9 +360,13 @@ public class CompareToBuilder {
}
/**
* Test if two <code>double</code>s are <, > or ==. This handles NaNs,
* Infinties, and -0.0. It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.
* <p>Test if two <code>double</code>s are <, > or ==.</p>
*
* <p>This handles NaNs, Infinties, and <code>-0.0</code>.</p>
*
* <p>It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
@ -353,7 +380,8 @@ public class CompareToBuilder {
}
/**
* Test if two <code>booleans</code>s are <, > or ==.
* <p>Test if two <code>booleans</code>s are <, > or ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
@ -374,17 +402,22 @@ public class CompareToBuilder {
}
/**
* Performs a deep comparison of two object arrays. This also will be
* called for the top level of multi-dimensional, ragged, and multi-typed
* arrays. If two arrays are of different lengths, and all elements of the
* <p>Performs a deep comparison of two Object arrays.</p>
*
* <p>This also will be called for the top level of multi-dimensional,
* ragged, and multi-typed arrays.</p>
*
* <p>If two arrays are of different lengths, and all elements of the
* shorter array are equal to the elements in the longer array, the longer
* array is the greater. This is dictionary, or lexical, ordering.
* array is the greater. This is dictionary, or lexical, ordering.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws ClassCastException if the specified object's type prevents it
* from being compared to this Object.
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
* @throws ClassCastException if the specified Object's type prevents it
* from being compared to this Object.
*/
public CompareToBuilder append(Object[] lhs, Object[] rhs) {
if (comparison != 0) {
@ -412,12 +445,16 @@ public class CompareToBuilder {
}
/**
* Deep comparison of array of <code>long</code> Length and all values
* are compared. The method append(long, long) is used.
* <p>Deep comparison of array of <code>long</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(long, long)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
*/
public CompareToBuilder append(long[] lhs, long[] rhs) {
if (comparison != 0) {
@ -440,12 +477,16 @@ public class CompareToBuilder {
}
/**
* Deep comparison of array of <code>int</code> Length and all values
* are compared. The method append(int, int) is used.
* <p>Deep comparison of array of <code>int</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(int, int)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
*/
public CompareToBuilder append(int[] lhs, int[] rhs) {
if (comparison != 0) {
@ -468,12 +509,16 @@ public class CompareToBuilder {
}
/**
* Deep comparison of array of <code>short</code> Length and all values
* are compared. The method append(short, short) is used.
* <p>Deep comparison of array of <code>short</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(short, short)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws NullPointerException if either (but not both) parameter is
* <code>null<code>
*/
public CompareToBuilder append(short[] lhs, short[] rhs) {
if (comparison != 0) {
@ -496,12 +541,16 @@ public class CompareToBuilder {
}
/**
* Deep comparison of array of <code>char</code> Length and all values
* are compared. The method append(char, char) is used.
* <p>Deep comparison of array of <code>char</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(char, char)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
*/
public CompareToBuilder append(char[] lhs, char[] rhs) {
if (comparison != 0) {
@ -524,12 +573,16 @@ public class CompareToBuilder {
}
/**
* Deep comparison of array of <code>byte</code> Length and all values
* are compared. The method append(byte, byte) is used.
* <p>Deep comparison of array of <code>byte</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(byte, byte)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
*/
public CompareToBuilder append(byte[] lhs, byte[] rhs) {
if (comparison != 0) {
@ -552,12 +605,16 @@ public class CompareToBuilder {
}
/**
* Deep comparison of array of <code>double</code> Length and all values
* are compared. The method append(double, double) is used.
* <p>Deep comparison of array of <code>double</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(double, double)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
*/
public CompareToBuilder append(double[] lhs, double[] rhs) {
if (comparison != 0) {
@ -580,12 +637,16 @@ public class CompareToBuilder {
}
/**
* Deep comparison of array of <code>float</code> Length and all values
* are compared. The method append(float, float) is used.
* <p>Deep comparison of array of <code>float</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(float, float)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
*/
public CompareToBuilder append(float[] lhs, float[] rhs) {
if (comparison != 0) {
@ -608,12 +669,16 @@ public class CompareToBuilder {
}
/**
* Deep comparison of array of <code>boolean</code> Length and all values
* are compared. The method append(boolean, boolean) is used.
* <p>Deep comparison of array of <code>boolean</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(boolean, boolean)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return CompareToBuilder - used to chain calls.
* @throws NullPointerException if either (but not both) parameter is null
* @throws NullPointerException if either (but not both) parameter is
* <code>null</code>
*/
public CompareToBuilder append(boolean[] lhs, boolean[] rhs) {
if (comparison != 0) {
@ -636,11 +701,12 @@ public class CompareToBuilder {
}
/**
* Return a negative integer if the object is less than, a positive
* integer if the object is greater than, or 0 if the object is equal.
* <p>Return a negative integer if the Object is less than, a positive
* integer if the Object is greater than, or <code>0</code> if the
* Object is equal.
*
* @return int - a negative integer, zero, or a positive integer as this
* object is less than, equal to, or greater than the specified object.
* Object is less than, equal to, or greater than the specified Object.
*/
public int toComparison() {
return comparison;

221
src/java/org/apache/commons/lang/builder/EqualsBuilder.java
View File

@ -56,22 +56,25 @@ package org.apache.commons.lang.builder;
import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
/**
* <code>Equals</code> generation routines.
* <p>
* This class provides methods to build a good equals method for any class.
* It follows rules laid out in Effective Java, by Joshua Bloch. In particular
* the rule for comparing <code>doubles </code>, <code>floats</code>, and
* arrays can be tricky. Also, making sure that <code>equals()</code>
* and <code>hashCode()</code> are consistent can be difficult.
* <p>
* Two object that compare as equals must generate the same hash code. But two
* objects with the same hash code do not have to be equal.
* <p>
* All relevant fields should be included in the calculation of equals. Derived
* fields may be ignored. In particular, any field used in generating a hash
* code must be used in the equals method, and vice versa.
* <p>
* Typical use for the code is as follows:
* <p><code>Equals</code> generation routines.</p>
*
* <p> This class provides methods to build a good equals method for any
* class. It follows rules laid out in
* <a href="http://java.sun.com/docs/books/effective/index.html">Effective Java</a>
* , by Joshua Bloch. In particular the rule for comparing <code>doubles</code>,
* <code>floats</code>, and arrays can be tricky. Also, making sure that
* <code>equals()</code> and <code>hashCode()</code> are consistent can be
* difficult.</p>
*
* <p>Two Object that compare as equals must generate the same hash code.
* But two Objects with the same hash code do not have to be equal.</p>
*
* <p>All relevant fields should be included in the calculation of equals.
* Derived fields may be ignored. In particular, any field used in
* generating a hash code must be used in the equals method, and vice
* versa.</p>
*
* <p>Typical use for the code is as follows:</p>
* <pre>
* public boolean equals(Object o) {
* if ( !(o instanceof MyClass) ) {
@ -85,15 +88,15 @@ import java.lang.reflect.Modifier;
* .isEquals();
* }
* </pre>
* <p>
* Alternatively, there is a method that uses reflection to determine
* the fields to test. Because these fields are usually private, the method,
* <code>reflectionEquals</code>, uses <code>Field.setAccessible</code> to change
* the visibility of the fields. This will fail under a security manager,
* unless the appropriate permissions are set. It is also slower than testing
* explicitly.
* <p>
* A typical invocation for this method would look like:
*
* <p> Alternatively, there is a method that uses reflection to determine
* the fields to test. Because these fields are usually private, the method,
* <code>reflectionEquals</code>, uses <code>Field.setAccessible</code> to
* change the visibility of the fields. This will fail under a security
* manager, unless the appropriate permissions are set up correctly. It is
* also slower than testing explicitly.</p>
*
* <p> A typical invocation for this method would look like:</p>
* <pre>
* public boolean equals(Object o) {
* return EqualsBuilder.reflectionEquals(this, obj);
@ -102,7 +105,7 @@ import java.lang.reflect.Modifier;
*
* @author <a href="mailto:steve.downey@netfolio.com">Steve Downey</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: EqualsBuilder.java,v 1.5 2002/11/01 16:40:41 bayard Exp $
* @version $Id: EqualsBuilder.java,v 1.6 2002/11/17 21:46:42 scolebourne Exp $
*/
public class EqualsBuilder {
/**
@ -111,8 +114,9 @@ public class EqualsBuilder {
private boolean isEquals;
/**
* Constructor for EqualsBuilder.
* Starts off assuming that equals is true.
* <p>Constructor for EqualsBuilder.</p>
*
* <p>Starts off assuming that equals is <code>true</code>.</p>
* @see java.lang.Object#Object()
*/
public EqualsBuilder() {
@ -123,40 +127,44 @@ public class EqualsBuilder {
//-------------------------------------------------------------------------
/**
* This method uses reflection to determine if the two object are equal.
* <p>
* It uses Field.setAccessible to gain access to private fields. This means
* that it will throw a security exception if run under a security manger, if
* the permissions are not set up.
* It is also not as efficient as testing explicitly.
* Transient members will be not be tested, as they are likely derived
* fields, and not part of the value of the object.
* Static fields will not be tested.
* <p>This method uses reflection to determine if the two Object are equal.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
* a security manger, if the permissions are not set up correctly. It is also
* not as efficient as testing explicitly.</p>
*
* <p>Transient members will be not be tested, as they are likely derived
* fields, and not part of the value of the Object.</p>
*
* <p>Static fields will not be tested.</p>
*
* @param lhs Left Hand Side
* @param rhs Right Hand Side
* @return boolean - if the two objects have tested equals.
* @return <code>true</code> if the two Objects have tested equals.
*/
public static boolean reflectionEquals(Object lhs, Object rhs) {
return reflectionEquals(lhs, rhs, false);
}
/**
* This method uses reflection to determine if the two object are equal.
* <p>
* It uses Field.setAccessible to gain access to private fields. This means
* that it will throw a security exception if run under a security manger, if
* the permissions are not set up.
* It is also not as efficient as testing explicitly.
* If the TestTransients parameter is set to true, transient members will be
* tested, otherwise they are ignored, as they are likely derived fields, and
* not part of the value of the object.
* Static fields will not be tested.
* <p>This method uses reflection to determine if the two Object are equal.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
* a security manger, if the permissions are not set up correctly. It is also
* not as efficient as testing explicitly.</p>
*
* <p>If the TestTransients parameter is set to <code>true</code>, transient
* members will be tested, otherwise they are ignored, as they are likely
* derived fields, and not part of the value of the Object.</p>
*
* <p>Static fields will not be tested.</p>
*
* @param lhs Left Hand Side
* @param rhs Right Hand Side
* @param testTransients whether to include transient fields
* @return boolean - if the two objects have tested equals.
* @return <code>true</code> if the two Objects have tested equals.
*/
public static boolean reflectionEquals(Object lhs, Object rhs,
boolean testTransients) {
@ -193,8 +201,9 @@ public class EqualsBuilder {
//-------------------------------------------------------------------------
/**
* Test if two <code>Object</code>s are equal using their <code>equals</code>
* method.
* <p>Test if two <code>Object</code>s are equal using their
* <code>equals</code> method.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -242,7 +251,8 @@ public class EqualsBuilder {
}
/**
* Test if two <code>long</code>s are equal using ==.
* <p>Test if two <code>long</code>s are equal using ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -256,7 +266,8 @@ public class EqualsBuilder {
}
/**
* Test if two <code>int</code>s are equal using ==.
* <p>Test if two <code>int</code>s are equal using ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -270,7 +281,8 @@ public class EqualsBuilder {
}
/**
* Test if two <code>short</code>s are equal using ==.
* <p>Test if two <code>short</code>s are equal using ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -284,7 +296,8 @@ public class EqualsBuilder {
}
/**
* Test if two <code>char</code>s are equal using ==.
* <p>Test if two <code>char</code>s are equal using ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -298,7 +311,8 @@ public class EqualsBuilder {
}
/**
* Test if two <code>byte</code>s are equal using ==.
* <p>Test if two <code>byte</code>s are equal using ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -312,10 +326,14 @@ public class EqualsBuilder {
}
/**
* Test if two <code>double</code>s are equal by testing that the
* pattern of bits returned by doubleToLong are equal. This handles NaNs,
* Infinties, and -0.0. It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.
* <p>Test if two <code>double</code>s are equal by testing that the
* pattern of bits returned by <code>doubleToLong</code> are equal.</p>
*
* <p>This handles NaNs, Infinties, and <code>-0.0</code>.</p>
*
* <p>It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -328,10 +346,14 @@ public class EqualsBuilder {
}
/**
* Test if two <code>float</code>s are equal byt testing that the
* pattern of bits returned by doubleToLong are equal. This handles NaNs,
* Infinties, and -0.0. It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.
* <p>Test if two <code>float</code>s are equal byt testing that the
* pattern of bits returned by doubleToLong are equal.</p>
*
* <p>This handles NaNs, Infinties, and <code>-0.0</code>.</p>
*
* <p>It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -344,7 +366,8 @@ public class EqualsBuilder {
}
/**
* Test if two <code>booleans</code>s are equal using ==.
* <p>Test if two <code>booleans</code>s are equal using ==.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -358,9 +381,11 @@ public class EqualsBuilder {
}
/**
* Performs a deep comparison of two object arrays. This also will be
* called for the top level of multi-dimensional, ragged, and multi-typed
* arrays.
* <p>Performs a deep comparison of two Object arrays.</p>
*
* <p>This also will be called for the top level of
* multi-dimensional, ragged, and multi-typed arrays.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -392,8 +417,11 @@ public class EqualsBuilder {
}
/**
* Deep comparison of array of <code>long</code> Length and all values
* are compared. The method append(long, long) is used.
* <p>Deep comparison of array of <code>long</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(long, long)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -420,8 +448,11 @@ public class EqualsBuilder {
}
/**
* Deep comparison of array of <code>int</code> Length and all values
* are compared. The method append(int, int) is used.
* <p>Deep comparison of array of <code>int</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(int, int)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -448,8 +479,11 @@ public class EqualsBuilder {
}
/**
* Deep comparison of array of <code>short</code> Length and all values
* are compared. The method append(short, short) is used.
* <p>Deep comparison of array of <code>short</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(short, short)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -476,8 +510,11 @@ public class EqualsBuilder {
}
/**
* Deep comparison of array of <code>char</code> Length and all values
* are compared. The method append(char, char) is used.
* <p>Deep comparison of array of <code>char</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(char, char)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -504,8 +541,11 @@ public class EqualsBuilder {
}
/**
* Deep comparison of array of <code>byte</code> Length and all values
* are compared. The method append(byte, byte) is used.
* <p>Deep comparison of array of <code>byte</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(byte, byte)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -532,8 +572,11 @@ public class EqualsBuilder {
}
/**
* Deep comparison of array of <code>double</code> Length and all values
* are compared. The method append(double, double) is used.
* <p>Deep comparison of array of <code>double</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(double, double)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -560,8 +603,11 @@ public class EqualsBuilder {
}
/**
* Deep comparison of array of <code>float</code> Length and all values
* are compared. The method append(float, float) is used.
* <p>Deep comparison of array of <code>float</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(float, float)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -588,8 +634,11 @@ public class EqualsBuilder {
}
/**
* Deep comparison of array of <code>boolean</code> Length and all values
* are compared. The method append(boolean, boolean) is used.
* <p>Deep comparison of array of <code>boolean</code> Length and all values
* are compared.</p>
*
* <p>The method {@link #append(boolean, boolean)} is used.</p>
*
* @param lhs - Left Hand Side
* @param rhs - Right Hand Side
* @return EqualsBuilder - used to chain calls.
@ -616,7 +665,9 @@ public class EqualsBuilder {
}
/**
* Return true if the fields that have been checked are all equal.
* <p>Return <code>true</code> if the fields that have been checked
* are all equal.</p>
*
* @return boolean
*/
public boolean isEquals() {

260
src/java/org/apache/commons/lang/builder/HashCodeBuilder.java
View File

@ -56,18 +56,20 @@ package org.apache.commons.lang.builder;
import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
/**
* <code>HashCode</code> generation routines.
* <p>
* This class enables a good hashcode to be built for any class. It follows
* the rules laid out in the book Effective Java, by Joshua Bloch. Writing a
* good hashCode is actually quite difficult. This class aims to simplify the
* process.
* <p>
* All relevant fields from the object should be included in the hashCode. Derived
* fields may be excluded. In general, any field used in the equals method must be
* used in the hashCode method.
* <p>
* To use this class write code as follows:
* <p><code>HashCode</code> generation routines.</p>
*
* <p> This class enables a good hashcode to be built for any class. It
* follows the rules laid out in the book
* <a href="http://java.sun.com/docs/books/effective/index.html">Effective Java</a>
* , by Joshua Bloch. Writing a good <code>hashCode</code> is actually quite
* difficult. This class aims to simplify the process.</p>
*
* <p> All relevant fields from the object should be included in the
* <code>hashCode</code>. Derived fields may be excluded. In general, any
* field used in the equals method must be used in the <code>hashCode</code>
* method.</p>
*
* <p>To use this class write code as follows:</p>
* <pre>
* public class Person {
* String name;
@ -86,15 +88,15 @@ import java.lang.reflect.Modifier;
* }
* }
* </pre>
* <p>
* Alternatively, there is a method that uses reflection to determine
*
* <p>Alternatively, there is a method that uses reflection to determine
* the fields to test. Because these fields are usually private, the method,
* <code>reflectionHashCode</code>, uses <code>Field.setAccessible</code> to
* change the visibility of the fields. This will fail under a security manager,
* unless the appropriate permissions are set. It is also slower than testing
* explicitly.
* <p>
* A typical invocation for this method would look like:
* unless the appropriate permissions are set up correctly. It is also slower
* than testing explicitly.</p>
*
* <p>A typical invocation for this method would look like:</p>
* <pre>
* public boolean hashCode(Object o) {
* return HashCodeBuilder.reflectionHashCode(this);
@ -102,7 +104,7 @@ import java.lang.reflect.Modifier;
* </pre>
*
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: HashCodeBuilder.java,v 1.4 2002/10/01 20:02:08 stevencaswell Exp $
* @version $Id: HashCodeBuilder.java,v 1.5 2002/11/17 21:46:42 scolebourne Exp $
*/
public class HashCodeBuilder {
@ -116,9 +118,10 @@ public class HashCodeBuilder {
private int iTotal = 0;
/**
* Constructor for HashCodeBuilder.
* This constructor uses two hard coded choices for the constants needed
* to build a hashCode.
* <p>Constructor for HashCodeBuilder.</p>
*
* <p>This constructor uses two hard coded choices for the constants
* needed to build a <code>hashCode</code>.</p>
*/
public HashCodeBuilder() {
super();
@ -127,10 +130,13 @@ public class HashCodeBuilder {
}
/**
* Constructor for HashCodeBuilder.
* Two randomly chosen, non-zero, odd numbers must be passed in. Ideally
* these should be different for each class, however this is not vital.
* Prime numbers are preferred, especially for the multiplier.
* <p>Constructor for <code>HashCodeBuilder</code>.</p>
*
* <p>Two randomly chosen, non-zero, odd numbers must be passed in.
* Ideally these should be different for each class, however this is
* not vital.</p>
*
* <p>Prime numbers are preferred, especially for the multiplier.</p>
*
* @param initialNonZeroOddNumber a non-zero, odd number used as the initial value
* @param multiplierNonZeroOddNumber a non-zero, odd number used as the multiplier
@ -157,69 +163,77 @@ public class HashCodeBuilder {
//-------------------------------------------------------------------------
/**
* This method uses reflection to build a valid hash code.
* <p>
* It uses Field.setAccessible to gain access to private fields. This means
* that it will throw a security exception if run under a security manger, if
* the permissions are not set up.
* It is also not as efficient as testing explicitly.
* Transient members will be not be used, as they are likely derived
* fields, and not part of the value of the object.
* Static fields will not be tested.
* This constructor uses two hard coded choices for the constants needed
* to build a hash code.
*
* @param object the object to create a hash code for
* <p>This method uses reflection to build a valid hash code.</p>
*
* <p>This constructor uses two hard coded choices for the constants
* needed to build a hash code.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
* a security manger, if the permissions are not set up correctly. It is
* also not as efficient as testing explicitly.</p>
*
* <p>Transient members will be not be used, as they are likely derived
* fields, and not part of the value of the Object.</p>
*
* <p>Static fields will not be tested.</p>
*
* @param object the Object to create a <code>hashCode</code> for
* @return int hash code
* @throws IllegalArgumentException if the object is null
* @throws IllegalArgumentException if the object is <code>null</code>
*/
public static int reflectionHashCode(Object object) {
return reflectionHashCode(object, false);
}
/**
* This method uses reflection to build a valid hash code.
* <p>
* It uses Field.setAccessible to gain access to private fields. This means
* that it will throw a security exception if run under a security manger, if
* the permissions are not set up.
* It is also not as efficient as testing explicitly.
* If the TestTransients parameter is set to true, transient members will be
* tested, otherwise they are ignored, as they are likely derived fields, and
* not part of the value of the object.
* Static fields will not be tested.
* This constructor uses two hard coded choices for the constants needed
* to build a hash code.
*
* @param object the object to create a hash code for
* <p>This method uses reflection to build a valid hash code.</p>
*
* <p>This constructor uses two hard coded choices for the constants needed
* to build a hash code.</p>
*
* <p> It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
* a security manger, if the permissions are not set up correctly. It is
* also not as efficient as testing explicitly.</p>
*
* <P>If the TestTransients parameter is set to <code>true</code>, transient
* members will be tested, otherwise they are ignored, as they are likely
* derived fields, and not part of the value of the Object.</p>
*
* <p>Static fields will not be tested.</p>
*
* @param object the Object to create a <code>hashCode</code> for
* @param testTransients whether to include transient fields
* @return int hash code
* @throws IllegalArgumentException if the object is null
* @throws IllegalArgumentException if the object is <code>null</code>
*/
public static int reflectionHashCode(Object object, boolean testTransients) {
return reflectionHashCode(17, 37, object, testTransients);
}
/**
* This method uses reflection to build a valid hash code.
* <p>
* It uses Field.setAccessible to gain access to private fields. This means
* that it will throw a security exception if run under a security manger, if
* the permissions are not set up.
* It is also not as efficient as testing explicitly.
* Transient members will be not be used, as they are likely derived
* fields, and not part of the value of the object.
* Static fields will not be tested.
* <p>
* Two randomly chosen, non-zero, odd numbers must be passed in. Ideally
* <p>This method uses reflection to build a valid hash code.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
* a security manger, if the permissions are not set up correctly. It is
* also not as efficient as testing explicitly.</p>
*
* <p>Transient members will be not be used, as they are likely derived
* fields, and not part of the value of the Object.</p>
*
* <p>Static fields will not be tested.</p>
*
* <p>Two randomly chosen, non-zero, odd numbers must be passed in. Ideally
* these should be different for each class, however this is not vital.
* Prime numbers are preferred, especially for the multiplier.
* Prime numbers are preferred, especially for the multiplier.</p>
*
* @param initialNonZeroOddNumber a non-zero, odd number used as the initial value
* @param multiplierNonZeroOddNumber a non-zero, odd number used as the multiplier
* @param object the object to create a hash code for
* @param object the Object to create a <code>hashCode</code> for
* @return int hash code
* @throws IllegalArgumentException if the object is null
* @throws IllegalArgumentException if the Object is <code>null</code>
* @throws IllegalArgumentException if the number is zero or even
*/
public static int reflectionHashCode(
@ -229,27 +243,29 @@ public class HashCodeBuilder {
}
/**
* This method uses reflection to build a valid hash code.
* <p>
* It uses Field.setAccessible to gain access to private fields. This means
* that it will throw a security exception if run under a security manger, if
* the permissions are not set up.
* It is also not as efficient as testing explicitly.
* If the TestTransients parameter is set to true, transient members will be
* tested, otherwise they are ignored, as they are likely derived fields, and
* not part of the value of the object.
* Static fields will not be tested.
* <p>
* Two randomly chosen, non-zero, odd numbers must be passed in. Ideally
* <p>This method uses reflection to build a valid hash code.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
* a security manger, if the permissions are not set up correctly. It is also
* not as efficient as testing explicitly.</p>
*
* <p>If the TestTransients parameter is set to <code>true</code>, transient
* members will be tested, otherwise they are ignored, as they are likely
* derived fields, and not part of the value of the Object.</p>
*
* <p>Static fields will not be tested.</p>
*
* <p>Two randomly chosen, non-zero, odd numbers must be passed in. Ideally
* these should be different for each class, however this is not vital.
* Prime numbers are preferred, especially for the multiplier.
* Prime numbers are preferred, especially for the multiplier.</p>
*
* @param initialNonZeroOddNumber
* @param multiplierNonZeroOddNumber
* @param object the object to create a hash code for
* @param object the Object to create a <code>hashCode</code> for
* @param testTransients whether to include transient fields
* @return int hash code
* @throws IllegalArgumentException if the object is null
* @throws IllegalArgumentException if the Object is <code>null</code>
* @throws IllegalArgumentException if the number is zero or even
*/
public static int reflectionHashCode(
@ -282,9 +298,9 @@ public class HashCodeBuilder {
//-------------------------------------------------------------------------
/**
* Append a hashCode for an Object.
* <p>Append a <code>hashCode</code> for an <code>Object</code>.</p>
*
* @param object the object to add to the hashCode
* @param object the Object to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(Object object) {
@ -325,9 +341,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a long.
* <p>Append a <code>hashCode</code> for a <code>long</code>.</p>
*
* @param value the long to add to the hashCode
* @param value the long to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(long value) {
@ -336,9 +352,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for an int.
* <p>Append a <code>hashCode</code> for an <code>int</code>.</p>
*
* @param value the int to add to the hashCode
* @param value the int to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(int value) {
@ -347,9 +363,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a short.
* <p>Append a <code>hashCode</code> for a <code>short</code>.</p>
*
* @param value the short to add to the hashCode
* @param value the short to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(short value) {
@ -358,9 +374,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a char.
* <p>Append a <code>hashCode</code> for a <code>char</code>.</p>
*
* @param value the char to add to the hashCode
* @param value the char to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(char value) {
@ -369,9 +385,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a byte.
* <p>Append a <code>hashCode</code> for a <code>byte</code>.</p>
*
* @param value the byte to add to the hashCode
* @param value the byte to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(byte value) {
@ -380,9 +396,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a double.
* <p>Append a <code>hashCode</code> for a <code>double</code>.</p>
*
* @param value the double to add to the hashCode
* @param value the double to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(double value) {
@ -390,9 +406,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a float.
* <p>Append a <code>hashCode</code> for a <code>float</code>.</p>
*
* @param value the float to add to the hashCode
* @param value the float to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(float value) {
@ -401,9 +417,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a long.
* <p>Append a <code>hashCode</code> for a <code>long</code>.</p>
*
* @param value the long to add to the hashCode
* @param value the long to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(boolean value) {
@ -412,9 +428,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for an Object array.
* <p>Append a <code>hashCode</code> for an <code>Object</code> array.</p>
*
* @param array the array to add to the hashCode
* @param array the array to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(Object[] array) {
@ -429,9 +445,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a long array.
* <p>Append a <code>hashCode</code> for a <code>long</code> array.</p>
*
* @param array the array to add to the hashCode
* @param array the array to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(long[] array) {
@ -446,9 +462,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for an int array.
* <p>Append a <code>hashCode</code> for an <code>int</code> array.</p>
*
* @param array the array to add to the hashCode
* @param array the array to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(int[] array) {
@ -463,9 +479,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a short array.
* <p>Append a <code>hashCode</code> for a <code>short</code> array.</p>
*
* @param array the array to add to the hashCode
* @param array the array to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(short[] array) {
@ -480,9 +496,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a char array.
* <p>Append a <code>hashCode</code> for a <code>char</code> array.</p>
*
* @param array the array to add to the hashCode
* @param array the array to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(char[] array) {
@ -497,9 +513,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a byte array.
* <p>Append a <code>hashCode</code> for a <code>byte</code> array.</p>
*
* @param array the array to add to the hashCode
* @param array the array to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(byte[] array) {
@ -514,9 +530,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a double array.
* <p>Append a <code>hashCode</code> for a <code>double</code> array.</p>
*
* @param array the array to add to the hashCode
* @param array the array to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(double[] array) {
@ -531,9 +547,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a float array.
* <p>Append a <code>hashCode</code> for a <code>float</code> array.</p>
*
* @param array the array to add to the hashCode
* @param array the array to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(float[] array) {
@ -548,9 +564,9 @@ public class HashCodeBuilder {
}
/**
* Append a hashCode for a boolean array.
* <p>Append a <code>hashCode</code> for a <code>boolean</code> array.</p>
*
* @param array the array to add to the hashCode
* @param array the array to add to the <code>hashCode</code>
* @return this
*/
public HashCodeBuilder append(boolean[] array) {
@ -565,9 +581,9 @@ public class HashCodeBuilder {
}
/**
* Return the computed hashCode
* <p>Return the computed <code>hashCode</code>.</p>
*
* @return int hashCode based on the fields appended
* @return <code>hashCode</code> based on the fields appended
*/
public int toHashCode() {
return iTotal;

210
src/java/org/apache/commons/lang/builder/StandardToStringStyle.java
View File

@ -54,21 +54,22 @@
package org.apache.commons.lang.builder;
/**
* <code>StandardToStringStyle</code> works with ToStringBuilder to create a
* toString.
* <p>
* This class is intended to be used as a singleton. There is no need
* to instantiate a new style each time. Your code should instantiate the class
* once, customize the values as required, and then store the result in a
* public static final variable for the rest of the program to access.
* <p><code>StandardToStringStyle</code> works with {@link ToStringBuilder}
* to create a <code>toString</code>.</p>
*
* <p>This class is intended to be used as a <code>Singleton</code>. There
* is no need * to instantiate a new style each time. Your code should
* instantiate the class once, customize the values as required, and then
* store the result in a public static final variable for the rest of the
* program to access.</p>
*
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: StandardToStringStyle.java,v 1.4 2002/09/22 09:18:32 scolebourne Exp $
* @version $Id: StandardToStringStyle.java,v 1.5 2002/11/17 21:46:42 scolebourne Exp $
*/
public class StandardToStringStyle extends ToStringStyle {
/**
* Constructor.
* <p>Constructor.</p>
*/
public StandardToStringStyle() {
super();
@ -77,7 +78,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets whether to use the class name.
* <p>Gets whether to use the class name.</p>
*
* @return the current useClassName flag
*/
public boolean isUseClassName() {
@ -85,7 +87,8 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets whether to use the class name.
* <p>Sets whether to use the class name.</p>
*
* @param useClassName the new useClassName flag
*/
public void setUseClassName(boolean useClassName) {
@ -95,7 +98,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets whether to output short or long class names.
* <p>Gets whether to output short or long class names.</p>
*
* @return the current shortClassName flag
*/
public boolean isShortClassName() {
@ -103,7 +107,8 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets whether to output short or long class names.
* <p>Sets whether to output short or long class names.</p>
*
* @param shortClassName the new shortClassName flag
*/
public void setShortClassName(boolean shortClassName) {
@ -113,7 +118,7 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets whether to use the identity hash code.
* <p>Gets whether to use the identity hash code.</p>
* @return the current useIdentityHashCode flag
*/
public boolean isUseIdentityHashCode() {
@ -121,7 +126,8 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets whether to use the identity hash code.
* <p>Sets whether to use the identity hash code.</p>
*
* @param useIdentityHashCode the new useIdentityHashCode flag
*/
public void setUseIdentityHashCode(boolean useIdentityHashCode) {
@ -131,7 +137,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets whether to use the field names passed in.
* <p>Gets whether to use the field names passed in.</p>
*
* @return the current useFieldNames flag
*/
public boolean isUseFieldNames() {
@ -139,7 +146,8 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets whether to use the field names passed in.
* <p>Sets whether to use the field names passed in.</p>
*
* @param useFieldNames the new useFieldNames flag
*/
public void setUseFieldNames(boolean useFieldNames) {
@ -149,7 +157,9 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets whether to use full detail when the caller doesn't specify.
* <p>Gets whether to use full detail when the caller doesn't
* specify.</p>
*
* @return the current defaultFullDetail flag
*/
public boolean isDefaultFullDetail() {
@ -157,7 +167,9 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets whether to use full detail when the caller doesn't specify.
* <p>Sets whether to use full detail when the caller doesn't
* specify.</p>
*
* @param defaultFullDetail the new defaultFullDetail flag
*/
public void setDefaultFullDetail(boolean defaultFullDetail) {
@ -167,7 +179,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets whether to output array content detail.
* <p>Gets whether to output array content detail.</p>
*
* @return the current array content detail setting
*/
public boolean isArrayContentDetail() {
@ -175,7 +188,8 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets whether to output array content detail.
* <p>Sets whether to output array content detail.</p>
*
* @param arrayContentDetail the new arrayContentDetail flag
*/
public void setArrayContentDetail(boolean arrayContentDetail) {
@ -185,7 +199,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the array start text.
* <p>Gets the array start text.</p>
*
* @return the current array start text
*/
public String getArrayStart() {
@ -193,8 +208,11 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the array start text.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the array start text.</p>
*
* <p><code>Null</code> is accepted, but will be converted
* to a empry String.</p>
*
* @param arrayStart the new array start text
*/
public void setArrayStart(String arrayStart) {
@ -204,7 +222,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the array end text.
* <p>Gets the array end text.</p>
*
* @return the current array end text
*/
public String getArrayEnd() {
@ -212,8 +231,11 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the array end text.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the array end text.</p>
*
* <p><code>Null</code> is accepted, but will be converted
* to a empty String.</p>
*
* @param arrayEnd the new array end text
*/
public void setArrayEnd(String arrayEnd) {
@ -223,7 +245,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the array separator text.
* <p>Gets the array separator text.</p>
*
* @return the current array separator text
*/
public String getArraySeparator() {
@ -231,8 +254,11 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the array separator text.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the array separator text.</p>
*
* <p><code>Null</code> is accepted, but will be converted
* to a empty String.</p>
*
* @param arraySeparator the new array separator text
*/
public void setArraySeparator(String arraySeparator) {
@ -242,7 +268,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the content start text.
* <p>Gets the content start text.</p>
*
* @return the current content start text
*/
public String getContentStart() {
@ -250,8 +277,11 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the content start text.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the content start text.</p>
*
* <p><code>Null</code> is accepted, but will be converted
* to a empty String.</p>
*
* @param contentStart the new content start text
*/
public void setContentStart(String contentStart) {
@ -261,7 +291,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the content end text.
* <p>Gets the content end text.</p>
*
* @return the current content end text
*/
public String getContentEnd() {
@ -269,8 +300,11 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the content end text.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the content end text.</p>
*
* <p><code>Null</code> is accepted, but will be converted
* to a empty String.</p>
*
* @param contentEnd the new content end text
*/
public void setContentEnd(String contentEnd) {
@ -280,7 +314,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the field name value separator text.
* <p>Gets the field name value separator text.</p>
*
* @return the current field name value separator text
*/
public String getFieldNameValueSeparator() {
@ -288,8 +323,11 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the field name value separator text.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the field name value separator text.</p>
*
* <p><code>Null</code> is accepted, but will be converted
* to a empty String.</p>
*
* @param fieldNameValueSeparator the new field name value separator text
*/
public void setFieldNameValueSeparator(String fieldNameValueSeparator) {
@ -299,7 +337,8 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the field separator text.
* <p>Gets the field separator text.</p>
*
* @return the current field separator text
*/
public String getFieldSeparator() {
@ -307,8 +346,11 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the field separator text.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the field separator text.</p>
*
* <p><code>Null</code> is accepted, but will be converted
* to a empty String.</p>
*
* @param fieldSeparator the new field separator text
*/
public void setFieldSeparator(String fieldSeparator) {
@ -318,16 +360,20 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the text to output when null found.
* @return the current text to output when null found
* <p>Gets the text to output when <code>null</code> found.</p>
*
* @return the current text to output when <code>null</code> found
*/
public String getNullText() {
return super.getNullText();
}
/**
* Sets the text to output when null found.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the text to output when <code>null</code> found.</p>
*
* <p><code>Null</code> is accepted, but will be converted
* to a empty String.</p>
*
* @param nullText the new text to output when null found
*/
public void setNullText(String nullText) {
@ -337,8 +383,11 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the text to output when a Collection, Map or Array size is output.
* This is output before the size value.
* <p>Gets the text to output when a <code>Collection</code>,
* <code>Map</code> or <code>Array</code> size is output.</p>
*
* <p>This is output before the size value.</p>
*
* @return the current start of size text
*/
public String getSizeStartText() {
@ -346,9 +395,14 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the text to output when a Collection, Map or Array size is output.
* This is output before the size value.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the text to output when a <code>Collection</code>,
* <code>Map</code> or <code>Array</code> size is output.</p>
*
* <p>This is output before the size value.</p>
*
* <p><code>Null</code> is accepted, but will be converted to
* a empty String.</p>
*
* @param sizeStartText the new start of size text
*/
public void setSizeStartText(String sizeStartText) {
@ -358,8 +412,11 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the text to output when a Collection, Map or Array size is output.
* This is output after the size value.
* Gets the text to output when a <code>Collection</code>,
* <code>Map</code> or <code>Array</code> size is output.</p>
*
* <p>This is output after the size value.</p>
*
* @return the current end of size text
*/
public String getSizeEndText() {
@ -367,9 +424,14 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the text to output when a Collection, Map or Array size is output.
* This is output after the size value.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the text to output when a <code>Collection</code>,
* <code>Map</code> or <code>Array</code> size is output.</p>
*
* <p>This is output after the size value.</p>
*
* <p><code>Null</code> is accepted, but will be converted
* to a Empty String.</p>
*
* @param sizeEndText the new end of size text
*/
public void setSizeEndText(String sizeEndText) {
@ -379,8 +441,11 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the text to output when an Object is output in summary mode.
* This is output before the size value.
* <p>Gets the text to output when an <code>Object</code> is
* output in summary mode.</p>
*
* <P>This is output before the size value.</p>
*
* @return the current start of summary text
*/
public String getSummaryObjectStartText() {
@ -388,9 +453,14 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the text to output when an Object is output in summary mode.
* This is output before the size value.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the text to output when an <code>Object</code> is
* output in summary mode.</p>
*
* <p>This is output before the size value.</p>
*
* <p><code>Null</code> is accepted, but will be converted to
* a empty String.</p>
*
* @param summaryObjectStartText the new start of summary text
*/
public void setSummaryObjectStartText(String summaryObjectStartText) {
@ -400,8 +470,11 @@ public class StandardToStringStyle extends ToStringStyle {
//---------------------------------------------------------------------
/**
* Gets the text to output when an Object is output in summary mode.
* This is output after the size value.
* <p>Gets the text to output when an <code>Object</code> is
* output in summary mode.</p>
*
* <p>This is output after the size value.</p>
*
* @return the current end of summary text
*/
public String getSummaryObjectEndText() {
@ -409,9 +482,14 @@ public class StandardToStringStyle extends ToStringStyle {
}
/**
* Sets the text to output when an Object is output in summary mode.
* This is output after the size value.
* Null is accepted, but will be converted to a blank string.
* <p>Sets the text to output when an <code>Object</code> is
* output in summary mode.</p>
*
* <p>This is output after the size value.</p>
*
* <p><code>Null</code> is accepted, but will be converted to
* a empty String.</p>
*
* @param summaryObjectEndText the new end of summary text
*/
public void setSummaryObjectEndText(String summaryObjectEndText) {

557
src/java/org/apache/commons/lang/builder/ToStringBuilder.java
View File

File diff suppressed because it is too large Load Diff

811
src/java/org/apache/commons/lang/builder/ToStringStyle.java
View File

File diff suppressed because it is too large Load Diff