Package org.apache.commons.text.lookup

Class StringLookupFactory

    • Field Detail

      • INSTANCE

        public static final StringLookupFactory INSTANCE
        Defines the singleton for this class.

      • KEY_BASE64_DECODER

        public static final java.lang.String KEY_BASE64_DECODER
        Default lookup key for interpolation "base64Decoder".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_BASE64_ENCODER

        public static final java.lang.String KEY_BASE64_ENCODER
        Default lookup key for interpolation "base64Encoder".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_CONST

        public static final java.lang.String KEY_CONST
        Default lookup key for interpolation "const".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_DATE

        public static final java.lang.String KEY_DATE
        Default lookup key for interpolation "date".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_DNS

        public static final java.lang.String KEY_DNS
        Default lookup key for interpolation "dns".
        Since:
        1.8
        See Also:
        Constant Field Values

      • KEY_ENV

        public static final java.lang.String KEY_ENV
        Default lookup key for interpolation "env".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_FILE

        public static final java.lang.String KEY_FILE
        Default lookup key for interpolation "file".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_JAVA

        public static final java.lang.String KEY_JAVA
        Default lookup key for interpolation "java".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_LOCALHOST

        public static final java.lang.String KEY_LOCALHOST
        Default lookup key for interpolation "localhost".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_PROPERTIES

        public static final java.lang.String KEY_PROPERTIES
        Default lookup key for interpolation "properties".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_RESOURCE_BUNDLE

        public static final java.lang.String KEY_RESOURCE_BUNDLE
        Default lookup key for interpolation "resourceBundle".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_SCRIPT

        public static final java.lang.String KEY_SCRIPT
        Default lookup key for interpolation "script".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_SYS

        public static final java.lang.String KEY_SYS
        Default lookup key for interpolation "sys".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_URL

        public static final java.lang.String KEY_URL
        Default lookup key for interpolation "url".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_URL_DECODER

        public static final java.lang.String KEY_URL_DECODER
        Default lookup key for interpolation "urlDecoder".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_URL_ENCODER

        public static final java.lang.String KEY_URL_ENCODER
        Default lookup key for interpolation "urlEncoder".
        Since:
        1.6
        See Also:
        Constant Field Values

      • KEY_XML

        public static final java.lang.String KEY_XML
        Default lookup key for interpolation "xml".
        Since:
        1.6
        See Also:
        Constant Field Values

      • DEFAULT_STRING_LOOKUPS_PROPERTY

        public static final java.lang.String DEFAULT_STRING_LOOKUPS_PROPERTY
        Name of the system property used to determine the string lookups added by the 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.)
        Since:
        1.10.0
        See Also:
        Constant Field Values

    • Method Detail

      • clear

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

      • addDefaultStringLookups

        public void addDefaultStringLookups​(java.util.Map<java.lang.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​(java.util.function.BiFunction<java.lang.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 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​(java.util.function.Function<java.lang.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​(java.util.Map<java.lang.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​(java.util.Map<java.lang.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​(java.util.Map<java.lang.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​(java.lang.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

      • 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