    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 *
    025 * @since 1.3
    026 */
    027public final class StringLookupFactory {
    028
    029    /**
    030     * Defines the singleton for this class.
    031     */
    032    public static final StringLookupFactory INSTANCE = new StringLookupFactory();
    033
    034    /**
    035     * Clears any static resources.
    036     *
    037     * @since 1.5
    038     */
    039    public static void clear() {
    040        ConstantStringLookup.clear();
    041    }
    042
    043    /**
    044     * No need to build instances for now.
    045     */
    046    private StringLookupFactory() {
    047        // empty
    048    }
    049
    050    /**
    051     * The following lookups are installed:
    052     * <ul>
    053     * <li>"sys" for the {@link SystemPropertyStringLookup}.</li>
    054     * <li>"env" for the {@link EnvironmentVariableStringLookup}.</li>
    055     * <li>"java" for the {@link JavaPlatformStringLookup}.</li>
    056     * <li>"date" for the {@link DateStringLookup}.</li>
    057     * <li>"localhost" for the {@link LocalHostStringLookup} since 1.3.</li>
    058     * <li>"xml" for the {@link XmlStringLookup} since 1.5.</li>
    059     * <li>"properties" for the {@link PropertiesStringLookup} since 1.5.</li>
    060     * <li>"script" for the {@link ScriptStringLookup} since 1.5.</li>
    061     * <li>"file" for the {@link FileStringLookup} since 1.5.</li>
    062     * <li>"url" for the {@link UrlStringLookup} since 1.5.</li>
    063     * <li>"base64" for the {@link Base64StringLookup} since 1.5.</li>
    064     * <li>"urlEncode" for the {@link UrlEncoderStringLookup} since 1.5.</li>
    065     * <li>"urlDecode" for the {@link UrlDecoderStringLookup} since 1.5.</li>
    066     * <li>"const" for the {@link ConstantStringLookup} since 1.5.</li>
    067     * </ul>
    068     *
    069     * @param stringLookupMap
    070     *            the map of string lookups.
    071     * @since 1.5
    072     */
    073    public void addDefaultStringLookups(final Map<String, StringLookup> stringLookupMap) {
    074        if (stringLookupMap != null) {
    075            stringLookupMap.put("sys", SystemPropertyStringLookup.INSTANCE);
    076            stringLookupMap.put("env", EnvironmentVariableStringLookup.INSTANCE);
    077            stringLookupMap.put("java", JavaPlatformStringLookup.INSTANCE);
    078            stringLookupMap.put("date", DateStringLookup.INSTANCE);
    079            stringLookupMap.put("localhost", LocalHostStringLookup.INSTANCE);
    080            stringLookupMap.put("xml", XmlStringLookup.INSTANCE);
    081            stringLookupMap.put("properties", PropertiesStringLookup.INSTANCE);
    082            stringLookupMap.put("script", ScriptStringLookup.INSTANCE);
    083            stringLookupMap.put("file", FileStringLookup.INSTANCE);
    084            stringLookupMap.put("url", UrlStringLookup.INSTANCE);
    085            stringLookupMap.put("base64", Base64StringLookup.INSTANCE);
    086            stringLookupMap.put("urlEncode", UrlEncoderStringLookup.INSTANCE);
    087            stringLookupMap.put("urlDecode", UrlDecoderStringLookup.INSTANCE);
    088            stringLookupMap.put("const", ConstantStringLookup.INSTANCE);
    089        }
    090    }
    091
    092    /**
    093     * Returns the DateStringLookup singleton instance to format the current date with the format given in the key in a
    094     * format compatible with {@link java.text.SimpleDateFormat}.
    095     *
    096     * @return the DateStringLookup singleton instance.
    097     */
    098    public StringLookup base64StringLookup() {
    099        return Base64StringLookup.INSTANCE;
    100    }
    101
    102    /**
    103     * Returns the ConstantStringLookup singleton instance to get the value of a fully-qualified static final value.
    104     *
    105     * @return the DateStringLookup singleton instance.
    106     * @since 1.5
    107     */
    108    public StringLookup constantStringLookup() {
    109        return ConstantStringLookup.INSTANCE;
    110    }
    111
    112    /**
    113     * Returns the DateStringLookup singleton instance to format the current date with the format given in the key in a
    114     * format compatible with {@link java.text.SimpleDateFormat}.
    115     *
    116     * @return the DateStringLookup singleton instance.
    117     */
    118    public StringLookup dateStringLookup() {
    119        return DateStringLookup.INSTANCE;
    120    }
    121
    122    /**
    123     * Returns the EnvironmentVariableStringLookup singleton instance where the lookup key is an environment variable
    124     * name.
    125     *
    126     * @return the EnvironmentVariableStringLookup singleton instance.
    127     */
    128    public StringLookup environmentVariableStringLookup() {
    129        return EnvironmentVariableStringLookup.INSTANCE;
    130    }
    131
    132    /**
    133     * Returns the FileStringLookup singleton instance.
    134     * <p>
    135     * Looks up the value for the key in the format "CharsetName:Path".
    136     * </p>
    137     * <p>
    138     * For example: "UTF-8:com/domain/document.properties".
    139     * </p>
    140     *
    141     * @return the FileStringLookup singleton instance.
    142     * @since 1.5
    143     */
    144    public StringLookup fileStringLookup() {
    145        return FileStringLookup.INSTANCE;
    146    }
    147
    148    /**
    149     * Returns a new InterpolatorStringLookup.
    150     * <p>
    151     * The following lookups are used by default:
    152     * </p>
    153     * <ul>
    154     * <li>"sys" for the {@link SystemPropertyStringLookup}.</li>
    155     * <li>"env" for the {@link EnvironmentVariableStringLookup}.</li>
    156     * <li>"java" for the {@link JavaPlatformStringLookup}.</li>
    157     * <li>"date" for the {@link DateStringLookup}.</li>
    158     * <li>"localhost" for the {@link LocalHostStringLookup}, see {@link #localHostStringLookup()} for key names; since
    159     * 1.3.</li>
    160     * <li>"xml" for the {@link XmlStringLookup} since 1.5.</li>
    161     * <li>"properties" for the {@link PropertiesStringLookup} since 1.5.</li>
    162     * <li>"script" for the {@link ScriptStringLookup} since 1.5.</li>
    163     * <li>"file" for the {@link FileStringLookup} since 1.5.</li>
    164     * <li>"url" for the {@link UrlStringLookup} since 1.5.</li>
    165     * <li>"base64" for the {@link Base64StringLookup} since 1.5.</li>
    166     * <li>"urlEncode" for the {@link UrlEncoderStringLookup} since 1.5.</li>
    167     * <li>"urlDecode" for the {@link UrlDecoderStringLookup} since 1.5.</li>
    168     * <li>"const" for the {@link ConstantStringLookup} since 1.5.</li>
    169     * </ul>
    170     *
    171     * @return a new InterpolatorStringLookup.
    172     */
    173    public StringLookup interpolatorStringLookup() {
    174        return new InterpolatorStringLookup();
    175    }
    176
    177    /**
    178     * Returns a new InterpolatorStringLookup.
    179     * <p>
    180     * If {@code addDefaultLookups} is true, the following lookups are used in addition to the ones provided in
    181     * {@code stringLookupMap}:
    182     * </p>
    183     * <ul>
    184     * <li>"sys" for the {@link SystemPropertyStringLookup}.</li>
    185     * <li>"env" for the {@link EnvironmentVariableStringLookup}.</li>
    186     * <li>"java" for the {@link JavaPlatformStringLookup}.</li>
    187     * <li>"date" for the {@link DateStringLookup}.</li>
    188     * <li>"localhost" for the {@link LocalHostStringLookup}, see {@link #localHostStringLookup()} for key names; since
    189     * 1.3.</li>
    190     * <li>"xml" for the {@link XmlStringLookup} since 1.5.</li>
    191     * <li>"properties" for the {@link PropertiesStringLookup} since 1.5.</li>
    192     * <li>"script" for the {@link ScriptStringLookup} since 1.5.</li>
    193     * <li>"file" for the {@link FileStringLookup} since 1.5.</li>
    194     * <li>"url" for the {@link UrlStringLookup} since 1.5.</li>
    195     * <li>"base64" for the {@link Base64StringLookup} since 1.5.</li>
    196     * <li>"urlEncode" for the {@link UrlEncoderStringLookup} since 1.5.</li>
    197     * <li>"urlDecode" for the {@link UrlDecoderStringLookup} since 1.5.</li>
    198     * <li>"const" for the {@link ConstantStringLookup} since 1.5.</li>
    199     * </ul>
    200     *
    201     * @param stringLookupMap
    202     *            the map of string lookups.
    203     * @param defaultStringLookup
    204     *            the default string lookup.
    205     * @param addDefaultLookups
    206     *            whether to use lookups as described above.
    207     * @return a new InterpolatorStringLookup.
    208     * @since 1.4
    209     */
    210    public StringLookup interpolatorStringLookup(final Map<String, StringLookup> stringLookupMap,
    211            final StringLookup defaultStringLookup, final boolean addDefaultLookups) {
    212        return new InterpolatorStringLookup(stringLookupMap, defaultStringLookup, addDefaultLookups);
    213    }
    214
    215    /**
    216     * Returns a new InterpolatorStringLookup.
    217     * <p>
    218     * The following lookups are used by default:
    219     * </p>
    220     * <ul>
    221     * <li>"sys" for the {@link SystemPropertyStringLookup}.</li>
    222     * <li>"env" for the {@link EnvironmentVariableStringLookup}.</li>
    223     * <li>"java" for the {@link JavaPlatformStringLookup}.</li>
    224     * <li>"date" for the {@link DateStringLookup}.</li>
    225     * <li>"localhost" for the {@link LocalHostStringLookup}, see {@link #localHostStringLookup()} for key names; since
    226     * 1.3.</li>
    227     * <li>"xml" for the {@link XmlStringLookup} since 1.5.</li>
    228     * <li>"properties" for the {@link PropertiesStringLookup} since 1.5.</li>
    229     * <li>"script" for the {@link ScriptStringLookup} since 1.5.</li>
    230     * <li>"file" for the {@link FileStringLookup} since 1.5.</li>
    231     * <li>"url" for the {@link UrlStringLookup} since 1.5.</li>
    232     * <li>"base64" for the {@link Base64StringLookup} since 1.5.</li>
    233     * <li>"urlEncode" for the {@link UrlEncoderStringLookup} since 1.5.</li>
    234     * <li>"urlDecode" for the {@link UrlDecoderStringLookup} since 1.5.</li>
    235     * <li>"const" for the {@link ConstantStringLookup} since 1.5.</li>
    236     * </ul>
    237     *
    238     * @param <V>
    239     *            the value type the default string lookup's map.
    240     * @param map
    241     *            the default map for string lookups.
    242     * @return a new InterpolatorStringLookup.
    243     */
    244    public <V> StringLookup interpolatorStringLookup(final Map<String, V> map) {
    245        return new InterpolatorStringLookup(map);
    246    }
    247
    248    /**
    249     * Returns a new InterpolatorStringLookup.
    250     * <p>
    251     * The following lookups are used by default:
    252     * </p>
    253     * <ul>
    254     * <li>"sys" for the {@link SystemPropertyStringLookup}.</li>
    255     * <li>"env" for the {@link EnvironmentVariableStringLookup}.</li>
    256     * <li>"java" for the {@link JavaPlatformStringLookup}.</li>
    257     * <li>"date" for the {@link DateStringLookup}.</li>
    258     * <li>"localhost" for the {@link LocalHostStringLookup}, see {@link #localHostStringLookup()} for key names; since
    259     * 1.3.</li>
    260     * <li>"xml" for the {@link XmlStringLookup} since 1.5.</li>
    261     * <li>"properties" for the {@link PropertiesStringLookup} since 1.5.</li>
    262     * <li>"script" for the {@link ScriptStringLookup} since 1.5.</li>
    263     * <li>"file" for the {@link FileStringLookup} since 1.5.</li>
    264     * <li>"url" for the {@link UrlStringLookup} since 1.5.</li>
    265     * <li>"base64" for the {@link Base64StringLookup} since 1.5.</li>
    266     * <li>"urlEncode" for the {@link UrlEncoderStringLookup} since 1.5.</li>
    267     * <li>"urlDecode" for the {@link UrlDecoderStringLookup} since 1.5.</li>
    268     * <li>"const" for the {@link ConstantStringLookup} since 1.5.</li>
    269     * </ul>
    270     *
    271     * @param defaultStringLookup
    272     *            the default string lookup.
    273     * @return a new InterpolatorStringLookup.
    274     */
    275    public StringLookup interpolatorStringLookup(final StringLookup defaultStringLookup) {
    276        return new InterpolatorStringLookup(defaultStringLookup);
    277    }
    278
    279    /**
    280     * Returns the JavaPlatformStringLookup singleton instance. Looks up keys related to Java: Java version, JRE
    281     * version, VM version, and so on.
    282     * <p>
    283     * The lookup keys with examples are:
    284     * </p>
    285     * <ul>
    286     * <li><b>version</b>: "Java version 1.8.0_181"</li>
    287     * <li><b>runtime</b>: "Java(TM) SE Runtime Environment (build 1.8.0_181-b13) from Oracle Corporation"</li>
    288     * <li><b>vm</b>: "Java HotSpot(TM) 64-Bit Server VM (build 25.181-b13, mixed mode)"</li>
    289     * <li><b>os</b>: "Windows 10 10.0, architecture: amd64-64"</li>
    290     * <li><b>hardware</b>: "processors: 4, architecture: amd64-64, instruction sets: amd64"</li>
    291     * <li><b>locale</b>: "default locale: en_US, platform encoding: iso-8859-1"</li>
    292     * </ul>
    293     *
    294     * @return the JavaPlatformStringLookup singleton instance.
    295     */
    296    public StringLookup javaPlatformStringLookup() {
    297        return JavaPlatformStringLookup.INSTANCE;
    298    }
    299
    300    /**
    301     * Returns the LocalHostStringLookup singleton instance where the lookup key is one of:
    302     * <ul>
    303     * <li><b>name</b>: for the local host name, for example {@code EXAMPLE}.</li>
    304     * <li><b>canonical-name</b>: for the local canonical host name, for example {@code EXAMPLE.apache.org}.</li>
    305     * <li><b>address</b>: for the local host address, for example {@code 192.168.56.1}.</li>
    306     * </ul>
    307     *
    308     * @return the DateStringLookup singleton instance.
    309     */
    310    public StringLookup localHostStringLookup() {
    311        return LocalHostStringLookup.INSTANCE;
    312    }
    313
    314    /**
    315     * Returns a new map-based lookup where the request for a lookup is answered with the value for that key.
    316     *
    317     * @param <V>
    318     *            the map value type.
    319     * @param map
    320     *            the map.
    321     * @return a new MapStringLookup.
    322     */
    323    public <V> StringLookup mapStringLookup(final Map<String, V> map) {
    324        return MapStringLookup.on(map);
    325    }
    326
    327    /**
    328     * Returns the NullStringLookup singleton instance which always returns null.
    329     *
    330     * @return the NullStringLookup singleton instance.
    331     */
    332    public StringLookup nullStringLookup() {
    333        return NullStringLookup.INSTANCE;
    334    }
    335
    336    /**
    337     * Returns the PropertiesStringLookup singleton instance.
    338     * <p>
    339     * Looks up the value for the key in the format "DocumentPath:Key".
    340     * </p>
    341     * <p>
    342     * For example: "com/domain/document.properties:Key".
    343     * </p>
    344     *
    345     * @return the PropertiesStringLookup singleton instance.
    346     * @since 1.5
    347     */
    348    public StringLookup propertiesStringLookup() {
    349        return PropertiesStringLookup.INSTANCE;
    350    }
    351
    352    /**
    353     * Returns the ResourceBundleStringLookup singleton instance.
    354     * <p>
    355     * Looks up the value for a given key in the format "BundleName:BundleKey".
    356     * </p>
    357     * <p>
    358     * For example: "com.domain.messages:MyKey".
    359     * </p>
    360     *
    361     * @return the ResourceBundleStringLookup singleton instance.
    362     */
    363    public StringLookup resourceBundleStringLookup() {
    364        return ResourceBundleStringLookup.INSTANCE;
    365    }
    366
    367    /**
    368     * Returns a ResourceBundleStringLookup instance for the given bundle name.
    369     * <p>
    370     * Looks up the value for a given key in the format "BundleKey".
    371     * </p>
    372     * <p>
    373     * For example: "MyKey".
    374     * </p>
    375     *
    376     * @param bundleName
    377     *            Only lookup in this bundle.
    378     * @return a ResourceBundleStringLookup instance for the given bundle name.
    379     * @since 1.5
    380     */
    381    public StringLookup resourceBundleStringLookup(final String bundleName) {
    382        return new ResourceBundleStringLookup(bundleName);
    383    }
    384
    385    /**
    386     * Returns the ScriptStringLookup singleton instance.
    387     * <p>
    388     * Looks up the value for the key in the format "ScriptEngineName:Script".
    389     * </p>
    390     * <p>
    391     * For example: "javascript:\"HelloWorld\"".
    392     * </p>
    393     *
    394     * @return the ScriptStringLookup singleton instance.
    395     * @since 1.5
    396     */
    397    public StringLookup scriptStringLookup() {
    398        return ScriptStringLookup.INSTANCE;
    399    }
    400
    401    /**
    402     * Returns the SystemPropertyStringLookup singleton instance where the lookup key is a system property name.
    403     *
    404     * @return the SystemPropertyStringLookup singleton instance.
    405     */
    406    public StringLookup systemPropertyStringLookup() {
    407        return SystemPropertyStringLookup.INSTANCE;
    408    }
    409
    410    /**
    411     * Returns the UrlStringLookup singleton instance.
    412     * <p>
    413     * Looks up the value for the key in the format "CharsetName:URL".
    414     * </p>
    415     * <p>
    416     * For example, using the HTTP scheme: "UTF-8:http://www.google.com"
    417     * </p>
    418     * <p>
    419     * For example, using the file scheme:
    420     * "UTF-8:file:///C:/somehome/commons/commons-text/src/test/resources/document.properties"
    421     * </p>
    422     *
    423     * @return the UrlStringLookup singleton instance.
    424     * @since 1.5
    425     */
    426    public StringLookup urlStringLookup() {
    427        return UrlStringLookup.INSTANCE;
    428    }
    429
    430    /**
    431     * Returns the XmlStringLookup singleton instance.
    432     * <p>
    433     * Looks up the value for the key in the format "DocumentPath:XPath".
    434     * </p>
    435     * <p>
    436     * For example: "com/domain/document.xml:/path/to/node".
    437     * </p>
    438     *
    439     * @return the XmlStringLookup singleton instance.
    440     * @since 1.5
    441     */
    442    public StringLookup xmlStringLookup() {
    443        return XmlStringLookup.INSTANCE;
    444    }
    445
    446}