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}