Java tutorial
/* * This library is part of OpenCms - * the Open Source Content Management System * * Copyright (c) Alkacon Software GmbH (http://www.alkacon.com) * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * For further information about Alkacon Software GmbH, please see the * company website: http://www.alkacon.com * * For further information about OpenCms, please see the * project website: http://www.opencms.org * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ package org.opencms.configuration; import org.opencms.i18n.CmsEncoder; import org.opencms.util.CmsStringUtil; import java.io.FileInputStream; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; import java.io.LineNumberReader; import java.io.Reader; import java.io.UnsupportedEncodingException; import java.util.AbstractMap; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.List; import java.util.Map; import java.util.Set; import java.util.StringTokenizer; import java.util.TreeMap; import org.dom4j.Element; /** * Provides convenient access to configuration parameters.<p> * * Usually the parameters are configured in some sort of String based file, * either in an XML configuration, or in a .property file. * This wrapper allows accessing such String values directly * as <code>int</code>, <code>boolean</code> or other data types, without * worrying about the type conversion.<p> * * It can also read a configuration from a special property file format, * which is explained here: * * <ul> * <li> * Each parameter in the file has the syntax <code>key = value</code> * </li> * <li> * The <i>key</i> may use any character but the equal sign '='. * </li> * <li> * <i>value</i> may be separated on different lines if a backslash * is placed at the end of the line that continues below. * </li> * <li> * If <i>value</i> is a list of strings, each token is separated * by a comma ','. * </li> * <li> * Commas in each token are escaped placing a backslash right before * the comma. * </li> * <li> * Backslashes are escaped by using two consecutive backslashes i.e. \\. * Note: Unlike in regular Java properties files, you don't need to escape Backslashes. * </li> * <li> * If a <i>key</i> is used more than once, the values are appended * as if they were on the same line separated with commas. * </li> * <li> * Blank lines and lines starting with character '#' are skipped. * </li> * </ul> * * Here is an example of a valid parameter properties file:<p> * * <pre> * # lines starting with # are comments * * # This is the simplest property * key = value * * # A long property may be separated on multiple lines * longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \ * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa * * # This is a property with many tokens * tokens_on_a_line = first token, second token * * # This sequence generates exactly the same result * tokens_on_multiple_lines = first token * tokens_on_multiple_lines = second token * * # commas may be escaped in tokens * commas.escaped = Hi\, what'up? * </pre> */ public class CmsParameterConfiguration extends AbstractMap<String, String> { /** * Used to read parameter lines from a property file.<p> * * The lines do not terminate with new-line chars but rather when there is no * backslash sign a the end of the line. This is used to * concatenate multiple lines for readability in the input file.<p> */ protected static class ParameterReader extends LineNumberReader { /** * Constructor.<p> * * @param reader a reader */ public ParameterReader(Reader reader) { super(reader); } /** * Reads a parameter line.<p> * * @return the parameter line read * * @throws IOException in case of IO errors */ public String readParameter() throws IOException { StringBuffer buffer = new StringBuffer(); String line = readLine(); while (line != null) { line = line.trim(); if ((line.length() != 0) && (line.charAt(0) != '#')) { if (endsWithSlash(line)) { line = line.substring(0, line.length() - 1); buffer.append(line); } else { buffer.append(line); return buffer.toString(); // normal method end } } line = readLine(); } return null; // EOF reached } } /** * This class divides property value into tokens separated by ",".<p> * * Commas in the property value that are wanted * can be escaped using the backslash in front like this "\,". */ protected static class ParameterTokenizer extends StringTokenizer { /** The property delimiter used while parsing (a comma). */ static final String COMMA = ","; /** * Constructor.<p> * * @param string the String to break into tokens */ public ParameterTokenizer(String string) { super(string, COMMA); } /** * Returns the next token.<p> * * @return the next token */ @Override public String nextToken() { StringBuffer buffer = new StringBuffer(); while (hasMoreTokens()) { String token = super.nextToken(); if (endsWithSlash(token)) { buffer.append(token.substring(0, token.length() - 1)); buffer.append(COMMA); } else { buffer.append(token); break; } } return buffer.toString().trim(); } } /** * An empty, immutable parameter configuration.<p> */ public static final CmsParameterConfiguration EMPTY_PARAMETERS = new CmsParameterConfiguration( Collections.<String, String>emptyMap(), Collections.<String, Object>emptyMap()); /** The parsed map of parameters where the Strings may have become Objects. */ private Map<String, Object> m_configurationObjects; /** The original map of parameters that contains only String values. */ private Map<String, String> m_configurationStrings; /** * Creates an empty parameter configuration.<p> */ public CmsParameterConfiguration() { this(new TreeMap<String, String>(), new TreeMap<String, Object>()); } /** * Creates a parameter configuration from an input stream.<p> * * @param in the input stream to create the parameter configuration from * * @throws IOException in case of errors loading the parameters from the input stream */ public CmsParameterConfiguration(InputStream in) throws IOException { this(); load(in); } /** * Creates a parameter configuration from a Map of Strings.<p> * * @param configuration the map of Strings to create the parameter configuration from */ public CmsParameterConfiguration(Map<String, String> configuration) { this(); for (String key : configuration.keySet()) { String value = configuration.get(key); add(key, value); } } /** * Creates a parameter wrapper by loading the parameters from the specified property file.<p> * * @param file the path of the file to load * * @throws IOException in case of errors loading the parameters from the specified property file */ public CmsParameterConfiguration(String file) throws IOException { this(); FileInputStream in = null; try { in = new FileInputStream(file); load(in); } finally { try { if (in != null) { in.close(); } } catch (IOException ex) { // ignore error on close() only } } } /** * Creates a parameter configuration from the given maps.<p> * * @param strings the String map * @param objects the object map */ private CmsParameterConfiguration(Map<String, String> strings, Map<String, Object> objects) { m_configurationStrings = strings; m_configurationObjects = objects; } /** * Returns an unmodifiable version of this parameter configuration.<p> * * @param original the configuration to make unmodifiable * * @return an unmodifiable version of this parameter configuration */ public static CmsParameterConfiguration unmodifiableVersion(CmsParameterConfiguration original) { return new CmsParameterConfiguration(Collections.unmodifiableMap(original.m_configurationStrings), original.m_configurationObjects); } /** * Counts the number of successive times 'ch' appears in the * 'line' before the position indicated by the 'index'.<p> * * @param line the line to count * @param index the index position to start * @param ch the character to count * * @return the number of successive times 'ch' appears in the 'line' * before the position indicated by the 'index' */ protected static int countPreceding(String line, int index, char ch) { int i; for (i = index - 1; i >= 0; i--) { if (line.charAt(i) != ch) { break; } } return index - 1 - i; } /** * Checks if the line ends with odd number of backslashes.<p> * * @param line the line to check * * @return <code>true</code> if the line ends with odd number of backslashes */ protected static boolean endsWithSlash(String line) { if (!line.endsWith("\\")) { return false; } return ((countPreceding(line, line.length() - 1, '\\') % 2) == 0); } /** * Replaces escaped char sequences in the input value.<p> * * @param value the value to unescape * * @return the unescaped String */ protected static String unescape(String value) { value = CmsStringUtil.substitute(value, "\\,", ","); value = CmsStringUtil.substitute(value, "\\=", "="); value = CmsStringUtil.substitute(value, "\\\\", "\\"); return value; } /** * Add a parameter to this configuration.<p> * * If the parameter already exists then the value will be added * to the existing configuration entry and a List will be created for the values.<p> * * String values separated by a comma "," will NOT be tokenized when this * method is used. To create a List of String values for a parameter, call this method * multiple times with the same parameter name.<p> * * @param key the parameter to add * @param value the value to add */ public void add(String key, String value) { add(key, value, false); } /** * Serializes this parameter configuration for the OpenCms XML configuration.<p> * * For each parameter, a XML node like this<br> * <code> * <param name="theName">theValue</param> * </code><br> * is generated and appended to the provided parent node.<p> * * @param parentNode the parent node where the parameter nodes are appended to * * @return the parent node */ public Element appendToXml(Element parentNode) { return appendToXml(parentNode, null); } /** * Serializes this parameter configuration for the OpenCms XML configuration.<p> * * For each parameter, a XML node like this<br> * <code> * <param name="theName">theValue</param> * </code><br> * is generated and appended to the provided parent node.<p> * * @param parentNode the parent node where the parameter nodes are appended to * @param parametersToIgnore if not <code>null</code>, * all parameters in this list are not written to the XML * * @return the parent node */ public Element appendToXml(Element parentNode, List<String> parametersToIgnore) { for (Map.Entry<String, Object> entry : m_configurationObjects.entrySet()) { String name = entry.getKey(); // check if the parameter should be ignored if ((parametersToIgnore == null) || !parametersToIgnore.contains(name)) { // now serialize the parameter name and value Object value = entry.getValue(); if (value instanceof List) { @SuppressWarnings("unchecked") List<String> values = (List<String>) value; for (String strValue : values) { // use the original String as value Element paramNode = parentNode.addElement(I_CmsXmlConfiguration.N_PARAM); // set the name attribute paramNode.addAttribute(I_CmsXmlConfiguration.A_NAME, name); // set the text of <param> node paramNode.addText(strValue); } } else { // use the original String as value String strValue = get(name); Element paramNode = parentNode.addElement(I_CmsXmlConfiguration.N_PARAM); // set the name attribute paramNode.addAttribute(I_CmsXmlConfiguration.A_NAME, name); // set the text of <param> node paramNode.addText(strValue); } } } return parentNode; } /** * @see java.util.Map#clear() */ @Override public void clear() { m_configurationStrings.clear(); m_configurationObjects.clear(); } /** * @see java.util.Map#containsKey(java.lang.Object) */ @Override public boolean containsKey(Object key) { return m_configurationStrings.containsKey(key); } /** * @see java.util.Map#containsValue(java.lang.Object) */ @Override public boolean containsValue(Object value) { return m_configurationStrings.containsValue(value) || m_configurationObjects.containsValue(value); } /** * @see java.util.Map#entrySet() */ @Override public Set<java.util.Map.Entry<String, String>> entrySet() { return m_configurationStrings.entrySet(); } /** * Returns the String associated with the given parameter.<p> * * @param key the parameter to look up the value for * * @return the String associated with the given parameter */ @Override public String get(Object key) { return m_configurationStrings.get(key); } /** * Returns the boolean associated with the given parameter, * or the default value in case there is no boolean value for this parameter.<p> * * @param key the parameter to look up the value for * @param defaultValue the default value * * @return the boolean associated with the given parameter, * or the default value in case there is no boolean value for this parameter */ public boolean getBoolean(String key, boolean defaultValue) { Object value = m_configurationObjects.get(key); if (value instanceof Boolean) { return ((Boolean) value).booleanValue(); } else if (value instanceof String) { Boolean b = Boolean.valueOf((String) value); m_configurationObjects.put(key, b); return b.booleanValue(); } else { return defaultValue; } } /** * Returns the integer associated with the given parameter, * or the default value in case there is no integer value for this parameter.<p> * * @param key the parameter to look up the value for * @param defaultValue the default value * * @return the integer associated with the given parameter, * or the default value in case there is no integer value for this parameter */ public int getInteger(String key, int defaultValue) { Object value = m_configurationObjects.get(key); if (value instanceof Integer) { return ((Integer) value).intValue(); } else if (value instanceof String) { Integer i = new Integer((String) value); m_configurationObjects.put(key, i); return i.intValue(); } else { return defaultValue; } } /** * Returns the List of Strings associated with the given parameter, * or an empty List in case there is no List of Strings for this parameter.<p> * * The list returned is a copy of the internal data of this object, and as * such you may alter it freely.<p> * * @param key the parameter to look up the value for * * @return the List of Strings associated with the given parameter, * or an empty List in case there is no List of Strings for this parameter */ public List<String> getList(String key) { return getList(key, null); } /** * Returns the List of Strings associated with the given parameter, * or the default value in case there is no List of Strings for this parameter.<p> * * The list returned is a copy of the internal data of this object, and as * such you may alter it freely.<p> * * @param key the parameter to look up the value for * @param defaultValue the default value * * @return the List of Strings associated with the given parameter, * or the default value in case there is no List of Strings for this parameter */ public List<String> getList(String key, List<String> defaultValue) { Object value = m_configurationObjects.get(key); if (value instanceof List) { @SuppressWarnings("unchecked") List<String> result = (List<String>) value; return new ArrayList<String>(result); } else if (value instanceof String) { List<String> values = new ArrayList<String>(1); values.add((String) value); m_configurationObjects.put(key, values); return values; } else { if (defaultValue == null) { return new ArrayList<String>(); } else { return defaultValue; } } } /** * Returns the raw Object associated with the given parameter, * or <code>null</code> in case there is no Object for this parameter.<p> * * @param key the parameter to look up the value for * * @return the raw Object associated with the given parameter, * or <code>null</code> in case there is no Object for this parameter.<p> */ public Object getObject(String key) { return m_configurationObjects.get(key); } /** * Returns the String associated with the given parameter, * or the given default value in case there is no value for this parameter.<p> * * @param key the parameter to look up the value for * @param defaultValue the default value * * @return the String associated with the given parameter, * or the given default value in case there is no value for this parameter.<p> */ public String getString(String key, String defaultValue) { String result = get(key); return result == null ? defaultValue : result; } /** * @see java.util.Map#hashCode() */ @Override public int hashCode() { return m_configurationStrings.hashCode(); } /** * @see java.util.Map#keySet() */ @Override public Set<String> keySet() { return m_configurationStrings.keySet(); } /** * Load the parameters from the given input stream, which must be in property file format.<p> * * @param input the stream to load the input from * * @throws IOException in case of IO errors reading from the stream */ public void load(InputStream input) throws IOException { ParameterReader reader = null; try { reader = new ParameterReader(new InputStreamReader(input, CmsEncoder.ENCODING_ISO_8859_1)); } catch (UnsupportedEncodingException ex) { reader = new ParameterReader(new InputStreamReader(input)); } while (true) { String line = reader.readParameter(); if (line == null) { return; // EOF } int equalSign = line.indexOf('='); if (equalSign > 0) { String key = line.substring(0, equalSign).trim(); String value = line.substring(equalSign + 1).trim(); if (CmsStringUtil.isEmptyOrWhitespaceOnly(value)) { continue; } add(key, value, true); } } } /** * Set a parameter for this configuration.<p> * * If the parameter already exists then the existing value will be replaced.<p> * * @param key the parameter to set * @param value the value to set * * @return the previous String value from the parameter map */ @Override public String put(String key, String value) { String result = remove(key); add(key, value, false); return result; } /** * Merges this parameter configuration with the provided other parameter configuration.<p> * * The difference form a simple <code>Map<String, String></code> is that for the parameter * configuration, the values of the keys in both maps are merged and kept in the Object store * as a List.<p> * * As result, <code>this</code> configuration will be altered, the other configuration will * stay unchanged.<p> * * @param other the other parameter configuration to merge this configuration with */ @Override public void putAll(Map<? extends String, ? extends String> other) { for (String key : other.keySet()) { boolean tokenize = false; if (other instanceof CmsParameterConfiguration) { Object o = ((CmsParameterConfiguration) other).getObject(key); if (o instanceof List) { tokenize = true; } } add(key, other.get(key), tokenize); } } /** * Removes a parameter from this configuration. * * @param key the parameter to remove */ @Override public String remove(Object key) { String result = m_configurationStrings.remove(key); m_configurationObjects.remove(key); return result; } /** * @see java.util.Map#toString() */ @Override public String toString() { return m_configurationStrings.toString(); } /** * @see java.util.Map#values() */ @Override public Collection<String> values() { return m_configurationStrings.values(); } /** * Add a parameter to this configuration.<p> * * If the parameter already exists then the value will be added * to the existing configuration entry and a List will be created for the values.<p> * * @param key the parameter to add * @param value the value to add * @param tokenize decides if a String value should be tokenized or nor */ private void add(String key, String value, boolean tokenize) { if (tokenize && (value.indexOf(ParameterTokenizer.COMMA) > 0)) { // token contains commas, so must be split apart then added ParameterTokenizer tokenizer = new ParameterTokenizer(value); while (tokenizer.hasMoreTokens()) { String token = tokenizer.nextToken(); addInternal(key, unescape(token)); } } else { // token contains no commas, so can be simply added addInternal(key, value); } } /** * Adds a parameter, parsing the value if required.<p> * * @param key the parameter to add * @param value the value of the parameter */ private void addInternal(String key, String value) { Object currentObj = m_configurationObjects.get(key); String currentStr = get(key); if (currentObj instanceof String) { // one object already in map - convert it to a list List<String> values = new ArrayList<String>(2); values.add(currentStr); values.add(value); m_configurationObjects.put(key, values); m_configurationStrings.put(key, currentStr + ParameterTokenizer.COMMA + value); } else if (currentObj instanceof List) { // already a list - just add the new token @SuppressWarnings("unchecked") List<String> list = (List<String>) currentObj; list.add(value); m_configurationStrings.put(key, currentStr + ParameterTokenizer.COMMA + value); } else { m_configurationObjects.put(key, value); m_configurationStrings.put(key, value); } } }