Package org.apache.commons.text.lookup

Class StringLookupFactory

java.lang.Object
org.apache.commons.text.lookup.StringLookupFactory
public final class StringLookupFactory
extends Object
Create instances of string lookups or access singleton string lookups implemented in this package.

The "classic" look up is mapStringLookup(Map).

The methods for variable interpolation (A.K.A. variable substitution) are:

The default lookups are:

Default String Lookups
Key Interface Factory Method Since
"base64Decoder" StringLookup base64DecoderStringLookup() 1.6
"base64Encoder" StringLookup base64EncoderStringLookup() 1.6
"const" StringLookup constantStringLookup() 1.5
"date" StringLookup dateStringLookup() 1.5
"dns" StringLookup dnsStringLookup() 1.8
"env" StringLookup environmentVariableStringLookup() 1.3
"file" StringLookup fileStringLookup() 1.5
"java" StringLookup javaPlatformStringLookup() 1.5
"localhost" StringLookup localHostStringLookup() 1.3
"properties" StringLookup propertiesStringLookup() 1.5
"resourceBundle" StringLookup resourceBundleStringLookup() 1.6
"script" StringLookup scriptStringLookup() 1.5
"sys" StringLookup systemPropertyStringLookup() 1.3
"url" StringLookup urlStringLookup() 1.5
"urlDecoder" StringLookup urlDecoderStringLookup() 1.5
"urlEncoder" StringLookup urlEncoderStringLookup() 1.5
"xml" StringLookup xmlStringLookup() 1.5

We also provide functional lookups used as building blocks for other lookups.

Functional String Lookups
Interface Factory Method Since
BiStringLookup biFunctionStringLookup(BiFunction) 1.9
StringLookup functionStringLookup(Function) 1.9
Since:
1.3

  • Field Details

  • Method Details

    • clear

      public static void clear()
      Clears any static resources.
      Since:
      1.5

    • addDefaultStringLookups

      public void addDefaultStringLookups​(Map<String,​StringLookup> stringLookupMap)
      Adds the default lookups.
      Parameters:
      stringLookupMap - the map of string lookups.
      Since:
      1.5

    • base64DecoderStringLookup

      public StringLookup base64DecoderStringLookup()
      Returns the Base64DecoderStringLookup singleton instance to decode Base64 strings.

      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!".

      Returns:
      The DateStringLookup singleton instance.
      Since:
      1.5

    • base64EncoderStringLookup

      public StringLookup base64EncoderStringLookup()
      Returns the Base64EncoderStringLookup singleton instance to encode strings to Base64.

      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=".

      Returns:
      The DateStringLookup singleton instance.
      Since:
      1.6

    • base64StringLookup

      @Deprecated public StringLookup base64StringLookup()
      Deprecated.
      Use base64DecoderStringLookup().
      Returns the Base64DecoderStringLookup singleton instance to decode Base64 strings.

      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!".

      Returns:
      The DateStringLookup singleton instance.
      Since:
      1.5

    • biFunctionStringLookup

      public <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.
      Type Parameters:
      R - the function return type.
      U - the function's second parameter type.
      Parameters:
      biFunction - the function.
      Returns:
      a new MapStringLookup.
      Since:
      1.9

    • constantStringLookup

      public StringLookup constantStringLookup()
      Returns the ConstantStringLookup singleton instance to look up the value of a fully-qualified static final value.

      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".

      Returns:
      The DateStringLookup singleton instance.
      Since:
      1.5

    • dateStringLookup

      public 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.

      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".

      Returns:
      The DateStringLookup singleton instance.

    • dnsStringLookup

      public 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.

      Using a StringLookup from the StringLookupFactory: 

       StringLookupFactory.INSTANCE.dnsStringLookup().lookup("address|apache.org");

      Using a StringSubstitutor: 

       StringSubstitutor.createInterpolator().replace("... ${dns:address|apache.org} ..."));

      The above examples convert "address|apache.org" to "95.216.24.32 (or "40.79.78.1").

      Returns:
      the DateStringLookup singleton instance.
      Since:
      1.8

    • environmentVariableStringLookup

      public StringLookup environmentVariableStringLookup()
      Returns the EnvironmentVariableStringLookup singleton instance where the lookup key is an environment variable name.

      Using a StringLookup from the StringLookupFactory: 

       StringLookupFactory.INSTANCE.dateStringLookup().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.

      Returns:
      The EnvironmentVariableStringLookup singleton instance.

    • fileStringLookup

      public StringLookup fileStringLookup()
      Returns the FileStringLookup singleton instance.

      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.

      Returns:
      The FileStringLookup singleton instance.
      Since:
      1.5

    • functionStringLookup

      public <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.
      Type Parameters:
      R - the function return type.
      Parameters:
      function - the function.
      Returns:
      a new MapStringLookup.
      Since:
      1.9

    • interpolatorStringLookup

      public StringLookup interpolatorStringLookup()
      Returns a new InterpolatorStringLookup using the default lookups.

      The lookups available to an interpolator are defined in

      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.

      Returns:
      a new InterpolatorStringLookup.

    • interpolatorStringLookup

      public StringLookup interpolatorStringLookup​(Map<String,​StringLookup> stringLookupMap, StringLookup defaultStringLookup, boolean addDefaultLookups)
      Returns a new InterpolatorStringLookup using the default lookups.

      If addDefaultLookups is true, the following lookups are used in addition to the ones provided in stringLookupMap:

      Parameters:
      stringLookupMap - the map of string lookups.
      defaultStringLookup - the default string lookup.
      addDefaultLookups - whether to use lookups as described above.
      Returns:
      a new InterpolatorStringLookup.
      Since:
      1.4

    • interpolatorStringLookup

      public <V> StringLookup interpolatorStringLookup​(Map<String,​V> map)
      Returns a new InterpolatorStringLookup using the default lookups.
      Type Parameters:
      V - the value type the default string lookup's map.
      Parameters:
      map - the default map for string lookups.
      Returns:
      a new InterpolatorStringLookup.

    • interpolatorStringLookup

      public StringLookup interpolatorStringLookup​(StringLookup defaultStringLookup)
      Returns a new InterpolatorStringLookup using the default lookups.
      Parameters:
      defaultStringLookup - the default string lookup.
      Returns:
      a new InterpolatorStringLookup.

    • javaPlatformStringLookup

      public StringLookup javaPlatformStringLookup()
      Returns the JavaPlatformStringLookup singleton instance. Looks up keys related to Java: Java version, JRE version, VM version, and so on.

      The lookup keys with examples are:

      • version: "Java version 1.8.0_181"
      • runtime: "Java(TM) SE Runtime Environment (build 1.8.0_181-b13) from Oracle Corporation"
      • vm: "Java HotSpot(TM) 64-Bit Server VM (build 25.181-b13, mixed mode)"
      • os: "Windows 10 10.0, architecture: amd64-64"
      • hardware: "processors: 4, architecture: amd64-64, instruction sets: amd64"
      • locale: "default locale: en_US, platform encoding: iso-8859-1"

      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".

      Returns:
      The JavaPlatformStringLookup singleton instance.

    • localHostStringLookup

      public 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.

      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".

      Returns:
      The DateStringLookup singleton instance.

    • mapStringLookup

      public <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.
      Type Parameters:
      V - the map value type.
      Parameters:
      map - the map.
      Returns:
      a new MapStringLookup.

    • nullStringLookup

      public StringLookup nullStringLookup()
      Returns the NullStringLookup singleton instance which always returns null.
      Returns:
      The NullStringLookup singleton instance.

    • propertiesStringLookup

      public StringLookup propertiesStringLookup()
      Returns the PropertiesStringLookup singleton instance.

      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".

      Returns:
      The PropertiesStringLookup singleton instance.
      Since:
      1.5

    • resourceBundleStringLookup

      public StringLookup resourceBundleStringLookup()
      Returns the ResourceBundleStringLookup singleton instance.

      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".

      Returns:
      The ResourceBundleStringLookup singleton instance.

    • resourceBundleStringLookup

      public StringLookup resourceBundleStringLookup​(String bundleName)
      Returns a ResourceBundleStringLookup instance for the given bundle name.

      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".

      Parameters:
      bundleName - Only lookup in this bundle.
      Returns:
      a ResourceBundleStringLookup instance for the given bundle name.
      Since:
      1.5

    • scriptStringLookup

      public StringLookup scriptStringLookup()
      Returns the ScriptStringLookup singleton instance.

      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");

      Using a StringSubstitutor: 

       StringSubstitutor.createInterpolator().replace("... ${javascript:3 + 4} ..."));

      The above examples convert "javascript:3 + 4" to "7".

      Returns:
      The ScriptStringLookup singleton instance.
      Since:
      1.5

    • systemPropertyStringLookup

      public StringLookup systemPropertyStringLookup()
      Returns the SystemPropertyStringLookup singleton instance where the lookup key is a system property name.

      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.

      Returns:
      The SystemPropertyStringLookup singleton instance.

    • urlDecoderStringLookup

      public StringLookup urlDecoderStringLookup()
      Returns the UrlDecoderStringLookup singleton instance.

      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!".

      Returns:
      The UrlStringLookup singleton instance.
      Since:
      1.6

    • urlEncoderStringLookup

      public StringLookup urlEncoderStringLookup()
      Returns the UrlDecoderStringLookup singleton instance.

      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".

      Returns:
      The UrlStringLookup singleton instance.
      Since:
      1.6

    • urlStringLookup

      public StringLookup urlStringLookup()
      Returns the UrlStringLookup singleton instance.

      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");

      Using a StringSubstitutor: 

       StringSubstitutor.createInterpolator().replace("... ${url:UTF-8:https://www.apache.org} ..."));

      The above examples convert "UTF-8:https://www.apache.org" to the contents of that page.

      Returns:
      The UrlStringLookup singleton instance.
      Since:
      1.5

    • xmlStringLookup

      public StringLookup xmlStringLookup()
      Returns the XmlStringLookup singleton instance.

      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.

      Returns:
      The XmlStringLookup singleton instance.
      Since:
      1.5