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 f8e2eba Expand Javadoc. new fde6c87 Merge branch 'master' of https://gitbox.apache.org/repos/asf/commons-text.git f8e2eba is described below commit f8e2eba2ef31670fa3ccfd62efb0746290b36741 Author: Gary Gregory <gardgreg...@gmail.com> AuthorDate: Sun Aug 4 12:27:00 2019 -0400 Expand Javadoc. --- .../commons/text/lookup/DnsStringLookup.java | 20 +++ .../commons/text/lookup/StringLookupFactory.java | 200 ++++++++++++++++++++- 2 files changed, 215 insertions(+), 5 deletions(-) diff --git a/src/main/java/org/apache/commons/text/lookup/DnsStringLookup.java b/src/main/java/org/apache/commons/text/lookup/DnsStringLookup.java index ba89418..d9e6f9d 100644 --- a/src/main/java/org/apache/commons/text/lookup/DnsStringLookup.java +++ b/src/main/java/org/apache/commons/text/lookup/DnsStringLookup.java @@ -19,6 +19,8 @@ package org.apache.commons.text.lookup; import java.net.InetAddress; import java.net.UnknownHostException; +import org.apache.commons.text.StringSubstitutor; + /** * Looks up keys related to DNS entries like host name, canonical host name, host address. * <p> @@ -34,6 +36,24 @@ import java.net.UnknownHostException; * <li><b><em>address</em></b>: same as {@code address|hostname}.</li> * </ul> * + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.dnsStringLookup().lookup("address|apache.org"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${dns:address|apache.org} ...")); + * </pre> + * <p> + * The above examples convert {@code "address|apache.org"} to {@code "95.216.24.32} (or {@code "40.79.78.1"}). + * </p> + * * @since 1.8 */ final class DnsStringLookup extends AbstractStringLookup { 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 b548503..443f808 100644 --- a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java +++ b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java @@ -599,7 +599,8 @@ public final class StringLookupFactory { * StringSubstitutor.createInterpolator().replace("... ${java:version} ...")); * </pre> * <p> - * The above examples convert {@code "version"} to the current VM version, for example, {@code "Java version 1.8.0_181"}. + * The above examples convert {@code "version"} to the current VM version, for example, + * {@code "Java version 1.8.0_181"}. * </p> * * @return The JavaPlatformStringLookup singleton instance. @@ -616,6 +617,25 @@ public final class StringLookupFactory { * <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.localHostStringLookup().lookup("canonical-name"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${localhost: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 DateStringLookup singleton instance. */ public StringLookup localHostStringLookup() { @@ -630,6 +650,24 @@ public final class StringLookupFactory { * <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.dnsStringLookup().lookup("address|apache.org"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${dns:address|apache.org} ...")); + * </pre> + * <p> + * The above examples convert {@code "address|apache.org"} to {@code "95.216.24.32} (or {@code "40.79.78.1"}). + * </p> + * * @return the DateStringLookup singleton instance. * @since 1.8 */ @@ -660,10 +698,29 @@ public final class StringLookupFactory { /** * Returns the PropertiesStringLookup singleton instance. * <p> - * Looks up the value for the key in the format "DocumentPath:Key". + * Looks up the value for the key in the format "DocumentPath:MyKey". * </p> * <p> - * For example: "com/domain/document.properties:Key". + * For example: "com/domain/document.properties:MyKey". + * </p> + * + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.propertiesStringLookup().lookup("com/domain/document.properties:MyKey"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${properties:com/domain/document.properties:MyKey} ...")); + * </pre> + * <p> + * The above examples convert {@code "com/domain/document.properties:MyKey"} to the key value in the properties file + * at the path "com/domain/document.properties". * </p> * * @return The PropertiesStringLookup singleton instance. @@ -681,6 +738,24 @@ public final class StringLookupFactory { * <p> * For example: "com.domain.messages:MyKey". * </p> + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.resourceBundleStringLookup().lookup("com.domain.messages:MyKey"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${resourceBundle:com.domain.messages:MyKey} ...")); + * </pre> + * <p> + * The above examples convert {@code "com.domain.messages:MyKey"} to the key value in the resource bundle at + * {@code "com.domain.messages"}. + * </p> * * @return The ResourceBundleStringLookup singleton instance. */ @@ -691,11 +766,22 @@ public final class StringLookupFactory { /** * Returns a ResourceBundleStringLookup instance for the given bundle name. * <p> - * Looks up the value for a given key in the format "BundleKey". + * Looks up the value for a given key in the format "MyKey". * </p> * <p> * For example: "MyKey". * </p> + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.resourceBundleStringLookup("com.domain.messages").lookup("MyKey"); + * </pre> + * <p> + * The above example converts {@code "MyKey"} to the key value in the resource bundle at + * {@code "com.domain.messages"}. + * </p> * * @param bundleName Only lookup in this bundle. * @return a ResourceBundleStringLookup instance for the given bundle name. @@ -711,7 +797,24 @@ public final class StringLookupFactory { * Looks up the value for the key in the format "ScriptEngineName:Script". * </p> * <p> - * For example: "javascript:3+4". + * For example: "javascript:3 + 4". + * </p> + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.scriptStringLookup().lookup("javascript:3 + 4"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${javascript:3 + 4} ...")); + * </pre> + * <p> + * The above examples convert {@code "javascript:3 + 4"} to {@code "7"}. * </p> * * @return The ScriptStringLookup singleton instance. @@ -724,6 +827,24 @@ public final class StringLookupFactory { /** * Returns the SystemPropertyStringLookup singleton instance where the lookup key is a system property name. * + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.systemPropertyStringLookup().lookup("USER"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${env:USER} ...")); + * </pre> + * <p> + * The above examples convert {@code "USER"} to the current Linux user. + * </p> + * * @return The SystemPropertyStringLookup singleton instance. */ public StringLookup systemPropertyStringLookup() { @@ -738,6 +859,23 @@ public final class StringLookupFactory { * <p> * For example: "Hello%20World%21" becomes "Hello World!". * </p> + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.urlDecoderStringLookup().lookup("Hello%20World%21"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${urlDecoder:Hello%20World%21} ...")); + * </pre> + * <p> + * The above examples convert {@code "Hello%20World%21"} to {@code "Hello World!"}. + * </p> * * @return The UrlStringLookup singleton instance. * @since 1.6 @@ -754,6 +892,23 @@ public final class StringLookupFactory { * <p> * For example: "Hello World!" becomes "Hello+World%21". * </p> + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.urlEncoderStringLookup().lookup("Hello World!"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${urlEncoder:Hello World!} ...")); + * </pre> + * <p> + * The above examples convert {@code "Hello World!"} to {@code "Hello%20World%21"}. + * </p> * * @return The UrlStringLookup singleton instance. * @since 1.6 @@ -774,6 +929,23 @@ public final class StringLookupFactory { * For example, using the file scheme: * "UTF-8:file:///C:/somehome/commons/commons-text/src/test/resources/document.properties" * </p> + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.urlStringLookup().lookup("UTF-8:http://www.google.com"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${url:UTF-8:http://www.google.com} ...")); + * </pre> + * <p> + * The above examples convert {@code "UTF-8:http://www.google.com"} to the contents of that page. + * </p> * * @return The UrlStringLookup singleton instance. * @since 1.5 @@ -790,6 +962,24 @@ public final class StringLookupFactory { * <p> * For example: "com/domain/document.xml:/path/to/node". * </p> + * <p> + * Using a {@link StringLookup} from the {@link StringLookupFactory}: + * </p> + * + * <pre> + * StringLookupFactory.INSTANCE.xmlStringLookup().lookup("com/domain/document.xml:/path/to/node"); + * </pre> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * + * <pre> + * StringSubstitutor.createInterpolator().replace("... ${xml:com/domain/document.xml:/path/to/node} ...")); + * </pre> + * <p> + * The above examples convert {@code "com/domain/document.xml:/path/to/node"} to the value of the XPath in the XML + * document. + * </p> * * @return The XmlStringLookup singleton instance. * @since 1.5