svn commit: r1500472 - /commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/ListDelimiterHandler.java

[oh...@apache.org]

Author: oheger
Date: Sun Jul  7 16:45:45 2013
New Revision: 1500472

URL: http://svn.apache.org/r1500472
Log:
Added new ListDelimiterHandler interface.

This interface is part of an approach to solve the escaping issues with list
delimiters, escaped delimiters, and backslashs.

Added:
    commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/ListDelimiterHandler.java

Added: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/ListDelimiterHandler.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/ListDelimiterHandler.java?rev=1500472&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/ListDelimiterHandler.java (added)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/ListDelimiterHandler.java Sun Jul  7 16:45:45 2013
@@ -0,0 +1,109 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.configuration;
+
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.List;
+
+/**
+ * <p>
+ * Definition of an interface that controls the handling of list delimiters in
+ * configuration properties.
+ * </p>
+ * <p>
+ * {@link AbstractConfiguration} supports list delimiters in property values. If
+ * such a delimiter is found, the value actually contains multiple values and
+ * has to be split. This is useful for instance for
+ * {@link PropertiesConfiguration}: properties files that have to be compatible
+ * with the {@code java.util.Properties} class cannot have multiple occurrences
+ * of a single property key, therefore a different storage scheme for
+ * multi-valued properties is needed. A possible storage scheme could look as
+ * follows:
+ *
+ * <pre>
+ * myProperty=value1,value2,value3
+ * </pre>
+ *
+ * Here a comma is used as list delimiter. When parsing this property (and using
+ * a corresponding {@code ListDelimiterHandler} implementation) the string value
+ * is split, and three values are added for the property key.
+ * </p>
+ * <p>
+ * A {@code ListDelimiterHandler} knows how to parse and to escape property
+ * values. It is called by concrete {@code Configuration} implementations when
+ * they have to deal with properties with multiple values.
+ * </p>
+ *
+ * @version $Id: $
+ * @since 2.0
+ */
+public interface ListDelimiterHandler
+{
+    /**
+     * Parses the specified value for list delimiters and splits it if
+     * necessary. The passed in object can be either a single value or a complex
+     * one, e.g. a collection, an array, or an {@code Iterable}. It is the
+     * responsibility of this method to return an {@code Iterator} which
+     * contains all extracted values.
+     *
+     * @param value the value to be parsed
+     * @return an {@code Iterator} allowing access to all extracted values
+     */
+    Iterator<?> parse(Object value);
+
+    /**
+     * Splits the specified string at the list delimiter and returns a
+     * collection with all extracted components. A concrete implementation also
+     * has to deal with escape characters which might mask a list delimiter
+     * character at certain positions. The boolean {@code trim} flag determines
+     * whether each extracted component should be trimmed. This typically makes
+     * sense as the list delimiter may be surrounded by whitespace. However,
+     * there may be specific use cases in which automatic trimming is not
+     * desired.
+     *
+     * @param s the string to be split
+     * @param trim a flag whether each component of the string is to be trimmed
+     * @return a collection with all components extracted from the string
+     */
+    Collection<String> split(String s, boolean trim);
+
+    /**
+     * Escapes the specified single value object. This method is called for
+     * properties containing only a single value. So this method can rely on the
+     * fact that the passed in object is not a list. An implementation has to
+     * check whether the value contains list delimiter characters and - if so -
+     * escape them accordingly.
+     *
+     * @param value the value to be escaped
+     * @return the escaped value
+     */
+    Object escape(Object value);
+
+    /**
+     * Escapes all values in the given list and concatenates them to a single
+     * string. This operation is required by configurations that have to
+     * represent properties with multiple values in a single line in their
+     * external configuration representation. This may require an advanced
+     * escaping in some cases.
+     *
+     * @param values the list with all the values to be converted to a single
+     *        value
+     * @return the resulting escaped value
+     */
+    Object escapeList(List<?> values);
+}