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:

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

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
"env" StringLookup environmentVariableStringLookup() 1.3
"file" StringLookup fileStringLookup(Path...) 1.5
"java" StringLookup javaPlatformStringLookup() 1.5
"localhost" StringLookup localHostStringLookup() 1.3
"properties" StringLookup propertiesStringLookup(Path...) 1.5
"resourceBundle" StringLookup resourceBundleStringLookup() 1.6
"sys" StringLookup systemPropertyStringLookup() 1.3
"urlDecoder" StringLookup urlDecoderStringLookup() 1.5
"urlEncoder" StringLookup urlEncoderStringLookup() 1.5
"xml" StringLookup xmlStringLookup(Map, Path...) 1.5
"xmlDecoder" StringLookup xmlDecoderStringLookup() 1.11.0
"xmlEncoder" StringLookup xmlEncoderStringLookup() 1.11.0
Additional String Lookups (not included by default)
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.

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

  • Field Details

  • Method Details

    • builder

      public static StringLookupFactory.Builder builder()
      Constructs a new StringLookupFactory.Builder.
      Returns:
      a new StringLookupFactory.Builder
      Since:
      1.12.0

    • clear

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

    • addDefaultStringLookups

      public void addDefaultStringLookups(Map<String,StringLookup> stringLookupMap)
      Adds the default string lookups for this class to 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.
      Parameters:
      stringLookupMap - the map of string lookups to edit.
      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 Base64DecoderStringLookup 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 Base64EncoderStringLookup 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 Base64DecoderStringLookup 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 ConstantStringLookup 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");

      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.

      Returns:
      the DnsStringLookup 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.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.

      Returns:
      The EnvironmentVariableStringLookup singleton instance.

    • fileStringLookup

      public StringLookup fileStringLookup()
      Returns a file StringLookup instance.

      If this factory was built using StringLookupFactory.Builder.setFences(Path...), then the string lookup is fenced and will throw an IllegalArgumentException if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

      Using a fenced StringLookup

      To use a fenced StringLookup, use builder(): 

       // Make the fence the current directory
 StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
 factory.fileStringLookup().lookup("UTF-8:com/domain/document.txt");

 // throws IllegalArgumentException
 factory.fileStringLookup().lookup("UTF-8:/rootdir/foo/document.txt");

 // throws IllegalArgumentException
 factory.fileStringLookup().lookup("UTF-8:../document.txt");
      Using an unfenced StringLookup

      To use an unfenced StringLookup, use INSTANCE: 

       StringLookupFactory.INSTANCE.fileStringLookup().lookup("UTF-8:com/domain/document.properties");
      Using a StringLookup with StringSubstitutor

      To build a fenced StringSubstitutor, use: 

       // Make the fence the current directory
 final StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
 final StringSubstitutor stringSubstitutor = new StringSubstitutor(factory.interpolatorStringLookup());
 stringSubstitutor.replace("... ${file:UTF-8:com/domain/document.txt} ..."));

 // throws IllegalArgumentException
 stringSubstitutor.replace("... ${file:UTF-8:/rootdir/foo/document.txt} ..."));

      Using an unfenced StringSubstitutor: 

       StringSubstitutor.createInterpolator().replace("... ${file:UTF-8:com/domain/document.txt} ..."));

      The above examples convert "UTF-8:com/domain/document.txt" to the contents of the file.

      Returns:
      a file StringLookup instance.
      Since:
      1.5

    • fileStringLookup

      public StringLookup fileStringLookup(Path... fences)
      Returns a fenced file StringLookup instance.

      To use a StringLookup fenced by the current directory, use: 

       StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("UTF-8:com/domain/document.txt");

 // throws IllegalArgumentException
 StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("UTF-8:/rootdir/foo/document.txt");

 // throws IllegalArgumentException
 StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("UTF-8:../com/domain/document.txt");

      The above example converts "UTF-8:com/domain/document.txt" to the contents of the file.

      StringSubstitutor methods like StringSubstitutor.replace(String) will throw a IllegalArgumentException when a file doesn't resolves in a fence.

      Parameters:
      fences - The fences guarding Path resolution.
      Returns:
      a file StringLookup instance.
      Since:
      1.12.0

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

      Returns:
      the default InterpolatorStringLookup.

    • interpolatorStringLookup

      public StringLookup interpolatorStringLookup(Map<String,StringLookup> stringLookupMap, StringLookup defaultStringLookup, boolean addDefaultLookups)
      Returns a new InterpolatorStringLookup. If 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.)
      Parameters:
      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.
      Returns:
      a new InterpolatorStringLookup.
      Since:
      1.4

    • interpolatorStringLookup

      public <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. (See the class documentation for details on how default lookups are configured.)
      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 given lookup and the configured default lookups to resolve variables. (See the class documentation for details on how default lookups are configured.)
      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 a Properties StringLookup instance.

      If this factory was built using StringLookupFactory.Builder.setFences(Path...), then the string lookup is fenced and will throw an IllegalArgumentException if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

      We looks up a 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 fenced StringLookup

      To use a fenced StringLookup, use builder(): 

       // Make the fence the current directory
 StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
 factory.propertiesStringLookup().lookup("com/domain/document.properties::MyKey");

 // throws IllegalArgumentException
 factory.propertiesStringLookup().lookup("/com/domain/document.properties::MyKey");

 // throws IllegalArgumentException
 factory.propertiesStringLookup().lookup("../com/domain/document.properties::MyKey");
      Using an unfenced StringLookup

      To use an unfenced StringLookup, use INSTANCE: 

       StringLookupFactory.INSTANCE.propertiesStringLookup().lookup("com/domain/document.properties::MyKey");
      Using a StringLookup with StringSubstitutor

      To build a fenced StringSubstitutor, use: 

       // Make the fence the current directory
 final StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
 final StringSubstitutor stringSubstitutor = new StringSubstitutor(factory.interpolatorStringLookup());
 stringSubstitutor.replace("... ${properties:com/domain/document.properties::MyKey} ..."));

 // throws IllegalArgumentException
 stringSubstitutor.replace("... ${properties:/rootdir/foo/document.properties::MyKey} ..."));

      Using an unfenced 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:
      a Properties StringLookup instance.
      Since:
      1.5

    • propertiesStringLookup

      public StringLookup propertiesStringLookup(Path... fences)
      Returns a fenced Properties StringLookup 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".

      To use a StringLookup fenced by the current directory, use: 

       StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("com/domain/document.properties::MyKey");

 // throws IllegalArgumentException
 StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("com/domain/document.properties::MyKey");

 // throws IllegalArgumentException
 StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("com/domain/document.properties::MyKey");

      The above example converts "com/domain/document.properties::MyKey" to the key value in the properties file at the path "com/domain/document.properties".

      StringSubstitutor methods like StringSubstitutor.replace(String) will throw a IllegalArgumentException when a file doesn't resolves in a fence.

      Parameters:
      fences - The fences guarding Path resolution.
      Returns:
      a Properties StringLookup instance.
      Since:
      1.12.0

    • 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. NOTE: This lookup is not included as a 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".

      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. This lookup is not included as a 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.

      Returns:
      The UrlStringLookup singleton instance.
      Since:
      1.5

    • xmlDecoderStringLookup

      public StringLookup xmlDecoderStringLookup()
      Returns the XmlDecoderStringLookup singleton instance.

      Decodes strings according to the XML 1.0 specification.

      For example: "&lt;element&gt;" becomes "<element>".

      Using a StringLookup from the StringLookupFactory: 

       StringLookupFactory.INSTANCE.xmlDecoderStringLookup().lookup("&lt;element&gt;");

      Using a StringSubstitutor: 

       StringSubstitutor.createInterpolator().replace("... ${xmlDecoder:&lt;element&gt;} ..."));

      The above examples convert "&lt;element&gt;" to "<element>".

      Returns:
      The XmlDecoderStringLookup singleton instance.
      Since:
      1.11.0

    • xmlEncoderStringLookup

      public StringLookup xmlEncoderStringLookup()
      Returns the XmlEncoderStringLookup singleton instance.

      Encodes strings according to the XML 1.0 specification.

      For example: "<element>" becomes "&lt;element&gt;".

      Using a StringLookup from the StringLookupFactory: 

       StringLookupFactory.INSTANCE.xmlEncoderStringLookup().lookup("<element>");

      Using a StringSubstitutor: 

       StringSubstitutor.createInterpolator().replace("... ${xmlEncoder:<element>} ..."));

      The above examples convert "<element>" to "&lt;element&gt;".

      Returns:
      The XmlEncoderStringLookup singleton instance.
      Since:
      1.11.0

    • xmlStringLookup

      public StringLookup xmlStringLookup()
      Returns an XML StringLookup instance.

      If this factory was built using StringLookupFactory.Builder.setFences(Path...), then the string lookup is fenced and will throw an IllegalArgumentException if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

      We look 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:
      An XML StringLookup instance.
      Since:
      1.5

    • xmlStringLookup

      public StringLookup xmlStringLookup(Map<String,Boolean> xPathFactoryFeatures)
      Returns an XML StringLookup instance.

      If this factory was built using StringLookupFactory.Builder.setFences(Path...), then the string lookup is fenced and will throw an IllegalArgumentException if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

      We look 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.

      Parameters:
      xPathFactoryFeatures - XPathFactory features to set.
      Returns:
      An XML StringLookup instance.
      Since:
      1.11.0
      See Also:

    • xmlStringLookup

      public StringLookup xmlStringLookup(Map<String,Boolean> xPathFactoryFeatures, Path... fences)
      Returns a fenced XML StringLookup instance.

      If this factory was built using StringLookupFactory.Builder.setFences(Path...), then the string lookup is fenced and will throw an IllegalArgumentException if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

      We look 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 fenced by the current directory (Paths.get("")): 

       StringLookupFactory.INSTANCE.xmlStringLookup(map, Pathe.get("")).lookup("com/domain/document.xml:/path/to/node");

      To use a StringLookup fenced by the current directory, use: 

       StringLookupFactory.INSTANCE.xmlStringLookup(Paths.get("")).lookup("com/domain/document.xml:/path/to/node");

 // throws IllegalArgumentException
 StringLookupFactory.INSTANCE.xmlStringLookup(Paths.get("")).lookup("/rootdir/foo/document.xml:/path/to/node");

 // throws IllegalArgumentException
 StringLookupFactory.INSTANCE.xmlStringLookup(Paths.get("")).lookup("../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.

      StringSubstitutor methods like StringSubstitutor.replace(String) will throw a IllegalArgumentException when a file doesn't resolves in a fence.

      Parameters:
      xPathFactoryFeatures - XPathFactory features to set.
      fences - The fences guarding Path resolution.
      Returns:
      An XML StringLookup instance.
      Since:
      1.12.0