Java tutorial
/* * 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.tree; import java.util.Collection; import java.util.Iterator; import java.util.LinkedList; import java.util.List; import org.apache.commons.lang.StringUtils; /** * <p> * A default implementation of the <code>ExpressionEngine</code> interface * providing the "native"e; expression language for hierarchical * configurations. * </p> * <p> * This class implements a rather simple expression language for navigating * through a hierarchy of configuration nodes. It supports the following * operations: * </p> * <p> * <ul> * <li>Navigating from a node to one of its children using the child node * delimiter, which is by the default a dot (".").</li> * <li>Navigating from a node to one of its attributes using the attribute node * delimiter, which by default follows the XPATH like syntax * <code>[@<attributeName>]</code>.</li> * <li>If there are multiple child or attribute nodes with the same name, a * specific node can be selected using a numerical index. By default indices are * written in paranthesis.</li> * </ul> * </p> * <p> * As an example consider the following XML document: * </p> * * <pre> * <database> * <tables> * <table type="system"> * <name>users</name> * <fields> * <field> * <name>lid</name> * <type>long</name> * </field> * <field> * <name>usrName</name> * <type>java.lang.String</type> * </field> * ... * </fields> * </table> * <table> * <name>documents</name> * <fields> * <field> * <name>docid</name> * <type>long</type> * </field> * ... * </fields> * </table> * ... * </tables> * </database> * </pre> * * </p> * <p> * If this document is parsed and stored in a hierarchical configuration object, * for instance the key <code>tables.table(0).name</code> can be used to find * out the name of the first table. In opposite <code>tables.table.name</code> * would return a collection with the names of all available tables. Similarily * the key <code>tables.table(1).fields.field.name</code> returns a collection * with the names of all fields of the second table. If another index is added * after the <code>field</code> element, a single field can be accessed: * <code>tables.table(1).fields.field(0).name</code>. The key * <code>tables.table(0)[@type]</code> would select the type attribute of the * first table. * </p> * <p> * This example works with the default values for delimiters and index markers. * It is also possible to set custom values for these properties so that you can * adapt a <code>DefaultExpressionEngine</code> to your personal needs. * </p> * * @since 1.3 * @author Oliver Heger * @version $Id: DefaultExpressionEngine.java 439648 2006-09-02 20:42:10Z oheger $ */ public class DefaultExpressionEngine implements ExpressionEngine { /** Constant for the default property delimiter. */ public static final String DEFAULT_PROPERTY_DELIMITER = "."; /** Constant for the default escaped property delimiter. */ public static final String DEFAULT_ESCAPED_DELIMITER = DEFAULT_PROPERTY_DELIMITER + DEFAULT_PROPERTY_DELIMITER; /** Constant for the default attribute start marker. */ public static final String DEFAULT_ATTRIBUTE_START = "[@"; /** Constant for the default attribute end marker. */ public static final String DEFAULT_ATTRIBUTE_END = "]"; /** Constant for the default index start marker. */ public static final String DEFAULT_INDEX_START = "("; /** Constant for the default index end marker. */ public static final String DEFAULT_INDEX_END = ")"; /** Stores the property delimiter. */ private String propertyDelimiter = DEFAULT_PROPERTY_DELIMITER; /** Stores the escaped property delimiter. */ private String escapedDelimiter = DEFAULT_ESCAPED_DELIMITER; /** Stores the attribute start marker. */ private String attributeStart = DEFAULT_ATTRIBUTE_START; /** Stores the attribute end marker. */ private String attributeEnd = DEFAULT_ATTRIBUTE_END; /** Stores the index start marker. */ private String indexStart = DEFAULT_INDEX_START; /** stores the index end marker. */ private String indexEnd = DEFAULT_INDEX_END; /** * Sets the attribute end marker. * * @return the attribute end marker */ public String getAttributeEnd() { return attributeEnd; } /** * Sets the attribute end marker. * * @param attributeEnd the attribute end marker; can be <b>null</b> if no * end marker is needed */ public void setAttributeEnd(String attributeEnd) { this.attributeEnd = attributeEnd; } /** * Returns the attribute start marker. * * @return the attribute start marker */ public String getAttributeStart() { return attributeStart; } /** * Sets the attribute start marker. Attribute start and end marker are used * together to detect attributes in a property key. * * @param attributeStart the attribute start marker */ public void setAttributeStart(String attributeStart) { this.attributeStart = attributeStart; } /** * Returns the escaped property delimiter string. * * @return the escaped property delimiter */ public String getEscapedDelimiter() { return escapedDelimiter; } /** * Sets the escaped property delimiter string. With this string a delimiter * that belongs to the key of a property can be escaped. If for instance * "." is used as property delimiter, you can set the escaped * delimiter to "\." and can then escape the delimiter with a back * slash. * * @param escapedDelimiter the escaped delimiter string */ public void setEscapedDelimiter(String escapedDelimiter) { this.escapedDelimiter = escapedDelimiter; } /** * Returns the index end marker. * * @return the index end marker */ public String getIndexEnd() { return indexEnd; } /** * Sets the index end marker. * * @param indexEnd the index end marker */ public void setIndexEnd(String indexEnd) { this.indexEnd = indexEnd; } /** * Returns the index start marker. * * @return the index start marker */ public String getIndexStart() { return indexStart; } /** * Sets the index start marker. Index start and end marker are used together * to detect indices in a property key. * * @param indexStart the index start marker */ public void setIndexStart(String indexStart) { this.indexStart = indexStart; } /** * Returns the property delimiter. * * @return the property delimiter */ public String getPropertyDelimiter() { return propertyDelimiter; } /** * Sets the property delmiter. This string is used to split the parts of a * property key. * * @param propertyDelimiter the property delimiter */ public void setPropertyDelimiter(String propertyDelimiter) { this.propertyDelimiter = propertyDelimiter; } /** * Evaluates the given key and returns all matching nodes. This method * supports the syntax as described in the class comment. * * @param root the root node * @param key the key * @return a list with the matching nodes */ public List query(ConfigurationNode root, String key) { List nodes = new LinkedList(); findNodesForKey(new DefaultConfigurationKey(this, key).iterator(), root, nodes); return nodes; } /** * Determines the key of the passed in node. This implementation takes the * given parent key, adds a property delimiter, and then adds the node's * name. (For attribute nodes the attribute delimiters are used instead.) * The name of the root node is a blanc string. Note that no indices will be * returned. * * @param node the node whose key is to be determined * @param parentKey the key of this node's parent * @return the key for the given node */ public String nodeKey(ConfigurationNode node, String parentKey) { if (parentKey == null) { // this is the root node return StringUtils.EMPTY; } else { DefaultConfigurationKey key = new DefaultConfigurationKey(this, parentKey); if (node.isAttribute()) { key.appendAttribute(node.getName()); } else { key.append(node.getName(), true); } return key.toString(); } } /** * <p> * Prepares Adding the property with the specified key. * </p> * <p> * To be able to deal with the structure supported by hierarchical * configuration implementations the passed in key is of importance, * especially the indices it might contain. The following example should * clearify this: Suppose the actual node structure looks like the * following: * </p> * <p> * <pre> * tables * +-- table * +-- name = user * +-- fields * +-- field * +-- name = uid * +-- field * +-- name = firstName * ... * +-- table * +-- name = documents * +-- fields * ... * </pre> * </p> * <p> * In this example a database structure is defined, e.g. all fields of the * first table could be accessed using the key * <code>tables.table(0).fields.field.name</code>. If now properties are * to be added, it must be exactly specified at which position in the * hierarchy the new property is to be inserted. So to add a new field name * to a table it is not enough to say just * </p> * <p> * <pre> * config.addProperty("tables.table.fields.field.name", "newField"); * </pre> * </p> * <p> * The statement given above contains some ambiguity. For instance it is not * clear, to which table the new field should be added. If this method finds * such an ambiguity, it is resolved by following the last valid path. Here * this would be the last table. The same is true for the <code>field</code>; * because there are multiple fields and no explicit index is provided, a * new <code>name</code> property would be added to the last field - which * is propably not what was desired. * </p> * <p> * To make things clear explicit indices should be provided whenever * possible. In the example above the exact table could be specified by * providing an index for the <code>table</code> element as in * <code>tables.table(1).fields</code>. By specifying an index it can * also be expressed that at a given position in the configuration tree a * new branch should be added. In the example above we did not want to add * an additional <code>name</code> element to the last field of the table, * but we want a complete new <code>field</code> element. This can be * achieved by specifying an invalid index (like -1) after the element where * a new branch should be created. Given this our example would run: * </p> * <p> * <pre> * config.addProperty("tables.table(1).fields.field(-1).name", "newField"); * </pre> * </p> * <p> * With this notation it is possible to add new branches everywhere. We * could for instance create a new <code>table</code> element by * specifying * </p> * <p> * <pre> * config.addProperty("tables.table(-1).fields.field.name", "newField2"); * </pre> * </p> * <p> * (Note that because after the <code>table</code> element a new branch is * created indices in following elements are not relevant; the branch is new * so there cannot be any ambiguities.) * </p> * * @param root the root node of the nodes hierarchy * @param key the key of the new property * @return a data object with information needed for the add operation */ public NodeAddData prepareAdd(ConfigurationNode root, String key) { DefaultConfigurationKey.KeyIterator it = new DefaultConfigurationKey(this, key).iterator(); if (!it.hasNext()) { throw new IllegalArgumentException("Key for add operation must be defined!"); } NodeAddData result = new NodeAddData(); result.setParent(findLastPathNode(it, root)); while (it.hasNext()) { if (!it.isPropertyKey()) { throw new IllegalArgumentException( "Invalid key for add operation: " + key + " (Attribute key in the middle.)"); } result.addPathNode(it.currentKey()); it.next(); } result.setNewNodeName(it.currentKey()); result.setAttribute(!it.isPropertyKey()); return result; } /** * Recursive helper method for evaluating a key. This method processes all * facets of a configuration key, traverses the tree of properties and * fetches the the nodes of all matching properties. * * @param keyPart the configuration key iterator * @param node the actual node * @param nodes here the found nodes are stored */ protected void findNodesForKey(DefaultConfigurationKey.KeyIterator keyPart, ConfigurationNode node, Collection nodes) { if (!keyPart.hasNext()) { nodes.add(node); } else { String key = keyPart.nextKey(false); if (keyPart.isPropertyKey()) { processSubNodes(keyPart, node.getChildren(key), nodes); } if (keyPart.isAttribute()) { processSubNodes(keyPart, node.getAttributes(key), nodes); } } } /** * Finds the last existing node for an add operation. This method traverses * the configuration node tree along the specified key. The last existing * node on this path is returned. * * @param keyIt the key iterator * @param node the actual node * @return the last existing node on the given path */ protected ConfigurationNode findLastPathNode(DefaultConfigurationKey.KeyIterator keyIt, ConfigurationNode node) { String keyPart = keyIt.nextKey(false); if (keyIt.hasNext()) { if (!keyIt.isPropertyKey()) { // Attribute keys can only appear as last elements of the path throw new IllegalArgumentException( "Invalid path for add operation: " + "Attribute key in the middle!"); } int idx = keyIt.hasIndex() ? keyIt.getIndex() : node.getChildrenCount(keyPart) - 1; if (idx < 0 || idx >= node.getChildrenCount(keyPart)) { return node; } else { return findLastPathNode(keyIt, (ConfigurationNode) node.getChildren(keyPart).get(idx)); } } else { return node; } } /** * Called by <code>findNodesForKey()</code> to process the sub nodes of * the current node depending on the type of the current key part (children, * attributes, or both). * * @param keyPart the key part * @param subNodes a list with the sub nodes to process * @param nodes the target collection */ private void processSubNodes(DefaultConfigurationKey.KeyIterator keyPart, List subNodes, Collection nodes) { if (keyPart.hasIndex()) { if (keyPart.getIndex() >= 0 && keyPart.getIndex() < subNodes.size()) { findNodesForKey((DefaultConfigurationKey.KeyIterator) keyPart.clone(), (ConfigurationNode) subNodes.get(keyPart.getIndex()), nodes); } } else { for (Iterator it = subNodes.iterator(); it.hasNext();) { findNodesForKey((DefaultConfigurationKey.KeyIterator) keyPart.clone(), (ConfigurationNode) it.next(), nodes); } } } }