    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements. See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache license, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License. You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the license for the specific language governing permissions and
    015 * limitations under the license.
    016 */
    017
    018package org.apache.commons.text.lookup;
    019
    020import java.util.Map;
    021
    022/**
    023 * Provides access to lookups defined in this package.
    024 * <p>
    025 * The default lookups are:
    026 * </p>
    027 * <table>
    028 * <caption>Default String Lookups</caption>
    029 * <tr>
    030 * <th>Key</th>
    031 * <th>Implementation</th>
    032 * <th>Factory Method</th>
    033 * <th>Since</th>
    034 * </tr>
    035 * <tr>
    036 * <td>{@value #KEY_BASE64_DECODER}</td>
    037 * <td>{@link Base64DecoderStringLookup}</td>
    038 * <td>{@link #base64DecoderStringLookup()}</td>
    039 * <td>1.6</td>
    040 * </tr>
    041 * <tr>
    042 * <td>{@value #KEY_BASE64_ENCODER}</td>
    043 * <td>{@link Base64EncoderStringLookup}</td>
    044 * <td>{@link #base64EncoderStringLookup()}</td>
    045 * <td>1.6</td>
    046 * </tr>
    047 * <tr>
    048 * <td>{@value #KEY_CONST}</td>
    049 * <td>{@link ConstantStringLookup}</td>
    050 * <td>{@link #constantStringLookup()}</td>
    051 * <td>1.5</td>
    052 * </tr>
    053 * <tr>
    054 * <td>{@value #KEY_DATE}</td>
    055 * <td>{@link DateStringLookup}</td>
    056 * <td>{@link #dateStringLookup()}</td>
    057 * <td>1.5</td>
    058 * </tr>
    059 * <tr>
    060 * <td>{@value #KEY_ENV}</td>
    061 * <td>{@link EnvironmentVariableStringLookup}</td>
    062 * <td>{@link #environmentVariableStringLookup()}</td>
    063 * <td>1.3</td>
    064 * </tr>
    065 * <tr>
    066 * <td>{@value #KEY_FILE}</td>
    067 * <td>{@link FileStringLookup}</td>
    068 * <td>{@link #fileStringLookup()}</td>
    069 * <td>1.5</td>
    070 * </tr>
    071 * <tr>
    072 * <td>{@value #KEY_JAVA}</td>
    073 * <td>{@link JavaPlatformStringLookup}</td>
    074 * <td>{@link #javaPlatformStringLookup()}</td>
    075 * <td>1.5</td>
    076 * </tr>
    077 * <tr>
    078 * <td>{@value #KEY_LOCALHOST}</td>
    079 * <td>{@link LocalHostStringLookup}</td>
    080 * <td>{@link #localHostStringLookup()}</td>
    081 * <td>1.3</td>
    082 * </tr>
    083 * <tr>
    084 * <td>{@value #KEY_PROPERTIES}</td>
    085 * <td>{@link PropertiesStringLookup}</td>
    086 * <td>{@link #propertiesStringLookup()}</td>
    087 * <td>1.5</td>
    088 * </tr>
    089 * <tr>
    090 * <td>{@value #KEY_RESOURCE_BUNDLE}</td>
    091 * <td>{@link ResourceBundleStringLookup}</td>
    092 * <td>{@link #resourceBundleStringLookup()}</td>
    093 * <td>1.6</td>
    094 * </tr>
    095 * <tr>
    096 * <td>{@value #KEY_SCRIPT}</td>
    097 * <td>{@link ScriptStringLookup}</td>
    098 * <td>{@link #scriptStringLookup()}</td>
    099 * <td>1.5</td>
    100 * </tr>
    101 * <tr>
    102 * <td>{@value #KEY_SYS}</td>
    103 * <td>{@link SystemPropertyStringLookup}</td>
    104 * <td>{@link #systemPropertyStringLookup()}</td>
    105 * <td>1.3</td>
    106 * </tr>
    107 * <tr>
    108 * <td>{@value #KEY_URL}</td>
    109 * <td>{@link UrlStringLookup}</td>
    110 * <td>{@link #urlStringLookup()}</td>
    111 * <td>1.5</td>
    112 * </tr>
    113 * <tr>
    114 * <td>{@value #KEY_URL_DECODER}</td>
    115 * <td>{@link UrlDecoderStringLookup}</td>
    116 * <td>{@link #urlDecoderStringLookup()}</td>
    117 * <td>1.5</td>
    118 * </tr>
    119 * <tr>
    120 * <td>{@value #KEY_URL_ENCODER}</td>
    121 * <td>{@link UrlEncoderStringLookup}</td>
    122 * <td>{@link #urlEncoderStringLookup()}</td>
    123 * <td>1.5</td>
    124 * </tr>
    125 * <tr>
    126 * <td>{@value #KEY_XML}</td>
    127 * <td>{@link XmlStringLookup}</td>
    128 * <td>{@link #xmlStringLookup()}</td>
    129 * <td>1.5</td>
    130 * </tr>
    131 * </table>
    132 *
    133 * @since 1.3
    134 */
    135public final class StringLookupFactory {
    136
    137    /**
    138     * Defines the singleton for this class.
    139     */
    140    public static final StringLookupFactory INSTANCE = new StringLookupFactory();
    141
    142    /**
    143     * Default lookup key for interpolation.
    144     *
    145     * @since 1.6
    146     */
    147    public static final String KEY_BASE64_DECODER = "base64Decoder";
    148
    149    /**
    150     * Default lookup key for interpolation.
    151     *
    152     * @since 1.6
    153     */
    154    public static final String KEY_BASE64_ENCODER = "base64Encoder";
    155
    156    /**
    157     * Default lookup key for interpolation.
    158     *
    159     * @since 1.6
    160     */
    161    public static final String KEY_CONST = "const";
    162
    163    /**
    164     * Default lookup key for interpolation.
    165     *
    166     * @since 1.6
    167     */
    168    public static final String KEY_DATE = "date";
    169
    170    /**
    171     * Default lookup key for interpolation.
    172     *
    173     * @since 1.6
    174     */
    175    public static final String KEY_ENV = "env";
    176
    177    /**
    178     * Default lookup key for interpolation.
    179     *
    180     * @since 1.6
    181     */
    182    public static final String KEY_FILE = "file";
    183
    184    /**
    185     * Default lookup key for interpolation.
    186     *
    187     * @since 1.6
    188     */
    189    public static final String KEY_JAVA = "java";
    190
    191    /**
    192     * Default lookup key for interpolation.
    193     *
    194     * @since 1.6
    195     */
    196    public static final String KEY_LOCALHOST = "localhost";
    197
    198    /**
    199     * Default lookup key for interpolation.
    200     *
    201     * @since 1.6
    202     */
    203    public static final String KEY_PROPERTIES = "properties";
    204
    205    /**
    206     * Default lookup key for interpolation.
    207     *
    208     * @since 1.6
    209     */
    210    public static final String KEY_RESOURCE_BUNDLE = "resourceBundle";
    211
    212    /**
    213     * Default lookup key for interpolation.
    214     *
    215     * @since 1.6
    216     */
    217    public static final String KEY_SCRIPT = "script";
    218
    219    /**
    220     * Default lookup key for interpolation.
    221     *
    222     * @since 1.6
    223     */
    224    public static final String KEY_SYS = "sys";
    225
    226    /**
    227     * Default lookup key for interpolation.
    228     *
    229     * @since 1.6
    230     */
    231    public static final String KEY_URL = "url";
    232
    233    /**
    234     * Default lookup key for interpolation.
    235     *
    236     * @since 1.6
    237     */
    238    public static final String KEY_URL_DECODER = "urlDecoder";
    239
    240    /**
    241     * Default lookup key for interpolation.
    242     *
    243     * @since 1.6
    244     */
    245    public static final String KEY_URL_ENCODER = "urlEncoder";
    246
    247    /**
    248     * Default lookup key for interpolation.
    249     *
    250     * @since 1.6
    251     */
    252    public static final String KEY_XML = "xml";
    253
    254    /**
    255     * Clears any static resources.
    256     *
    257     * @since 1.5
    258     */
    259    public static void clear() {
    260        ConstantStringLookup.clear();
    261    }
    262
    263    /**
    264     * No need to build instances for now.
    265     */
    266    private StringLookupFactory() {
    267        // empty
    268    }
    269
    270    /**
    271     * Adds the {@link StringLookupFactory default lookups}.
    272     *
    273     * @param stringLookupMap
    274     *            the map of string lookups.
    275     * @since 1.5
    276     */
    277    public void addDefaultStringLookups(final Map<String, StringLookup> stringLookupMap) {
    278        if (stringLookupMap != null) {
    279            // "base64" is deprecated in favor of KEY_BASE64_DECODER.
    280            stringLookupMap.put("base64", Base64DecoderStringLookup.INSTANCE);
    281            stringLookupMap.put(KEY_BASE64_DECODER, Base64DecoderStringLookup.INSTANCE);
    282            stringLookupMap.put(KEY_BASE64_ENCODER, Base64EncoderStringLookup.INSTANCE);
    283            stringLookupMap.put(KEY_CONST, ConstantStringLookup.INSTANCE);
    284            stringLookupMap.put(KEY_DATE, DateStringLookup.INSTANCE);
    285            stringLookupMap.put(KEY_ENV, EnvironmentVariableStringLookup.INSTANCE);
    286            stringLookupMap.put(KEY_FILE, FileStringLookup.INSTANCE);
    287            stringLookupMap.put(KEY_JAVA, JavaPlatformStringLookup.INSTANCE);
    288            stringLookupMap.put(KEY_LOCALHOST, LocalHostStringLookup.INSTANCE);
    289            stringLookupMap.put(KEY_PROPERTIES, PropertiesStringLookup.INSTANCE);
    290            stringLookupMap.put(KEY_RESOURCE_BUNDLE, ResourceBundleStringLookup.INSTANCE);
    291            stringLookupMap.put(KEY_SCRIPT, ScriptStringLookup.INSTANCE);
    292            stringLookupMap.put(KEY_SYS, SystemPropertyStringLookup.INSTANCE);
    293            stringLookupMap.put(KEY_URL, UrlStringLookup.INSTANCE);
    294            stringLookupMap.put(KEY_URL_DECODER, UrlDecoderStringLookup.INSTANCE);
    295            stringLookupMap.put(KEY_URL_ENCODER, UrlEncoderStringLookup.INSTANCE);
    296            stringLookupMap.put(KEY_XML, XmlStringLookup.INSTANCE);
    297        }
    298    }
    299
    300    /**
    301     * Returns the Base64StringLookup singleton instance to format the current date with the format given in the key in
    302     * a format compatible with {@link java.text.SimpleDateFormat}.
    303     *
    304     * @return the DateStringLookup singleton instance.
    305     * @since 1.5
    306     */
    307    public StringLookup base64DecoderStringLookup() {
    308        return Base64DecoderStringLookup.INSTANCE;
    309    }
    310
    311    /**
    312     * Returns the Base64StringLookup singleton instance to format the current date with the format given in the key in
    313     * a format compatible with {@link java.text.SimpleDateFormat}.
    314     *
    315     * @return the DateStringLookup singleton instance.
    316     * @since 1.6
    317     */
    318    public StringLookup base64EncoderStringLookup() {
    319        return Base64EncoderStringLookup.INSTANCE;
    320    }
    321
    322    /**
    323     * Returns the Base64StringLookup singleton instance to format the current date with the format given in the key in
    324     * a format compatible with {@link java.text.SimpleDateFormat}.
    325     *
    326     * @return the DateStringLookup singleton instance.
    327     * @since 1.5
    328     * @deprecated Use {@link #base64DecoderStringLookup()}.
    329     */
    330    @Deprecated
    331    public StringLookup base64StringLookup() {
    332        return Base64DecoderStringLookup.INSTANCE;
    333    }
    334
    335    /**
    336     * Returns the ConstantStringLookup singleton instance to get the value of a fully-qualified static final value.
    337     *
    338     * @return the DateStringLookup singleton instance.
    339     * @since 1.5
    340     */
    341    public StringLookup constantStringLookup() {
    342        return ConstantStringLookup.INSTANCE;
    343    }
    344
    345    /**
    346     * Returns the DateStringLookup singleton instance to format the current date with the format given in the key in a
    347     * format compatible with {@link java.text.SimpleDateFormat}.
    348     *
    349     * @return the DateStringLookup singleton instance.
    350     */
    351    public StringLookup dateStringLookup() {
    352        return DateStringLookup.INSTANCE;
    353    }
    354
    355    /**
    356     * Returns the EnvironmentVariableStringLookup singleton instance where the lookup key is an environment variable
    357     * name.
    358     *
    359     * @return the EnvironmentVariableStringLookup singleton instance.
    360     */
    361    public StringLookup environmentVariableStringLookup() {
    362        return EnvironmentVariableStringLookup.INSTANCE;
    363    }
    364
    365    /**
    366     * Returns the FileStringLookup singleton instance.
    367     * <p>
    368     * Looks up the value for the key in the format "CharsetName:Path".
    369     * </p>
    370     * <p>
    371     * For example: "UTF-8:com/domain/document.properties".
    372     * </p>
    373     *
    374     * @return the FileStringLookup singleton instance.
    375     * @since 1.5
    376     */
    377    public StringLookup fileStringLookup() {
    378        return FileStringLookup.INSTANCE;
    379    }
    380
    381    /**
    382     * Returns a new InterpolatorStringLookup using the {@link StringLookupFactory default lookups}.
    383     *
    384     * @return a new InterpolatorStringLookup.
    385     */
    386    public StringLookup interpolatorStringLookup() {
    387        return InterpolatorStringLookup.INSTANCE;
    388    }
    389
    390    /**
    391     * Returns a new InterpolatorStringLookup using the {@link StringLookupFactory default lookups}.
    392     * <p>
    393     * If {@code addDefaultLookups} is true, the following lookups are used in addition to the ones provided in
    394     * {@code stringLookupMap}:
    395     * </p>
    396     *
    397     * @param stringLookupMap
    398     *            the map of string lookups.
    399     * @param defaultStringLookup
    400     *            the default string lookup.
    401     * @param addDefaultLookups
    402     *            whether to use lookups as described above.
    403     * @return a new InterpolatorStringLookup.
    404     * @since 1.4
    405     */
    406    public StringLookup interpolatorStringLookup(final Map<String, StringLookup> stringLookupMap,
    407            final StringLookup defaultStringLookup, final boolean addDefaultLookups) {
    408        return new InterpolatorStringLookup(stringLookupMap, defaultStringLookup, addDefaultLookups);
    409    }
    410
    411    /**
    412     * Returns a new InterpolatorStringLookup using the {@link StringLookupFactory default lookups}.
    413     *
    414     * @param <V>
    415     *            the value type the default string lookup's map.
    416     * @param map
    417     *            the default map for string lookups.
    418     * @return a new InterpolatorStringLookup.
    419     */
    420    public <V> StringLookup interpolatorStringLookup(final Map<String, V> map) {
    421        return new InterpolatorStringLookup(map);
    422    }
    423
    424    /**
    425     * Returns a new InterpolatorStringLookup using the {@link StringLookupFactory default lookups}.
    426     *
    427     * @param defaultStringLookup
    428     *            the default string lookup.
    429     * @return a new InterpolatorStringLookup.
    430     */
    431    public StringLookup interpolatorStringLookup(final StringLookup defaultStringLookup) {
    432        return new InterpolatorStringLookup(defaultStringLookup);
    433    }
    434
    435    /**
    436     * Returns the JavaPlatformStringLookup singleton instance. Looks up keys related to Java: Java version, JRE
    437     * version, VM version, and so on.
    438     * <p>
    439     * The lookup keys with examples are:
    440     * </p>
    441     * <ul>
    442     * <li><b>version</b>: "Java version 1.8.0_181"</li>
    443     * <li><b>runtime</b>: "Java(TM) SE Runtime Environment (build 1.8.0_181-b13) from Oracle Corporation"</li>
    444     * <li><b>vm</b>: "Java HotSpot(TM) 64-Bit Server VM (build 25.181-b13, mixed mode)"</li>
    445     * <li><b>os</b>: "Windows 10 10.0, architecture: amd64-64"</li>
    446     * <li><b>hardware</b>: "processors: 4, architecture: amd64-64, instruction sets: amd64"</li>
    447     * <li><b>locale</b>: "default locale: en_US, platform encoding: iso-8859-1"</li>
    448     * </ul>
    449     *
    450     * @return the JavaPlatformStringLookup singleton instance.
    451     */
    452    public StringLookup javaPlatformStringLookup() {
    453        return JavaPlatformStringLookup.INSTANCE;
    454    }
    455
    456    /**
    457     * Returns the LocalHostStringLookup singleton instance where the lookup key is one of:
    458     * <ul>
    459     * <li><b>name</b>: for the local host name, for example {@code EXAMPLE}.</li>
    460     * <li><b>canonical-name</b>: for the local canonical host name, for example {@code EXAMPLE.apache.org}.</li>
    461     * <li><b>address</b>: for the local host address, for example {@code 192.168.56.1}.</li>
    462     * </ul>
    463     *
    464     * @return the DateStringLookup singleton instance.
    465     */
    466    public StringLookup localHostStringLookup() {
    467        return LocalHostStringLookup.INSTANCE;
    468    }
    469
    470    /**
    471     * Returns a new map-based lookup where the request for a lookup is answered with the value for that key.
    472     *
    473     * @param <V>
    474     *            the map value type.
    475     * @param map
    476     *            the map.
    477     * @return a new MapStringLookup.
    478     */
    479    public <V> StringLookup mapStringLookup(final Map<String, V> map) {
    480        return MapStringLookup.on(map);
    481    }
    482
    483    /**
    484     * Returns the NullStringLookup singleton instance which always returns null.
    485     *
    486     * @return the NullStringLookup singleton instance.
    487     */
    488    public StringLookup nullStringLookup() {
    489        return NullStringLookup.INSTANCE;
    490    }
    491
    492    /**
    493     * Returns the PropertiesStringLookup singleton instance.
    494     * <p>
    495     * Looks up the value for the key in the format "DocumentPath:Key".
    496     * </p>
    497     * <p>
    498     * For example: "com/domain/document.properties:Key".
    499     * </p>
    500     *
    501     * @return the PropertiesStringLookup singleton instance.
    502     * @since 1.5
    503     */
    504    public StringLookup propertiesStringLookup() {
    505        return PropertiesStringLookup.INSTANCE;
    506    }
    507
    508    /**
    509     * Returns the ResourceBundleStringLookup singleton instance.
    510     * <p>
    511     * Looks up the value for a given key in the format "BundleName:BundleKey".
    512     * </p>
    513     * <p>
    514     * For example: "com.domain.messages:MyKey".
    515     * </p>
    516     *
    517     * @return the ResourceBundleStringLookup singleton instance.
    518     */
    519    public StringLookup resourceBundleStringLookup() {
    520        return ResourceBundleStringLookup.INSTANCE;
    521    }
    522
    523    /**
    524     * Returns a ResourceBundleStringLookup instance for the given bundle name.
    525     * <p>
    526     * Looks up the value for a given key in the format "BundleKey".
    527     * </p>
    528     * <p>
    529     * For example: "MyKey".
    530     * </p>
    531     *
    532     * @param bundleName
    533     *            Only lookup in this bundle.
    534     * @return a ResourceBundleStringLookup instance for the given bundle name.
    535     * @since 1.5
    536     */
    537    public StringLookup resourceBundleStringLookup(final String bundleName) {
    538        return new ResourceBundleStringLookup(bundleName);
    539    }
    540
    541    /**
    542     * Returns the ScriptStringLookup singleton instance.
    543     * <p>
    544     * Looks up the value for the key in the format "ScriptEngineName:Script".
    545     * </p>
    546     * <p>
    547     * For example: "javascript:\"HelloWorld\"".
    548     * </p>
    549     *
    550     * @return the ScriptStringLookup singleton instance.
    551     * @since 1.5
    552     */
    553    public StringLookup scriptStringLookup() {
    554        return ScriptStringLookup.INSTANCE;
    555    }
    556
    557    /**
    558     * Returns the SystemPropertyStringLookup singleton instance where the lookup key is a system property name.
    559     *
    560     * @return the SystemPropertyStringLookup singleton instance.
    561     */
    562    public StringLookup systemPropertyStringLookup() {
    563        return SystemPropertyStringLookup.INSTANCE;
    564    }
    565
    566    /**
    567     * Returns the UrlDecoderStringLookup singleton instance.
    568     * <p>
    569     * Decodes URL Strings using the UTF-8 encoding.
    570     * </p>
    571     * <p>
    572     * For example: "Hello%20World%21" becomes "Hello World!".
    573     * </p>
    574     *
    575     * @return the UrlStringLookup singleton instance.
    576     * @since 1.6
    577     */
    578    public StringLookup urlDecoderStringLookup() {
    579        return UrlDecoderStringLookup.INSTANCE;
    580    }
    581
    582    /**
    583     * Returns the UrlDecoderStringLookup singleton instance.
    584     * <p>
    585     * Decodes URL Strings using the UTF-8 encoding.
    586     * </p>
    587     * <p>
    588     * For example: "Hello World!" becomes "Hello+World%21".
    589     * </p>
    590     *
    591     * @return the UrlStringLookup singleton instance.
    592     * @since 1.6
    593     */
    594    public StringLookup urlEncoderStringLookup() {
    595        return UrlEncoderStringLookup.INSTANCE;
    596    }
    597
    598    /**
    599     * Returns the UrlStringLookup singleton instance.
    600     * <p>
    601     * Looks up the value for the key in the format "CharsetName:URL".
    602     * </p>
    603     * <p>
    604     * For example, using the HTTP scheme: "UTF-8:http://www.google.com"
    605     * </p>
    606     * <p>
    607     * For example, using the file scheme:
    608     * "UTF-8:file:///C:/somehome/commons/commons-text/src/test/resources/document.properties"
    609     * </p>
    610     *
    611     * @return the UrlStringLookup singleton instance.
    612     * @since 1.5
    613     */
    614    public StringLookup urlStringLookup() {
    615        return UrlStringLookup.INSTANCE;
    616    }
    617
    618    /**
    619     * Returns the XmlStringLookup singleton instance.
    620     * <p>
    621     * Looks up the value for the key in the format "DocumentPath:XPath".
    622     * </p>
    623     * <p>
    624     * For example: "com/domain/document.xml:/path/to/node".
    625     * </p>
    626     *
    627     * @return the XmlStringLookup singleton instance.
    628     * @since 1.5
    629     */
    630    public StringLookup xmlStringLookup() {
    631        return XmlStringLookup.INSTANCE;
    632    }
    633
    634}