Author: bayard
Date: Sat Mar 20 20:20:26 2010
New Revision: 925674
URL: http://svn.apache.org/viewvc?rev=925674&view=rev
Log:
Adding Builder interface, and refactoring the builder classes and
BasicThreadFactory to implement this interface. Patch from Michael Wooten in
LANG-601
Added:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/Builder.java
(with props)
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/CompareToBuilder.java
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ToStringBuilder.java
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/concurrent/BasicThreadFactory.java
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/CompareToBuilderTest.java
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/EqualsBuilderTest.java
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/HashCodeBuilderTest.java
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/ToStringBuilderTest.java
Added:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/Builder.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/Builder.java?rev=925674&view=auto
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/Builder.java
(added)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/Builder.java
Sat Mar 20 20:20:26 2010
@@ -0,0 +1,89 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.builder;
+
+/**
+ * <p>
+ * The Builder interface is designed to designate a class as a
<em>builder</em>
+ * object in the Builder design pattern. Builders are capable of creating and
+ * configuring objects or results that normally take multiple steps to
construct
+ * or are very complex to derive.
+ * </p>
+ *
+ * <p>
+ * The builder interface defines a single method, {...@link #build()}, that
+ * classes must implement. The result of this method should be the final
+ * configured object or result after all building operations are performed.
+ * </p>
+ *
+ * <p>
+ * It is a recommended practice that the methods supplied to configure the
+ * object or result being built return a reference to <code>this</code> so that
+ * method calls can be chained together.
+ * </p>
+ *
+ * <p>
+ * Example Builder:
+ * <code><pre>
+ * class FontBuilder implements Builder<Font> {
+ * private Font font;
+ *
+ * public FontBuilder(String fontName) {
+ * this.font = new Font(fontName, Font.PLAIN, 12);
+ * }
+ *
+ * public FontBuilder bold() {
+ * this.font = this.font.deriveFont(Font.BOLD);
+ * return this; // Reference returned so calls can be chained
+ * }
+ *
+ * public FontBuilder size(float pointSize) {
+ * this.font = this.font.deriveFont(pointSize);
+ * return this; // Reference returned so calls can be chained
+ * }
+ *
+ * // Other Font construction methods
+ *
+ * public Font build() {
+ * return this.font;
+ * }
+ * }
+ * </pre></code>
+ *
+ * Example Builder Usage:
+ * <code><pre>
+ * Font bold14ptSansSerifFont = new FontBuilder(Font.SANS_SERIF).bold()
+ * .size(14.0f)
+ * .build();
+ * </pre></code>
+ * </p>
+ *
+ * @param <T> the type of object that the builder will construct or compute.
+ *
+ * @author <a href="mailto:[email protected]";>Michael Wooten</a>
+ * @since 3.0
+ */
+public interface Builder<T> {
+
+ /**
+ * Returns a reference to the object being constructed or result being
+ * calculated by the builder.
+ *
+ * @return the object constructed or result calculated by the builder.
+ */
+ public T build();
+}
Propchange:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/Builder.java
------------------------------------------------------------------------------
svn:eol-style = native
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/CompareToBuilder.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/CompareToBuilder.java?rev=925674&r1=925673&r2=925674&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/CompareToBuilder.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/CompareToBuilder.java
Sat Mar 20 20:20:26 2010
@@ -89,7 +89,7 @@ import org.apache.commons.lang3.ArrayUti
* @since 1.0
* @version $Id$
*/
-public class CompareToBuilder {
+public class CompareToBuilder implements Builder<Integer> {
/**
* Current state of the comparison as appended fields are checked.
@@ -1043,5 +1043,18 @@ public class CompareToBuilder {
return comparison;
}
+ /**
+ * Returns a negative integer, a positive integer, or zero as
+ * the <code>builder</code> has judged the "left-hand" side
+ * as less than, greater than, or equal to the "right-hand"
+ * side.
+ *
+ * @return final comparison result
+ *
+ * @since 3.0
+ */
+ public Integer build() {
+ return toComparison();
+ }
}
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java?rev=925674&r1=925673&r2=925674&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java
Sat Mar 20 20:20:26 2010
@@ -86,7 +86,7 @@ import org.apache.commons.lang3.Pair;
* @since 1.0
* @version $Id$
*/
-public class EqualsBuilder {
+public class EqualsBuilder implements Builder<Boolean> {
/**
* <p>
@@ -968,6 +968,19 @@ public class EqualsBuilder {
public boolean isEquals() {
return this.isEquals;
}
+
+ /**
+ * <p>Returns <code>true</code> if the fields that have been checked
+ * are all equal.</p>
+ *
+ * @return <code>true</code> if all of the fields that have been checked
+ * are equal, <code>false</code> otherwise.
+ *
+ * @since 3.0
+ */
+ public Boolean build() {
+ return isEquals();
+ }
/**
* Sets the <code>isEquals</code> value.
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java?rev=925674&r1=925673&r2=925674&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java
Sat Mar 20 20:20:26 2010
@@ -93,7 +93,7 @@ import org.apache.commons.lang3.ArrayUti
* @since 1.0
* @version $Id$
*/
-public class HashCodeBuilder {
+public class HashCodeBuilder implements Builder<Integer> {
/**
* <p>
* A registry of objects used by reflection methods to detect cyclical
object references and avoid infinite loops.
@@ -976,6 +976,17 @@ public class HashCodeBuilder {
public int toHashCode() {
return iTotal;
}
+
+ /**
+ * Returns the computed <code>hashCode</code>.
+ *
+ * @return <code>hashCode</code> based on the fields appended
+ *
+ * @since 3.0
+ */
+ public Integer build() {
+ return toHashCode();
+ }
/**
* <p>
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ToStringBuilder.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ToStringBuilder.java?rev=925674&r1=925673&r2=925674&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ToStringBuilder.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ToStringBuilder.java
Sat Mar 20 20:20:26 2010
@@ -89,7 +89,7 @@ import org.apache.commons.lang3.ObjectUt
* @since 1.0
* @version $Id$
*/
-public class ToStringBuilder {
+public class ToStringBuilder implements Builder<String> {
/**
* The default style of output to use, not null.
@@ -1065,4 +1065,17 @@ public class ToStringBuilder {
return this.getStringBuffer().toString();
}
+ /**
+ * Returns the String that was build as an object representation. The
+ * default implementation utilizes the {...@link #toString()}
implementation.
+ *
+ * @return the String <code>toString</code>
+ *
+ * @see #toString()
+ *
+ * @since 3.0
+ */
+ public String build() {
+ return toString();
+ }
}
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/concurrent/BasicThreadFactory.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/concurrent/BasicThreadFactory.java?rev=925674&r1=925673&r2=925674&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/concurrent/BasicThreadFactory.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/concurrent/BasicThreadFactory.java
Sat Mar 20 20:20:26 2010
@@ -250,7 +250,9 @@ public class BasicThreadFactory implemen
*
* @version $Id: $
*/
- public static class Builder {
+ public static class Builder
+ implements
org.apache.commons.lang3.builder.Builder<BasicThreadFactory> {
+
/** The wrapped factory. */
private ThreadFactory wrappedFactory;
Modified:
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/CompareToBuilderTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/CompareToBuilderTest.java?rev=925674&r1=925673&r2=925674&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/CompareToBuilderTest.java
(original)
+++
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/CompareToBuilderTest.java
Sat Mar 20 20:20:26 2010
@@ -272,6 +272,20 @@ public class CompareToBuilderTest extend
assertTrue(new CompareToBuilder().append((Object) null, (Object)
null).toComparison() == 0);
assertTrue(new CompareToBuilder().append(null, o1).toComparison() < 0);
}
+
+ public void testObjectBuild() {
+ TestObject o1 = new TestObject(4);
+ TestObject o2 = new TestObject(4);
+ assertTrue(new CompareToBuilder().append(o1, o1).build() == 0);
+ assertTrue(new CompareToBuilder().append(o1, o2).build() == 0);
+ o2.setA(5);
+ assertTrue(new CompareToBuilder().append(o1, o2).build() < 0);
+ assertTrue(new CompareToBuilder().append(o2, o1).build() > 0);
+
+ assertTrue(new CompareToBuilder().append(o1, null).build() > 0);
+ assertTrue(new CompareToBuilder().append((Object) null, (Object)
null).build() == 0);
+ assertTrue(new CompareToBuilder().append(null, o1).build() < 0);
+ }
public void testObjectEx2() {
TestObject o1 = new TestObject(4);
Modified:
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/EqualsBuilderTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/EqualsBuilderTest.java?rev=925674&r1=925673&r2=925674&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/EqualsBuilderTest.java
(original)
+++
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/EqualsBuilderTest.java
Sat Mar 20 20:20:26 2010
@@ -305,6 +305,21 @@ public class EqualsBuilderTest extends T
assertTrue(!new EqualsBuilder().append(null, o2).isEquals());
assertTrue(new EqualsBuilder().append((Object) null, (Object)
null).isEquals());
}
+
+ public void testObjectBuild() {
+ TestObject o1 = new TestObject(4);
+ TestObject o2 = new TestObject(5);
+ assertTrue(new EqualsBuilder().append(o1, o1).build());
+ assertTrue(!new EqualsBuilder().append(o1, o2).build());
+ o2.setA(4);
+ assertTrue(new EqualsBuilder().append(o1, o2).build());
+
+ assertTrue(!new EqualsBuilder().append(o1, this).build());
+
+ assertTrue(!new EqualsBuilder().append(o1, null).build());
+ assertTrue(!new EqualsBuilder().append(null, o2).build());
+ assertTrue(new EqualsBuilder().append((Object) null, (Object)
null).build());
+ }
public void testLong() {
long o1 = 1L;
Modified:
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/HashCodeBuilderTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/HashCodeBuilderTest.java?rev=925674&r1=925673&r2=925674&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/HashCodeBuilderTest.java
(original)
+++
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/HashCodeBuilderTest.java
Sat Mar 20 20:20:26 2010
@@ -205,6 +205,13 @@ public class HashCodeBuilderTest extends
obj = new Object();
assertEquals(17 * 37 + obj.hashCode(), new HashCodeBuilder(17,
37).append(obj).toHashCode());
}
+
+ public void testObjectBuild() {
+ Object obj = null;
+ assertEquals(17 * 37, new HashCodeBuilder(17,
37).append(obj).build().intValue());
+ obj = new Object();
+ assertEquals(17 * 37 + obj.hashCode(), new HashCodeBuilder(17,
37).append(obj).build().intValue());
+ }
@SuppressWarnings("cast") // cast is not really needed, keep for
consistency
public void testLong() {
Modified:
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/ToStringBuilderTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/ToStringBuilderTest.java?rev=925674&r1=925673&r2=925674&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/ToStringBuilderTest.java
(original)
+++
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/builder/ToStringBuilderTest.java
Sat Mar 20 20:20:26 2010
@@ -619,6 +619,23 @@ public class ToStringBuilderTest extends
assertEquals(baseStr + "[a=<size=0>]", new
ToStringBuilder(base).append("a", (Object) new String[0], false).toString());
assertEquals(baseStr + "[a={}]", new ToStringBuilder(base).append("a",
(Object) new String[0], true).toString());
}
+
+ public void testObjectBuild() {
+ Integer i3 = new Integer(3);
+ Integer i4 = new Integer(4);
+ assertEquals(baseStr + "[<null>]", new
ToStringBuilder(base).append((Object) null).build());
+ assertEquals(baseStr + "[3]", new
ToStringBuilder(base).append(i3).build());
+ assertEquals(baseStr + "[a=<null>]", new
ToStringBuilder(base).append("a", (Object) null).build());
+ assertEquals(baseStr + "[a=3]", new ToStringBuilder(base).append("a",
i3).build());
+ assertEquals(baseStr + "[a=3,b=4]", new
ToStringBuilder(base).append("a", i3).append("b", i4).build());
+ assertEquals(baseStr + "[a=<Integer>]", new
ToStringBuilder(base).append("a", i3, false).build());
+ assertEquals(baseStr + "[a=<size=0>]", new
ToStringBuilder(base).append("a", new ArrayList<Object>(), false).build());
+ assertEquals(baseStr + "[a=[]]", new ToStringBuilder(base).append("a",
new ArrayList<Object>(), true).build());
+ assertEquals(baseStr + "[a=<size=0>]", new
ToStringBuilder(base).append("a", new HashMap<Object, Object>(),
false).build());
+ assertEquals(baseStr + "[a={}]", new ToStringBuilder(base).append("a",
new HashMap<Object, Object>(), true).build());
+ assertEquals(baseStr + "[a=<size=0>]", new
ToStringBuilder(base).append("a", (Object) new String[0], false).build());
+ assertEquals(baseStr + "[a={}]", new ToStringBuilder(base).append("a",
(Object) new String[0], true).build());
+ }
public void testLong() {
assertEquals(baseStr + "[3]", new
ToStringBuilder(base).append(3L).toString());
