public final class StringLookupFactory extends Object
The "classic" look up is mapStringLookup(Map)
.
The methods for variable interpolation (A.K.A. variable substitution) are:
interpolatorStringLookup()
.interpolatorStringLookup(Map)
.interpolatorStringLookup(StringLookup)
.interpolatorStringLookup(Map, StringLookup, boolean)
.
Unless explicitly requested otherwise, a set of default lookups are included for convenience with these
variable interpolation methods. These defaults are listed in the table below. However, the exact lookups
included can be configured through the use of the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property.
If present, this system property will be parsed as a comma-separated list of lookup names, with the names
being those defined by the DefaultStringLookup
enum. For example, setting this system property to
"BASE64_ENCODER,ENVIRONMENT"
will only include the
BASE64_ENCODER
and ENVIRONMENT
lookups. Setting the property to the empty string will cause no defaults to be configured.
Note that not all lookups defined here and in DefaultStringLookup
are included by default.
Specifically, lookups that can execute code (e.g., SCRIPT
) and those
that can result in contact with remote servers (e.g., URL
and
DNS
) are not included by default. The current set of default lookups can
be accessed directly with addDefaultStringLookups(Map)
.
Key | Interface | Factory Method | Since |
---|---|---|---|
"dns" | StringLookup |
dnsStringLookup() |
1.8 |
"url" | StringLookup |
urlStringLookup() |
1.5 |
"script" | StringLookup |
scriptStringLookup() |
1.5 |
This class also provides functional lookups used as building blocks for other lookups.
Interface | Factory Method | Since |
---|---|---|
BiStringLookup |
biFunctionStringLookup(BiFunction) |
1.9 |
StringLookup |
functionStringLookup(Function) |
1.9 |
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_STRING_LOOKUPS_PROPERTY
Name of the system property used to determine the string lookups added by the
addDefaultStringLookups(Map) method. |
static StringLookupFactory |
INSTANCE
Defines the singleton for this class.
|
static String |
KEY_BASE64_DECODER
Default lookup key for interpolation "base64Decoder".
|
static String |
KEY_BASE64_ENCODER
Default lookup key for interpolation "base64Encoder".
|
static String |
KEY_CONST
Default lookup key for interpolation "const".
|
static String |
KEY_DATE
Default lookup key for interpolation "date".
|
static String |
KEY_DNS
Default lookup key for interpolation "dns".
|
static String |
KEY_ENV
Default lookup key for interpolation "env".
|
static String |
KEY_FILE
Default lookup key for interpolation "file".
|
static String |
KEY_JAVA
Default lookup key for interpolation "java".
|
static String |
KEY_LOCALHOST
Default lookup key for interpolation "localhost".
|
static String |
KEY_PROPERTIES
Default lookup key for interpolation "properties".
|
static String |
KEY_RESOURCE_BUNDLE
Default lookup key for interpolation "resourceBundle".
|
static String |
KEY_SCRIPT
Default lookup key for interpolation "script".
|
static String |
KEY_SYS
Default lookup key for interpolation "sys".
|
static String |
KEY_URL
Default lookup key for interpolation "url".
|
static String |
KEY_URL_DECODER
Default lookup key for interpolation "urlDecoder".
|
static String |
KEY_URL_ENCODER
Default lookup key for interpolation "urlEncoder".
|
static String |
KEY_XML
Default lookup key for interpolation "xml".
|
Modifier and Type | Method and Description |
---|---|
void |
addDefaultStringLookups(Map<String,StringLookup> stringLookupMap)
Adds the default string lookups for this class to
stringLookupMap . |
StringLookup |
base64DecoderStringLookup()
Returns the Base64DecoderStringLookup singleton instance to decode Base64 strings.
|
StringLookup |
base64EncoderStringLookup()
Returns the Base64EncoderStringLookup singleton instance to encode strings to Base64.
|
StringLookup |
base64StringLookup()
Deprecated.
|
<R,U> BiStringLookup<U> |
biFunctionStringLookup(BiFunction<String,U,R> biFunction)
Returns a new function-based lookup where the request for a lookup is answered by applying the function with a
lookup key.
|
static void |
clear()
Clears any static resources.
|
StringLookup |
constantStringLookup()
Returns the ConstantStringLookup singleton instance to look up the value of a fully-qualified static final value.
|
StringLookup |
dateStringLookup()
Returns the DateStringLookup singleton instance to format the current date with the format given in the key in a
format compatible with
SimpleDateFormat . |
StringLookup |
dnsStringLookup()
Returns the DnsStringLookup singleton instance where the lookup key is one of:
name: for the local host name, for example
EXAMPLE but also EXAMPLE.apache.org .
canonical-name: for the local canonical host name, for example EXAMPLE.apache.org .
address: for the local host address, for example 192.168.56.1 .
|
StringLookup |
environmentVariableStringLookup()
Returns the EnvironmentVariableStringLookup singleton instance where the lookup key is an environment variable
name.
|
StringLookup |
fileStringLookup()
Returns the FileStringLookup singleton instance.
|
<R> StringLookup |
functionStringLookup(Function<String,R> function)
Returns a new function-based lookup where the request for a lookup is answered by applying the function with a
lookup key.
|
StringLookup |
interpolatorStringLookup()
Returns a
InterpolatorStringLookup containing the configured
default lookups . |
StringLookup |
interpolatorStringLookup(Map<String,StringLookup> stringLookupMap,
StringLookup defaultStringLookup,
boolean addDefaultLookups)
Returns a new InterpolatorStringLookup.
|
<V> StringLookup |
interpolatorStringLookup(Map<String,V> map)
Returns a new InterpolatorStringLookup using the given key-value pairs and the configured
default lookups to resolve variables. |
StringLookup |
interpolatorStringLookup(StringLookup defaultStringLookup)
Returns a new InterpolatorStringLookup using the given lookup and the configured
default lookups to resolve variables. |
StringLookup |
javaPlatformStringLookup()
Returns the JavaPlatformStringLookup singleton instance.
|
StringLookup |
localHostStringLookup()
Returns the LocalHostStringLookup singleton instance where the lookup key is one of:
name: for the local host name, for example
EXAMPLE .
canonical-name: for the local canonical host name, for example EXAMPLE.apache.org .
address: for the local host address, for example 192.168.56.1 .
|
<V> StringLookup |
mapStringLookup(Map<String,V> map)
Returns a new map-based lookup where the request for a lookup is answered with the value for that key.
|
StringLookup |
nullStringLookup()
Returns the NullStringLookup singleton instance which always returns null.
|
StringLookup |
propertiesStringLookup()
Returns the PropertiesStringLookup singleton instance.
|
StringLookup |
resourceBundleStringLookup()
Returns the ResourceBundleStringLookup singleton instance.
|
StringLookup |
resourceBundleStringLookup(String bundleName)
Returns a ResourceBundleStringLookup instance for the given bundle name.
|
StringLookup |
scriptStringLookup()
Returns the ScriptStringLookup singleton instance.
|
StringLookup |
systemPropertyStringLookup()
Returns the SystemPropertyStringLookup singleton instance where the lookup key is a system property name.
|
StringLookup |
urlDecoderStringLookup()
Returns the UrlDecoderStringLookup singleton instance.
|
StringLookup |
urlEncoderStringLookup()
Returns the UrlDecoderStringLookup singleton instance.
|
StringLookup |
urlStringLookup()
Returns the UrlStringLookup singleton instance.
|
StringLookup |
xmlStringLookup()
Returns the XmlStringLookup singleton instance.
|
public static final StringLookupFactory INSTANCE
public static final String KEY_BASE64_DECODER
public static final String KEY_BASE64_ENCODER
public static final String KEY_CONST
public static final String KEY_DATE
public static final String KEY_DNS
public static final String KEY_ENV
public static final String KEY_FILE
public static final String KEY_JAVA
public static final String KEY_LOCALHOST
public static final String KEY_PROPERTIES
public static final String KEY_RESOURCE_BUNDLE
public static final String KEY_SCRIPT
public static final String KEY_SYS
public static final String KEY_URL
public static final String KEY_URL_DECODER
public static final String KEY_URL_ENCODER
public static final String KEY_XML
public static final String DEFAULT_STRING_LOOKUPS_PROPERTY
addDefaultStringLookups(Map)
method. Use of this property is only required
in cases where the set of default lookups must be modified. (See the class documentation
for details.)public static void clear()
public void addDefaultStringLookups(Map<String,StringLookup> stringLookupMap)
stringLookupMap
. The default string
lookups are a set of built-in lookups added for convenience during string interpolation. The
defaults may be configured using the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property.
See the class documentation for details and a list of lookups.stringLookupMap
- the map of string lookups to edit.public StringLookup base64DecoderStringLookup()
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));
The above examples convert "SGVsbG9Xb3JsZCE="
to "HelloWorld!"
.
public StringLookup base64EncoderStringLookup()
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.base64EncoderStringLookup().lookup("HelloWorld!");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${base64Encoder:HelloWorld!} ..."));
The above examples convert to "SGVsbG9Xb3JsZCE="
.
@Deprecated public StringLookup base64StringLookup()
base64DecoderStringLookup()
.
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));
The above examples convert "SGVsbG9Xb3JsZCE="
to "HelloWorld!"
.
public <R,U> BiStringLookup<U> biFunctionStringLookup(BiFunction<String,U,R> biFunction)
R
- the function return type.U
- the function's second parameter type.biFunction
- the function.public StringLookup constantStringLookup()
Sometimes it is necessary in a configuration file to refer to a constant defined in a class. This can be done
with this lookup implementation. Variable names must be in the format apackage.AClass.AFIELD
. The
lookup(String)
method will split the passed in string at the last dot, separating the fully qualified
class name and the name of the constant (i.e. static final) member field. Then the class is loaded and the
field's value is obtained using reflection.
Once retrieved values are cached for fast access. This class is thread-safe. It can be used as a standard (i.e. global) lookup object and serve multiple clients concurrently.
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.constantStringLookup().lookup("java.awt.event.KeyEvent.VK_ESCAPE");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${const:java.awt.event.KeyEvent.VK_ESCAPE} ..."));
The above examples convert java.awt.event.KeyEvent.VK_ESCAPE
to "27"
.
public StringLookup dateStringLookup()
SimpleDateFormat
.
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.dateStringLookup().lookup("yyyy-MM-dd");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${date:yyyy-MM-dd} ..."));
The above examples convert "yyyy-MM-dd"
to todays's date, for example, "2019-08-04"
.
public StringLookup dnsStringLookup()
EXAMPLE
but also EXAMPLE.apache.org
.EXAMPLE.apache.org
.192.168.56.1
.
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.dnsStringLookup().lookup("address|apache.org");
When used through a StringSubstitutor
, this lookup must either be added programmatically
(as below) or enabled as a default lookup using the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property
(see class documentation).
Map<String, StringLookup> lookupMap = new HashMap<>(); lookupMap.put("dns", StringLookupFactory.INSTANCE.dnsStringLookup()); StringLookup variableResolver = StringLookupFactory.INSTANCE.interpolatorStringLookup(lookupMap, null, false); new StringSubstitutor(variableResolver).replace("... ${dns:address|apache.org} ...");
The above examples convert "address|apache.org"
to the IP address of apache.org
.
public StringLookup environmentVariableStringLookup()
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.environmentVariableStringLookup().lookup("USER");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${env:USER} ..."));
The above examples convert (on Linux) "USER"
to the current user name. On Windows 10, you would use
"USERNAME"
to the same effect.
public StringLookup fileStringLookup()
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.fileStringLookup().lookup("UTF-8:com/domain/document.properties");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${file:UTF-8:com/domain/document.properties} ..."));
The above examples convert "UTF-8:com/domain/document.properties"
to the contents of the file.
public <R> StringLookup functionStringLookup(Function<String,R> function)
R
- the function return type.function
- the function.public StringLookup interpolatorStringLookup()
InterpolatorStringLookup
containing the configured
default lookups
. See the class documentation for
details on how these defaults are configured.
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.interpolatorStringLookup().lookup("${sys:os.name}, ${env:USER}");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${sys:os.name}, ${env:USER} ..."));
The above examples convert "${sys:os.name}, ${env:USER}"
to the OS name and Linux user name.
InterpolatorStringLookup
.public StringLookup interpolatorStringLookup(Map<String,StringLookup> stringLookupMap, StringLookup defaultStringLookup, boolean addDefaultLookups)
addDefaultLookups
is true
, the configured
default lookups
are included in addition to the ones
provided in stringLookupMap
. (See the class documentation for details on how default lookups
are configured.)stringLookupMap
- the map of string lookups.defaultStringLookup
- the default string lookup; this lookup is used when a variable cannot be
resolved using the lookups in stringLookupMap
or the configured default lookups (if enabled)addDefaultLookups
- whether to use default lookups as described above.public <V> StringLookup interpolatorStringLookup(Map<String,V> map)
default lookups
to resolve variables. (See the class
documentation for details on how default lookups are configured.)V
- the value type the default string lookup's map.map
- the default map for string lookups.public StringLookup interpolatorStringLookup(StringLookup defaultStringLookup)
default lookups
to resolve variables. (See the class
documentation for details on how default lookups are configured.)defaultStringLookup
- the default string lookup.public StringLookup javaPlatformStringLookup()
The lookup keys with examples are:
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.javaPlatformStringLookup().lookup("version");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${java:version} ..."));
The above examples convert "version"
to the current VM version, for example,
"Java version 1.8.0_181"
.
public StringLookup localHostStringLookup()
EXAMPLE
.EXAMPLE.apache.org
.192.168.56.1
.
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.localHostStringLookup().lookup("canonical-name");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${localhost:canonical-name} ..."));
The above examples convert "canonical-name"
to the current host name, for example,
"EXAMPLE.apache.org"
.
public <V> StringLookup mapStringLookup(Map<String,V> map)
V
- the map value type.map
- the map.public StringLookup nullStringLookup()
public StringLookup propertiesStringLookup()
Looks up the value for the key in the format "DocumentPath::MyKey".
Note the use of "::" instead of ":" to allow for "C:" drive letters in paths.
For example: "com/domain/document.properties::MyKey".
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.propertiesStringLookup().lookup("com/domain/document.properties::MyKey");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${properties:com/domain/document.properties::MyKey} ..."));
The above examples convert "com/domain/document.properties::MyKey"
to the key value in the properties
file at the path "com/domain/document.properties".
public StringLookup resourceBundleStringLookup()
Looks up the value for a given key in the format "BundleName:BundleKey".
For example: "com.domain.messages:MyKey".
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.resourceBundleStringLookup().lookup("com.domain.messages:MyKey");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${resourceBundle:com.domain.messages:MyKey} ..."));
The above examples convert "com.domain.messages:MyKey"
to the key value in the resource bundle at
"com.domain.messages"
.
public StringLookup resourceBundleStringLookup(String bundleName)
Looks up the value for a given key in the format "MyKey".
For example: "MyKey".
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.resourceBundleStringLookup("com.domain.messages").lookup("MyKey");
The above example converts "MyKey"
to the key value in the resource bundle at
"com.domain.messages"
.
bundleName
- Only lookup in this bundle.public StringLookup scriptStringLookup()
default lookup
unless explicitly enabled. See
the class level documentation for details.
Looks up the value for the key in the format "ScriptEngineName:Script".
For example: "javascript:3 + 4".
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.scriptStringLookup().lookup("javascript:3 + 4");
When used through a StringSubstitutor
, this lookup must either be added programmatically
(as below) or enabled as a default lookup using the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property
(see class documentation).
Map<String, StringLookup> lookupMap = new HashMap<>(); lookupMap.put("script", StringLookupFactory.INSTANCE.scriptStringLookup()); StringLookup variableResolver = StringLookupFactory.INSTANCE.interpolatorStringLookup(lookupMap, null, false); String value = new StringSubstitutor(variableResolver).replace("${script:javascript:3 + 4}");
The above examples convert "javascript:3 + 4"
to "7"
.
public StringLookup systemPropertyStringLookup()
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.systemPropertyStringLookup().lookup("os.name");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${sys:os.name} ..."));
The above examples convert "os.name"
to the operating system name.
public StringLookup urlDecoderStringLookup()
Decodes URL Strings using the UTF-8 encoding.
For example: "Hello%20World%21" becomes "Hello World!".
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.urlDecoderStringLookup().lookup("Hello%20World%21");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${urlDecoder:Hello%20World%21} ..."));
The above examples convert "Hello%20World%21"
to "Hello World!"
.
public StringLookup urlEncoderStringLookup()
Decodes URL Strings using the UTF-8 encoding.
For example: "Hello World!" becomes "Hello+World%21".
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.urlEncoderStringLookup().lookup("Hello World!");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${urlEncoder:Hello World!} ..."));
The above examples convert "Hello World!"
to "Hello%20World%21"
.
public StringLookup urlStringLookup()
default lookup
unless explicitly enabled. See
the class level documentation for details.
Looks up the value for the key in the format "CharsetName:URL".
For example, using the HTTP scheme: "UTF-8:http://www.google.com"
For example, using the file scheme: "UTF-8:file:///C:/somehome/commons/commons-text/src/test/resources/document.properties"
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.urlStringLookup().lookup("UTF-8:https://www.apache.org");
When used through a StringSubstitutor
, this lookup must either be added programmatically
(as below) or enabled as a default lookup using the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property
(see class documentation).
Map<String, StringLookup> lookupMap = new HashMap<>(); lookupMap.put("url", StringLookupFactory.INSTANCE.urlStringLookup()); StringLookup variableResolver = StringLookupFactory.INSTANCE.interpolatorStringLookup(lookupMap, null, false); String value = new StringSubstitutor(variableResolver).replace("${url:UTF-8:https://www.apache.org}");
The above examples convert "UTF-8:https://www.apache.org"
to the contents of that page.
public StringLookup xmlStringLookup()
Looks up the value for the key in the format "DocumentPath:XPath".
For example: "com/domain/document.xml:/path/to/node".
Using a StringLookup
from the StringLookupFactory
:
StringLookupFactory.INSTANCE.xmlStringLookup().lookup("com/domain/document.xml:/path/to/node");
Using a StringSubstitutor
:
StringSubstitutor.createInterpolator().replace("... ${xml:com/domain/document.xml:/path/to/node} ..."));
The above examples convert "com/domain/document.xml:/path/to/node"
to the value of the XPath in the XML
document.
Copyright © 2014–2022 The Apache Software Foundation. All rights reserved.