This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-text.git
The following commit(s) were added to refs/heads/master by this push:
new 78b50843 Deprecate Builder in favor of Supplier
78b50843 is described below
commit 78b50843d700cad94ca41210b09be20d6941bae4
Author: Gary Gregory <[email protected]>
AuthorDate: Sun Apr 7 09:02:31 2024 -0400
Deprecate Builder in favor of Supplier
Javadoc improvements
---
src/changes/changes.xml | 1 +
src/main/java/org/apache/commons/text/Builder.java | 53 +++++++++++++---------
.../apache/commons/text/RandomStringGenerator.java | 21 +++++++--
.../java/org/apache/commons/text/StrBuilder.java | 18 +++++++-
.../org/apache/commons/text/TextStringBuilder.java | 18 +++++++-
.../commons/text/lookup/StringLookupFactory.java | 20 ++++----
.../apache/commons/text/TextStringBuilderTest.java | 6 +++
7 files changed, 97 insertions(+), 40 deletions(-)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 724f5098..e284df29 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -54,6 +54,7 @@ The <action> type attribute can be add,update,fix,remove.
<!-- FIX -->
<action issue="TEXT-232" type="fix" dev="ggregory" due-to="Arnout Engelen,
Gary Gregory">WordUtils.containsAllWords​() may throw
PatternSyntaxException.</action>
<action issue="TEXT-175" type="fix" dev="ggregory" due-to="David Lavati,
seanfabs, Gary Gregory, Bruno P. Kinoshita">Fix regression for determining
whitespace in WordUtils #519.</action>
+ <action type="fix" dev="ggregory" due-to="Gary
Gregory">Deprecate Builder in favor of Supplier.</action>
<!-- UPDATE -->
<action type="update" dev="ggregory" due-to="Gary
Gregory">Bump commons-lang3 from 3.13.0 to 3.14.0.</action>
<action type="update" dev="ggregory"
due-to="Dependabot">Bump commons.bytebuddy.version from 1.14.9 to 1.14.13 #476,
#482, #505, #521.</action>
diff --git a/src/main/java/org/apache/commons/text/Builder.java
b/src/main/java/org/apache/commons/text/Builder.java
index ca4c2d34..4007fe60 100644
--- a/src/main/java/org/apache/commons/text/Builder.java
+++ b/src/main/java/org/apache/commons/text/Builder.java
@@ -16,28 +16,29 @@
*/
package org.apache.commons.text;
+import java.util.function.Supplier;
+
/**
- * 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.
- *
+ * Duplicates the functionality of {@link Supplier}.
* <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.
+ * Defines a class as a <em>builder</em> following 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 #get()}, 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} so that
- * method calls can be chained together.
+ * It is a recommended practice that the methods supplied to configure the
object or result being built return a reference to {@code this} so that method
calls
+ * can be chained together.
* </p>
*
* <p>
* Example Builder:
* </p>
- * <pre><code>
+ *
+ * <pre>
+ * <code>
* class FontBuilder implements Builder<Font> {
* private Font font;
*
@@ -61,26 +62,34 @@ package org.apache.commons.text;
* return this.font;
* }
* }
- * </code></pre>
+ * </code>
+ * </pre>
*
* Example Builder Usage:
- * <pre><code>
- * Font bold14ptSansSerifFont = new FontBuilder(Font.SANS_SERIF).bold()
- * .size(14.0f)
- * .build();
- * </code></pre>
+ *
+ * <pre>
+ * <code>
+ * Font bold14ptSansSerifFont = new FontBuilder(Font.SANS_SERIF)
+ * .bold()
+ * .size(14.0f)
+ * .get();
+ * </code>
+ * </pre>
*
*
* @param <T> the type of object that the builder will construct or compute.
* @since 1.0
+ * @see Supplier
+ * @deprecated Use :@link Supplier}.
*/
-public interface Builder<T> {
+@Deprecated
+public interface Builder<T> extends Supplier<T> {
/**
- * Returns a reference to the object being constructed or result being
- * calculated by the builder.
+ * 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.
*/
T build();
+
}
diff --git a/src/main/java/org/apache/commons/text/RandomStringGenerator.java
b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
index c1cf9a12..aa3f43c7 100644
--- a/src/main/java/org/apache/commons/text/RandomStringGenerator.java
+++ b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
@@ -126,14 +126,15 @@ public final class RandomStringGenerator {
private List<Character> characterList;
/**
- * Builds the {@code RandomStringGenerator} using the properties
specified.
+ * Builds a new {@code RandomStringGenerator}.
*
- * @return The configured {@code RandomStringGenerator}
+ * @return A new {@code RandomStringGenerator}
+ * @deprecated Use {@link #get()}.
*/
+ @Deprecated
@Override
public RandomStringGenerator build() {
- return new RandomStringGenerator(minimumCodePoint,
maximumCodePoint, inclusivePredicates,
- random, characterList);
+ return get();
}
/**
@@ -164,6 +165,18 @@ public final class RandomStringGenerator {
return this;
}
+ /**
+ * Builds a new {@code RandomStringGenerator}.
+ *
+ * @return A new {@code RandomStringGenerator}
+ * @since 1.12.0
+ */
+ @Override
+ public RandomStringGenerator get() {
+ return new RandomStringGenerator(minimumCodePoint,
maximumCodePoint, inclusivePredicates,
+ random, characterList);
+ }
+
/**
* Limits the characters in the generated string to those who match at
* supplied list of Character.
diff --git a/src/main/java/org/apache/commons/text/StrBuilder.java
b/src/main/java/org/apache/commons/text/StrBuilder.java
index 27249954..c84c5f2c 100644
--- a/src/main/java/org/apache/commons/text/StrBuilder.java
+++ b/src/main/java/org/apache/commons/text/StrBuilder.java
@@ -1510,11 +1510,13 @@ public class StrBuilder implements CharSequence,
Appendable, Serializable, Build
}
/**
- * Builds a string.
+ * Converts this instance to a String.
*
- * @return The builder as a String
+ * @return This instance as a String
* @see #toString()
+ * @deprecated Use {@link #get()}.
*/
+ @Deprecated
@Override
public String build() {
return toString();
@@ -1868,6 +1870,18 @@ public class StrBuilder implements CharSequence,
Appendable, Serializable, Build
return true;
}
+ /**
+ * Converts this instance to a String.
+ *
+ * @return This instance as a String
+ * @see #toString()
+ * @since 1.12.0
+ */
+ @Override
+ public String get() {
+ return toString();
+ }
+
/**
* Copies the character array into the specified array.
*
diff --git a/src/main/java/org/apache/commons/text/TextStringBuilder.java
b/src/main/java/org/apache/commons/text/TextStringBuilder.java
index 7b978707..ca48a293 100644
--- a/src/main/java/org/apache/commons/text/TextStringBuilder.java
+++ b/src/main/java/org/apache/commons/text/TextStringBuilder.java
@@ -1548,11 +1548,13 @@ public class TextStringBuilder implements CharSequence,
Appendable, Serializable
}
/**
- * Implement the {@link Builder} interface.
+ * Converts this instance to a String.
*
- * @return The builder as a String
+ * @return This instance as a String
* @see #toString()
+ * @deprecated Use {@link #get()}.
*/
+ @Deprecated
@Override
public String build() {
return toString();
@@ -1961,6 +1963,18 @@ public class TextStringBuilder implements CharSequence,
Appendable, Serializable
return true;
}
+ /**
+ * Converts this instance to a String.
+ *
+ * @return This instance as a String
+ * @see #toString()
+ * @since 1.12.0
+ */
+ @Override
+ public String get() {
+ return toString();
+ }
+
/** Gets a direct reference to internal storage, not for public
consumption. */
char[] getBuffer() {
return buffer;
diff --git
a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
index 3c4015a6..c4a2d98a 100644
--- a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
+++ b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
@@ -250,16 +250,6 @@ public final class StringLookupFactory {
}
- /**
- * Constructs a new {@link Builder}.
- *
- * @return a new {@link Builder}
- * @since 1.12.0
- */
- public static Builder builder() {
- return new Builder();
- }
-
/**
* Internal class used to construct the default {@link StringLookup} map
used by {@link StringLookupFactory#addDefaultStringLookups(Map)}.
*/
@@ -582,6 +572,16 @@ public final class StringLookupFactory {
*/
public static final String KEY_XML_ENCODER = "xmlEncoder";
+ /**
+ * Constructs a new {@link Builder}.
+ *
+ * @return a new {@link Builder}
+ * @since 1.12.0
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
/**
* Clears any static resources.
*
diff --git a/src/test/java/org/apache/commons/text/TextStringBuilderTest.java
b/src/test/java/org/apache/commons/text/TextStringBuilderTest.java
index b3d63dd9..524ae3c5 100644
--- a/src/test/java/org/apache/commons/text/TextStringBuilderTest.java
+++ b/src/test/java/org/apache/commons/text/TextStringBuilderTest.java
@@ -340,6 +340,12 @@ public class TextStringBuilderTest {
}
}
+ @Test
+ public void testAsSupplier() {
+ final TextStringBuilder sb = new
TextStringBuilder().appendAll("Lorem", " ", "ipsum", " ", "dolor");
+ assertEquals(sb.toString(), sb.get());
+ }
+
@Test
public void testAsTokenizer() throws Exception {
// from Javadoc
