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 5597e216 Add support for a new StringLookup key "loopbackAddress", similar to "localhost" 5597e216 is described below commit 5597e216f2a4b11bae0b37ec597bfd0d9a0fcae7 Author: Gary Gregory <garydgreg...@gmail.com> AuthorDate: Thu Sep 19 13:17:37 2024 -0400 Add support for a new StringLookup key "loopbackAddress", similar to "localhost" --- pom.xml | 8 ++-- src/changes/changes.xml | 6 ++- .../org/apache/commons/text/StringSubstitutor.java | 4 ++ .../commons/text/lookup/DefaultStringLookup.java | 8 ++++ .../text/lookup/InetAddressStringLookup.java | 32 ++++++++++--- .../commons/text/lookup/StringLookupFactory.java | 53 ++++++++++++++++++++-- src/site/xdoc/userguide.xml | 3 +- ...a => InetAddressStringLookupLocalHostTest.java} | 19 ++++---- ...netAddressStringLookupLoopbackAddressTest.java} | 26 +++++------ .../text/lookup/StringLookupFactoryTest.java | 6 ++- 10 files changed, 122 insertions(+), 43 deletions(-) diff --git a/pom.xml b/pom.xml index 6641a18c..eae1ee3c 100644 --- a/pom.xml +++ b/pom.xml @@ -23,7 +23,7 @@ <version>75</version> </parent> <artifactId>commons-text</artifactId> - <version>1.12.1-SNAPSHOT</version> + <version>1.13.0-SNAPSHOT</version> <name>Apache Commons Text</name> <description>Apache Commons Text is a set of utility functions and reusable components for the purpose of processing and manipulating text that should be of use in a Java environment. @@ -41,8 +41,8 @@ <commons.packageId>text</commons.packageId> <commons.module.name>org.apache.commons.text</commons.module.name> - <commons.release.version>1.12.0</commons.release.version> - <commons.release.next>1.12.1</commons.release.next> + <commons.release.version>1.13.0</commons.release.version> + <commons.release.next>1.13.1</commons.release.next> <commons.release.desc>(Java 8+)</commons.release.desc> <commons.jira.id>TEXT</commons.jira.id> @@ -59,7 +59,7 @@ <!-- Commons Release Plugin --> <!-- Previous version of the component (used for reporting binary compatibility check)--> - <commons.bc.version>1.11.0</commons.bc.version> + <commons.bc.version>1.12.0</commons.bc.version> <commons.rc.version>RC1</commons.rc.version> <commons.release.isDistModule>true</commons.release.isDistModule> <commons.distSvnStagingUrl>scm:svn:https://dist.apache.org/repos/dist/dev/commons/${commons.componentid}</commons.distSvnStagingUrl> diff --git a/src/changes/changes.xml b/src/changes/changes.xml index db4ac195..91391f8a 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -45,7 +45,11 @@ The <action> type attribute can be add,update,fix,remove. <title>Apache Commons Text Changes</title> </properties> <body> - <release version="1.12.1" date="YYYY-MM-DD" description="Release 1.12.1. Requires Java 8 or above."> + <release version="1.13.0" date="YYYY-MM-DD" description="Release 1.13.0. Requires Java 8 or above."> + <!-- ADD --> + <action type="add" dev="ggregory" due-to="Gary Gregory">Add StringLookupFactory.loopbackAddressStringLookup().</action> + <action type="add" dev="ggregory" due-to="Gary Gregory">Add StringLookupFactory.KEY_LOOPBACK_ADDRESS.</action> + <action type="add" dev="ggregory" due-to="Gary Gregory">Add DefaultStringLookup.LOOPBACK_ADDRESS.</action> <!-- FIX --> <action type="fix" dev="ggregory" due-to="Gary Gregory">Fix build on Java 22.</action> <action type="fix" dev="ggregory" due-to="Gary Gregory">Fix build on Java 23-ea.</action> diff --git a/src/main/java/org/apache/commons/text/StringSubstitutor.java b/src/main/java/org/apache/commons/text/StringSubstitutor.java index 190e5a88..b83bf003 100644 --- a/src/main/java/org/apache/commons/text/StringSubstitutor.java +++ b/src/main/java/org/apache/commons/text/StringSubstitutor.java @@ -345,6 +345,10 @@ public class StringSubstitutor { * <td>{@link StringLookupFactory#localHostStringLookup()}</td> * </tr> * <tr> + * <td>{@value org.apache.commons.text.lookup.StringLookupFactory#KEY_LOOPBACK_ADDRESS}</td> + * <td>{@link StringLookupFactory#loopbackAddressStringLookup()}</td> + * </tr> + * <tr> * <td>{@value org.apache.commons.text.lookup.StringLookupFactory#KEY_PROPERTIES}</td> * <td>{@link StringLookupFactory#propertiesStringLookup()}</td> * </tr> diff --git a/src/main/java/org/apache/commons/text/lookup/DefaultStringLookup.java b/src/main/java/org/apache/commons/text/lookup/DefaultStringLookup.java index d7eb8bcf..b985efdf 100644 --- a/src/main/java/org/apache/commons/text/lookup/DefaultStringLookup.java +++ b/src/main/java/org/apache/commons/text/lookup/DefaultStringLookup.java @@ -106,6 +106,14 @@ public enum DefaultStringLookup { */ LOCAL_HOST(StringLookupFactory.KEY_LOCALHOST, StringLookupFactory.INSTANCE.localHostStringLookup()), + /** + * The lookup for local host information using the key {@code "loopbackAddress"}. + * + * @see StringLookupFactory#KEY_LOOPBACK_ADDRESS + * @see StringLookupFactory#loopbackAddressStringLookup() + */ + LOOPBACK_ADDRESS(StringLookupFactory.KEY_LOOPBACK_ADDRESS, StringLookupFactory.INSTANCE.loopbackAddressStringLookup()), + /** * The lookup for properties using the key {@code "properties"}. * diff --git a/src/main/java/org/apache/commons/text/lookup/InetAddressStringLookup.java b/src/main/java/org/apache/commons/text/lookup/InetAddressStringLookup.java index 797caa20..395d1d53 100644 --- a/src/main/java/org/apache/commons/text/lookup/InetAddressStringLookup.java +++ b/src/main/java/org/apache/commons/text/lookup/InetAddressStringLookup.java @@ -18,6 +18,9 @@ package org.apache.commons.text.lookup; import java.net.InetAddress; import java.net.UnknownHostException; +import java.util.Objects; + +import org.apache.commons.lang3.function.FailableSupplier; /** * Looks up keys related to an {@link InetAddresse}. @@ -38,15 +41,30 @@ import java.net.UnknownHostException; final class InetAddressStringLookup extends AbstractStringLookup { /** - * Defines the singleton for this class. + * Defines the LOCAL_HOST constant. */ - static final InetAddressStringLookup INSTANCE = new InetAddressStringLookup(); + static final InetAddressStringLookup LOCAL_HOST = new InetAddressStringLookup(InetAddress::getLocalHost); + + /** + * Defines the LOCAL_HOST constant. + */ + static final InetAddressStringLookup LOOPACK_ADDRESS = new InetAddressStringLookup(InetAddress::getLoopbackAddress); + + /** + * Supplies the InetAddress. + */ + private final FailableSupplier<InetAddress, UnknownHostException> inetAddressSupplier; /** * No need to build instances for now. */ - private InetAddressStringLookup() { - // empty + private InetAddressStringLookup(final FailableSupplier<InetAddress, UnknownHostException> inetAddressSupplier) { + this.inetAddressSupplier = Objects.requireNonNull(inetAddressSupplier, "inetAddressSupplier"); + } + + private InetAddress getInetAddress() throws UnknownHostException { + // Don't cache result, methods, like InetAddress::getLocalHost do their own cacheing. + return inetAddressSupplier.get(); } /** @@ -63,11 +81,11 @@ final class InetAddressStringLookup extends AbstractStringLookup { try { switch (key) { case InetAddressKeys.KEY_NAME: - return InetAddress.getLocalHost().getHostName(); + return getInetAddress().getHostName(); case InetAddressKeys.KEY_CANONICAL_NAME: - return InetAddress.getLocalHost().getCanonicalHostName(); + return getInetAddress().getCanonicalHostName(); case InetAddressKeys.KEY_ADDRESS: - return InetAddress.getLocalHost().getHostAddress(); + return getInetAddress().getHostAddress(); default: throw new IllegalArgumentException(key); } 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 995be76b..f14eb90a 100644 --- a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java +++ b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java @@ -17,6 +17,7 @@ package org.apache.commons.text.lookup; +import java.net.InetAddress; import java.nio.charset.StandardCharsets; import java.nio.file.Path; import java.util.Base64; @@ -115,6 +116,12 @@ import org.apache.commons.text.StringSubstitutor; * <td>1.3</td> * </tr> * <tr> + * <td>{@value #KEY_LOOPBACK_ADDRESS}</td> + * <td>{@link StringLookup}</td> + * <td>{@link #loopbackAddressStringLookup()}</td> + * <td>1.13.0</td> + * </tr> + * <tr> * <td>{@value #KEY_PROPERTIES}</td> * <td>{@link StringLookup}</td> * <td>{@link #propertiesStringLookup(Path...)}</td> @@ -289,6 +296,7 @@ public final class StringLookupFactory { addLookup(DefaultStringLookup.FILE, lookupMap); addLookup(DefaultStringLookup.JAVA, lookupMap); addLookup(DefaultStringLookup.LOCAL_HOST, lookupMap); + addLookup(DefaultStringLookup.LOCAL_HOST, lookupMap); addLookup(DefaultStringLookup.PROPERTIES, lookupMap); addLookup(DefaultStringLookup.RESOURCE_BUNDLE, lookupMap); addLookup(DefaultStringLookup.SYSTEM_PROPERTIES, lookupMap); @@ -502,6 +510,13 @@ public final class StringLookupFactory { */ public static final String KEY_LOCALHOST = "localhost"; + /** + * Default lookup key for interpolation {@value #KEY_LOOPBACK_ADDRESS}. + * + * @since 1.13.0 + */ + public static final String KEY_LOOPBACK_ADDRESS = "loobackAddress"; + /** * Default lookup key for interpolation {@value #KEY_PROPERTIES}. * @@ -1084,7 +1099,7 @@ public final class StringLookupFactory { } /** - * Returns the LocalHostStringLookup singleton instance where the lookup key is one of: + * Returns the InetAddressStringLookup instance where the lookup key for {@link InetAddress#getLocalHost()} is one of: * <ul> * <li><b>name</b>: for the local host name, for example {@code EXAMPLE}.</li> * <li><b>canonical-name</b>: for the local canonical host name, for example {@code EXAMPLE.apache.org}.</li> @@ -1109,10 +1124,42 @@ public final class StringLookupFactory { * The above examples convert {@code "canonical-name"} to the current host name, for example, {@code "EXAMPLE.apache.org"}. * </p> * - * @return The DateStringLookup singleton instance. + * @return The InetAddressStringLookup singleton instance. */ public StringLookup localHostStringLookup() { - return InetAddressStringLookup.INSTANCE; + return InetAddressStringLookup.LOCAL_HOST; + } + + /** + * Returns the InetAddressStringLookup instance where the lookup key for {@link InetAddress#getLoopbackAddress()} is one of: + * <ul> + * <li><b>name</b>: for the local host name, for example {@code EXAMPLE}.</li> + * <li><b>canonical-name</b>: for the local canonical host name, for example {@code EXAMPLE.apache.org}.</li> + * <li><b>address</b>: for the local host address, for example {@code 192.168.56.1}.</li> + * </ul> + * + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.loopbackAddressStringLookup().lookup("canonical-name"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${loopbackAddress:canonical-name} ...")); + * </pre> + * <p> + * The above examples convert {@code "canonical-name"} to the current host name, for example, {@code "EXAMPLE.apache.org"}. + * </p> + * + * @return The InetAddressStringLookup singleton instance. + */ + public StringLookup loopbackAddressStringLookup() { + return InetAddressStringLookup.LOOPACK_ADDRESS; } /** diff --git a/src/site/xdoc/userguide.xml b/src/site/xdoc/userguide.xml index eb5ed835..598b6c24 100644 --- a/src/site/xdoc/userguide.xml +++ b/src/site/xdoc/userguide.xml @@ -205,7 +205,8 @@ final String text = interpolator.replace( "<a href="https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html#environmentVariableStringLookup()">Environment Variable</a>: ${env:USERNAME}\n" + "<a href="https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html#fileStringLookup(java.nio.file.Path...)()">File Content</a>: ${file:UTF-8:src/test/resources/document.properties}\n" + "<a href="https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html#javaPlatformStringLookup()">Java</a>: ${java:version}\n" + - "<a href="https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html#localHostStringLookup()">Localhost</a>: ${localhost:canonical-name}\n" + + "<a href="https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html#localHostStringLookup()">Local host</a>: ${localhost:canonical-name}\n" + + "<a href="https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html#localHostStringLookup()">Loopback address</a>: ${loopbackAddress:canonical-name}\n" + "<a href="https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html#propertiesStringLookup(java.nio.file.Path...)()">Properties File</a>: ${properties:src/test/resources/document.properties::mykey}\n" + "<a href="https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html#resourceBundleStringLookup(java.lang.String)()">Resource Bundle</a>: ${resourceBundle:org.apache.commons.text.example.testResourceBundleLookup:mykey}\n" + "<a href="https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html#systemPropertyStringLookup()">System Property</a>: ${sys:user.dir}\n" + diff --git a/src/test/java/org/apache/commons/text/lookup/LocalHostStringLookupTest.java b/src/test/java/org/apache/commons/text/lookup/InetAddressStringLookupLocalHostTest.java similarity index 75% copy from src/test/java/org/apache/commons/text/lookup/LocalHostStringLookupTest.java copy to src/test/java/org/apache/commons/text/lookup/InetAddressStringLookupLocalHostTest.java index ddb64e32..cc8e3cd5 100644 --- a/src/test/java/org/apache/commons/text/lookup/LocalHostStringLookupTest.java +++ b/src/test/java/org/apache/commons/text/lookup/InetAddressStringLookupLocalHostTest.java @@ -24,42 +24,39 @@ import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; /** - * Tests {@link InetAddressStringLookup}. + * Tests {@link InetAddressStringLookup#LOCAL_HOST}. */ -public class LocalHostStringLookupTest { +public class InetAddressStringLookupLocalHostTest { @Test public void testAddress() throws UnknownHostException { - Assertions.assertEquals(InetAddress.getLocalHost().getHostAddress(), - InetAddressStringLookup.INSTANCE.lookup("address")); + Assertions.assertEquals(InetAddress.getLocalHost().getHostAddress(), InetAddressStringLookup.LOCAL_HOST.lookup("address")); } @Test public void testBadKey() { - Assertions.assertThrows(IllegalArgumentException.class, () -> InetAddressStringLookup.INSTANCE.lookup("FOO")); + Assertions.assertThrows(IllegalArgumentException.class, () -> InetAddressStringLookup.LOCAL_HOST.lookup("FOO")); } @Test public void testCanonicalName() throws UnknownHostException { - Assertions.assertEquals(InetAddress.getLocalHost().getCanonicalHostName(), - InetAddressStringLookup.INSTANCE.lookup("canonical-name")); + Assertions.assertEquals(InetAddress.getLocalHost().getCanonicalHostName(), InetAddressStringLookup.LOCAL_HOST.lookup("canonical-name")); } @Test public void testName() throws UnknownHostException { - Assertions.assertEquals(InetAddress.getLocalHost().getHostName(), - InetAddressStringLookup.INSTANCE.lookup("name")); + Assertions.assertEquals(InetAddress.getLocalHost().getHostName(), InetAddressStringLookup.LOCAL_HOST.lookup("name")); } @Test public void testNull() { - Assertions.assertNull(InetAddressStringLookup.INSTANCE.lookup(null)); + Assertions.assertNull(InetAddressStringLookup.LOCAL_HOST.lookup(null)); } @Test public void testToString() { // does not blow up and gives some kind of string. - Assertions.assertFalse(InetAddressStringLookup.INSTANCE.toString().isEmpty()); + Assertions.assertFalse(InetAddressStringLookup.LOCAL_HOST.toString().isEmpty()); } } diff --git a/src/test/java/org/apache/commons/text/lookup/LocalHostStringLookupTest.java b/src/test/java/org/apache/commons/text/lookup/InetAddressStringLookupLoopbackAddressTest.java similarity index 57% rename from src/test/java/org/apache/commons/text/lookup/LocalHostStringLookupTest.java rename to src/test/java/org/apache/commons/text/lookup/InetAddressStringLookupLoopbackAddressTest.java index ddb64e32..3d841440 100644 --- a/src/test/java/org/apache/commons/text/lookup/LocalHostStringLookupTest.java +++ b/src/test/java/org/apache/commons/text/lookup/InetAddressStringLookupLoopbackAddressTest.java @@ -18,48 +18,44 @@ package org.apache.commons.text.lookup; import java.net.InetAddress; -import java.net.UnknownHostException; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; /** - * Tests {@link InetAddressStringLookup}. + * Tests {@link InetAddressStringLookup#LOOPACK_ADDRESS}. */ -public class LocalHostStringLookupTest { +public class InetAddressStringLookupLoopbackAddressTest { @Test - public void testAddress() throws UnknownHostException { - Assertions.assertEquals(InetAddress.getLocalHost().getHostAddress(), - InetAddressStringLookup.INSTANCE.lookup("address")); + public void testAddress() { + Assertions.assertEquals(InetAddress.getLoopbackAddress().getHostAddress(), InetAddressStringLookup.LOOPACK_ADDRESS.lookup("address")); } @Test public void testBadKey() { - Assertions.assertThrows(IllegalArgumentException.class, () -> InetAddressStringLookup.INSTANCE.lookup("FOO")); + Assertions.assertThrows(IllegalArgumentException.class, () -> InetAddressStringLookup.LOOPACK_ADDRESS.lookup("FOO")); } @Test - public void testCanonicalName() throws UnknownHostException { - Assertions.assertEquals(InetAddress.getLocalHost().getCanonicalHostName(), - InetAddressStringLookup.INSTANCE.lookup("canonical-name")); + public void testCanonicalName() { + Assertions.assertEquals(InetAddress.getLoopbackAddress().getCanonicalHostName(), InetAddressStringLookup.LOOPACK_ADDRESS.lookup("canonical-name")); } @Test - public void testName() throws UnknownHostException { - Assertions.assertEquals(InetAddress.getLocalHost().getHostName(), - InetAddressStringLookup.INSTANCE.lookup("name")); + public void testName() { + Assertions.assertEquals(InetAddress.getLoopbackAddress().getHostName(), InetAddressStringLookup.LOOPACK_ADDRESS.lookup("name")); } @Test public void testNull() { - Assertions.assertNull(InetAddressStringLookup.INSTANCE.lookup(null)); + Assertions.assertNull(InetAddressStringLookup.LOOPACK_ADDRESS.lookup(null)); } @Test public void testToString() { // does not blow up and gives some kind of string. - Assertions.assertFalse(InetAddressStringLookup.INSTANCE.toString().isEmpty()); + Assertions.assertFalse(InetAddressStringLookup.LOOPACK_ADDRESS.toString().isEmpty()); } } diff --git a/src/test/java/org/apache/commons/text/lookup/StringLookupFactoryTest.java b/src/test/java/org/apache/commons/text/lookup/StringLookupFactoryTest.java index 8f29fc7a..b32b01ad 100644 --- a/src/test/java/org/apache/commons/text/lookup/StringLookupFactoryTest.java +++ b/src/test/java/org/apache/commons/text/lookup/StringLookupFactoryTest.java @@ -44,6 +44,7 @@ public class StringLookupFactoryTest { StringLookupFactory.KEY_FILE, StringLookupFactory.KEY_JAVA, StringLookupFactory.KEY_LOCALHOST, + StringLookupFactory.KEY_LOOPBACK_ADDRESS, StringLookupFactory.KEY_PROPERTIES, StringLookupFactory.KEY_RESOURCE_BUNDLE, StringLookupFactory.KEY_SYS, @@ -120,6 +121,7 @@ public class StringLookupFactoryTest { StringLookupFactory.KEY_FILE, StringLookupFactory.KEY_JAVA, StringLookupFactory.KEY_LOCALHOST, + StringLookupFactory.KEY_LOOPBACK_ADDRESS, StringLookupFactory.KEY_PROPERTIES, StringLookupFactory.KEY_RESOURCE_BUNDLE, StringLookupFactory.KEY_SYS, @@ -185,6 +187,7 @@ public class StringLookupFactoryTest { StringLookupFactory.KEY_FILE, StringLookupFactory.KEY_JAVA, StringLookupFactory.KEY_LOCALHOST, + StringLookupFactory.KEY_LOOPBACK_ADDRESS, StringLookupFactory.KEY_PROPERTIES, StringLookupFactory.KEY_RESOURCE_BUNDLE, StringLookupFactory.KEY_SYS, @@ -223,7 +226,8 @@ public class StringLookupFactoryTest { stringLookupFactory.environmentVariableStringLookup()); Assertions.assertSame(InterpolatorStringLookup.INSTANCE, stringLookupFactory.interpolatorStringLookup()); Assertions.assertSame(JavaPlatformStringLookup.INSTANCE, stringLookupFactory.javaPlatformStringLookup()); - Assertions.assertSame(InetAddressStringLookup.INSTANCE, stringLookupFactory.localHostStringLookup()); + Assertions.assertSame(InetAddressStringLookup.LOCAL_HOST, stringLookupFactory.localHostStringLookup()); + Assertions.assertSame(InetAddressStringLookup.LOOPACK_ADDRESS, stringLookupFactory.loopbackAddressStringLookup()); Assertions.assertSame(StringLookupFactory.INSTANCE_NULL, stringLookupFactory.nullStringLookup()); Assertions.assertSame(ResourceBundleStringLookup.INSTANCE, stringLookupFactory.resourceBundleStringLookup()); Assertions.assertSame(ScriptStringLookup.INSTANCE, stringLookupFactory.scriptStringLookup());