You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2019/08/04 16:29:44 UTC
[commons-text] branch master updated: Expand Javadoc.
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 <ga...@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