    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 */
    017package org.apache.commons.configuration2.tree;
    018
    019import java.util.Iterator;
    020import java.util.NoSuchElementException;
    021
    022import org.apache.commons.lang3.StringUtils;
    023
    024/**
    025 * <p>
    026 * A simple class that supports creation of and iteration on configuration keys
    027 * supported by a {@link DefaultExpressionEngine} object.
    028 * </p>
    029 * <p>
    030 * For key creation the class works similar to a StringBuffer: There are several
    031 * {@code appendXXXX()} methods with which single parts of a key can be
    032 * constructed. All these methods return a reference to the actual object so
    033 * they can be written in a chain. When using this methods the exact syntax for
    034 * keys need not be known.
    035 * </p>
    036 * <p>
    037 * This class also defines a specialized iterator for configuration keys. With
    038 * such an iterator a key can be tokenized into its single parts. For each part
    039 * it can be checked whether it has an associated index.
    040 * </p>
    041 * <p>
    042 * Instances of this class are always associated with an instance of
    043 * {@link DefaultExpressionEngine}, from which the current
    044 * delimiters are obtained. So key creation and parsing is specific to this
    045 * associated expression engine.
    046 * </p>
    047 *
    048 * @since 1.3
    049 * @author <a
    050 * href="http://commons.apache.org/configuration/team-list.html">Commons
    051 * Configuration team</a>
    052 * @version $Id: DefaultConfigurationKey.java 1842194 2018-09-27 22:24:23Z ggregory $
    053 */
    054public class DefaultConfigurationKey
    055{
    056    /** Constant for the initial StringBuffer size. */
    057    private static final int INITIAL_SIZE = 32;
    058
    059    /** Stores a reference to the associated expression engine. */
    060    private final DefaultExpressionEngine expressionEngine;
    061
    062    /** Holds a buffer with the so far created key. */
    063    private final StringBuilder keyBuffer;
    064
    065    /**
    066     * Creates a new instance of {@code DefaultConfigurationKey} and sets
    067     * the associated expression engine.
    068     *
    069     * @param engine the expression engine (must not be <b>null</b>)
    070     * @throws IllegalArgumentException if the expression engine is <b>null</b>
    071     */
    072    public DefaultConfigurationKey(final DefaultExpressionEngine engine)
    073    {
    074        this(engine, null);
    075    }
    076
    077    /**
    078     * Creates a new instance of {@code DefaultConfigurationKey} and sets the
    079     * associated expression engine and an initial key.
    080     *
    081     * @param engine the expression engine (must not be <b>null</b>)
    082     * @param key the key to be wrapped
    083     * @throws IllegalArgumentException if the expression engine is <b>null</b>
    084     */
    085    public DefaultConfigurationKey(final DefaultExpressionEngine engine, final String key)
    086    {
    087        if (engine == null)
    088        {
    089            throw new IllegalArgumentException(
    090                    "Expression engine must not be null!");
    091        }
    092        expressionEngine = engine;
    093        if (key != null)
    094        {
    095            keyBuffer = new StringBuilder(trim(key));
    096        }
    097        else
    098        {
    099            keyBuffer = new StringBuilder(INITIAL_SIZE);
    100        }
    101    }
    102
    103    /**
    104     * Returns the associated default expression engine.
    105     *
    106     * @return the associated expression engine
    107     */
    108    public DefaultExpressionEngine getExpressionEngine()
    109    {
    110        return expressionEngine;
    111    }
    112
    113    /**
    114     * Appends the name of a property to this key. If necessary, a property
    115     * delimiter will be added. If the boolean argument is set to <b>true</b>,
    116     * property delimiters contained in the property name will be escaped.
    117     *
    118     * @param property the name of the property to be added
    119     * @param escape a flag if property delimiters in the passed in property name
    120     * should be escaped
    121     * @return a reference to this object
    122     */
    123    public DefaultConfigurationKey append(final String property, final boolean escape)
    124    {
    125        String key;
    126        if (escape && property != null)
    127        {
    128            key = escapeDelimiters(property);
    129        }
    130        else
    131        {
    132            key = property;
    133        }
    134        key = trim(key);
    135
    136        if (keyBuffer.length() > 0 && !isAttributeKey(property)
    137                && key.length() > 0)
    138        {
    139            keyBuffer.append(getSymbols().getPropertyDelimiter());
    140        }
    141
    142        keyBuffer.append(key);
    143        return this;
    144    }
    145
    146    /**
    147     * Appends the name of a property to this key. If necessary, a property
    148     * delimiter will be added. Property delimiters in the given string will not
    149     * be escaped.
    150     *
    151     * @param property the name of the property to be added
    152     * @return a reference to this object
    153     */
    154    public DefaultConfigurationKey append(final String property)
    155    {
    156        return append(property, false);
    157    }
    158
    159    /**
    160     * Appends an index to this configuration key.
    161     *
    162     * @param index the index to be appended
    163     * @return a reference to this object
    164     */
    165    public DefaultConfigurationKey appendIndex(final int index)
    166    {
    167        keyBuffer.append(getSymbols().getIndexStart());
    168        keyBuffer.append(index);
    169        keyBuffer.append(getSymbols().getIndexEnd());
    170        return this;
    171    }
    172
    173    /**
    174     * Appends an attribute to this configuration key.
    175     *
    176     * @param attr the name of the attribute to be appended
    177     * @return a reference to this object
    178     */
    179    public DefaultConfigurationKey appendAttribute(final String attr)
    180    {
    181        keyBuffer.append(constructAttributeKey(attr));
    182        return this;
    183    }
    184
    185    /**
    186     * Returns the actual length of this configuration key.
    187     *
    188     * @return the length of this key
    189     */
    190    public int length()
    191    {
    192        return keyBuffer.length();
    193    }
    194
    195    /**
    196     * Sets the new length of this configuration key. With this method it is
    197     * possible to truncate the key, e.g. to return to a state prior calling
    198     * some {@code append()} methods. The semantic is the same as the
    199     * {@code setLength()} method of {@code StringBuilder}.
    200     *
    201     * @param len the new length of the key
    202     */
    203    public void setLength(final int len)
    204    {
    205        keyBuffer.setLength(len);
    206    }
    207    /**
    208     * Returns a configuration key object that is initialized with the part
    209     * of the key that is common to this key and the passed in key.
    210     *
    211     * @param other the other key
    212     * @return a key object with the common key part
    213     */
    214    public DefaultConfigurationKey commonKey(final DefaultConfigurationKey other)
    215    {
    216        if (other == null)
    217        {
    218            throw new IllegalArgumentException("Other key must no be null!");
    219        }
    220
    221        final DefaultConfigurationKey result = new DefaultConfigurationKey(getExpressionEngine());
    222        final KeyIterator it1 = iterator();
    223        final KeyIterator it2 = other.iterator();
    224
    225        while (it1.hasNext() && it2.hasNext() && partsEqual(it1, it2))
    226        {
    227            if (it1.isAttribute())
    228            {
    229                result.appendAttribute(it1.currentKey());
    230            }
    231            else
    232            {
    233                result.append(it1.currentKey());
    234                if (it1.hasIndex)
    235                {
    236                    result.appendIndex(it1.getIndex());
    237                }
    238            }
    239        }
    240
    241        return result;
    242    }
    243
    244    /**
    245     * Returns the &quot;difference key&quot; to a given key. This value
    246     * is the part of the passed in key that differs from this key. There is
    247     * the following relation:
    248     * {@code other = key.commonKey(other) + key.differenceKey(other)}
    249     * for an arbitrary configuration key {@code key}.
    250     *
    251     * @param other the key for which the difference is to be calculated
    252     * @return the difference key
    253     */
    254    public DefaultConfigurationKey differenceKey(final DefaultConfigurationKey other)
    255    {
    256        final DefaultConfigurationKey common = commonKey(other);
    257        final DefaultConfigurationKey result = new DefaultConfigurationKey(getExpressionEngine());
    258
    259        if (common.length() < other.length())
    260        {
    261            final String k = other.toString().substring(common.length());
    262            // skip trailing delimiters
    263            int i = 0;
    264            while (i < k.length()
    265                    && String.valueOf(k.charAt(i)).equals(
    266                            getSymbols().getPropertyDelimiter()))
    267            {
    268                i++;
    269            }
    270
    271            if (i < k.length())
    272            {
    273                result.append(k.substring(i));
    274            }
    275        }
    276
    277        return result;
    278    }
    279
    280    /**
    281     * Checks if two {@code ConfigurationKey} objects are equal. Two instances
    282     * of this class are considered equal if they have the same content (i.e.
    283     * their internal string representation is equal). The expression engine
    284     * property is not taken into account.
    285     *
    286     * @param obj the object to compare
    287     * @return a flag if both objects are equal
    288     */
    289    @Override
    290    public boolean equals(final Object obj)
    291    {
    292        if (this == obj)
    293        {
    294            return true;
    295        }
    296        if (!(obj instanceof DefaultConfigurationKey))
    297        {
    298            return false;
    299        }
    300
    301        final DefaultConfigurationKey c = (DefaultConfigurationKey) obj;
    302        return keyBuffer.toString().equals(c.toString());
    303    }
    304
    305    /**
    306     * Returns the hash code for this object.
    307     *
    308     * @return the hash code
    309     */
    310    @Override
    311    public int hashCode()
    312    {
    313        return String.valueOf(keyBuffer).hashCode();
    314    }
    315
    316    /**
    317     * Returns a string representation of this object. This is the configuration
    318     * key as a plain string.
    319     *
    320     * @return a string for this object
    321     */
    322    @Override
    323    public String toString()
    324    {
    325        return keyBuffer.toString();
    326    }
    327
    328    /**
    329     * Tests if the specified key represents an attribute according to the
    330     * current expression engine.
    331     *
    332     * @param key the key to be checked
    333     * @return <b>true</b> if this is an attribute key, <b>false</b> otherwise
    334     */
    335    public boolean isAttributeKey(final String key)
    336    {
    337        if (key == null)
    338        {
    339            return false;
    340        }
    341
    342        return key.startsWith(getSymbols().getAttributeStart())
    343                && (getSymbols().getAttributeEnd() == null || key
    344                        .endsWith(getSymbols().getAttributeEnd()));
    345    }
    346
    347    /**
    348     * Decorates the given key so that it represents an attribute. Adds special
    349     * start and end markers. The passed in string will be modified only if does
    350     * not already represent an attribute.
    351     *
    352     * @param key the key to be decorated
    353     * @return the decorated attribute key
    354     */
    355    public String constructAttributeKey(final String key)
    356    {
    357        if (key == null)
    358        {
    359            return StringUtils.EMPTY;
    360        }
    361        if (isAttributeKey(key))
    362        {
    363            return key;
    364        }
    365        final StringBuilder buf = new StringBuilder();
    366        buf.append(getSymbols().getAttributeStart()).append(key);
    367        if (getSymbols().getAttributeEnd() != null)
    368        {
    369            buf.append(getSymbols().getAttributeEnd());
    370        }
    371        return buf.toString();
    372    }
    373
    374    /**
    375     * Extracts the name of the attribute from the given attribute key. This
    376     * method removes the attribute markers - if any - from the specified key.
    377     *
    378     * @param key the attribute key
    379     * @return the name of the corresponding attribute
    380     */
    381    public String attributeName(final String key)
    382    {
    383        return isAttributeKey(key) ? removeAttributeMarkers(key) : key;
    384    }
    385
    386    /**
    387     * Removes leading property delimiters from the specified key.
    388     *
    389     * @param key the key
    390     * @return the key with removed leading property delimiters
    391     */
    392    public String trimLeft(final String key)
    393    {
    394        if (key == null)
    395        {
    396            return StringUtils.EMPTY;
    397        }
    398        String result = key;
    399        while (hasLeadingDelimiter(result))
    400        {
    401            result = result.substring(getSymbols()
    402                    .getPropertyDelimiter().length());
    403        }
    404        return result;
    405    }
    406
    407    /**
    408     * Removes trailing property delimiters from the specified key.
    409     *
    410     * @param key the key
    411     * @return the key with removed trailing property delimiters
    412     */
    413    public String trimRight(final String key)
    414    {
    415        if (key == null)
    416        {
    417            return StringUtils.EMPTY;
    418        }
    419        String result = key;
    420        while (hasTrailingDelimiter(result))
    421        {
    422            result = result
    423                    .substring(0, result.length()
    424                            - getSymbols().getPropertyDelimiter()
    425                                    .length());
    426        }
    427        return result;
    428    }
    429
    430    /**
    431     * Removes delimiters at the beginning and the end of the specified key.
    432     *
    433     * @param key the key
    434     * @return the key with removed property delimiters
    435     */
    436    public String trim(final String key)
    437    {
    438        return trimRight(trimLeft(key));
    439    }
    440
    441    /**
    442     * Returns an iterator for iterating over the single components of this
    443     * configuration key.
    444     *
    445     * @return an iterator for this key
    446     */
    447    public KeyIterator iterator()
    448    {
    449        return new KeyIterator();
    450    }
    451
    452    /**
    453     * Helper method that checks if the specified key ends with a property
    454     * delimiter.
    455     *
    456     * @param key the key to check
    457     * @return a flag if there is a trailing delimiter
    458     */
    459    private boolean hasTrailingDelimiter(final String key)
    460    {
    461        return key.endsWith(getSymbols().getPropertyDelimiter())
    462                && (getSymbols().getEscapedDelimiter() == null || !key
    463                        .endsWith(getSymbols().getEscapedDelimiter()));
    464    }
    465
    466    /**
    467     * Helper method that checks if the specified key starts with a property
    468     * delimiter.
    469     *
    470     * @param key the key to check
    471     * @return a flag if there is a leading delimiter
    472     */
    473    private boolean hasLeadingDelimiter(final String key)
    474    {
    475        return key.startsWith(getSymbols().getPropertyDelimiter())
    476                && (getSymbols().getEscapedDelimiter() == null || !key
    477                        .startsWith(getSymbols().getEscapedDelimiter()));
    478    }
    479
    480    /**
    481     * Helper method for removing attribute markers from a key.
    482     *
    483     * @param key the key
    484     * @return the key with removed attribute markers
    485     */
    486    private String removeAttributeMarkers(final String key)
    487    {
    488        return key
    489                .substring(
    490                        getSymbols().getAttributeStart().length(),
    491                        key.length()
    492                                - ((getSymbols().getAttributeEnd() != null) ? getSymbols()
    493                                        .getAttributeEnd().length()
    494                                        : 0));
    495    }
    496
    497    /**
    498     * Unescapes the delimiters in the specified string.
    499     *
    500     * @param key the key to be unescaped
    501     * @return the unescaped key
    502     */
    503    private String unescapeDelimiters(final String key)
    504    {
    505        return (getSymbols().getEscapedDelimiter() == null) ? key
    506                : StringUtils.replace(key, getSymbols()
    507                        .getEscapedDelimiter(), getSymbols()
    508                        .getPropertyDelimiter());
    509    }
    510
    511    /**
    512     * Returns the symbols object from the associated expression engine.
    513     *
    514     * @return the {@code DefaultExpressionEngineSymbols}
    515     */
    516    private DefaultExpressionEngineSymbols getSymbols()
    517    {
    518        return getExpressionEngine().getSymbols();
    519    }
    520
    521    /**
    522     * Escapes the delimiters in the specified string.
    523     *
    524     * @param key the key to be escaped
    525     * @return the escaped key
    526     */
    527    private String escapeDelimiters(final String key)
    528    {
    529        return (getSymbols().getEscapedDelimiter() == null || key
    530                .indexOf(getSymbols().getPropertyDelimiter()) < 0) ? key
    531                : StringUtils.replace(key, getSymbols()
    532                        .getPropertyDelimiter(), getSymbols()
    533                        .getEscapedDelimiter());
    534    }
    535
    536    /**
    537     * Helper method for comparing two key parts.
    538     *
    539     * @param it1 the iterator with the first part
    540     * @param it2 the iterator with the second part
    541     * @return a flag if both parts are equal
    542     */
    543    private static boolean partsEqual(final KeyIterator it1, final KeyIterator it2)
    544    {
    545        return it1.nextKey().equals(it2.nextKey())
    546                && it1.getIndex() == it2.getIndex()
    547                && it1.isAttribute() == it2.isAttribute();
    548    }
    549
    550    /**
    551     * A specialized iterator class for tokenizing a configuration key. This
    552     * class implements the normal iterator interface. In addition it provides
    553     * some specific methods for configuration keys.
    554     */
    555    public class KeyIterator implements Iterator<Object>, Cloneable
    556    {
    557        /** Stores the current key name. */
    558        private String current;
    559
    560        /** Stores the start index of the actual token. */
    561        private int startIndex;
    562
    563        /** Stores the end index of the actual token. */
    564        private int endIndex;
    565
    566        /** Stores the index of the actual property if there is one. */
    567        private int indexValue;
    568
    569        /** Stores a flag if the actual property has an index. */
    570        private boolean hasIndex;
    571
    572        /** Stores a flag if the actual property is an attribute. */
    573        private boolean attribute;
    574
    575        /**
    576         * Returns the next key part of this configuration key. This is a short
    577         * form of {@code nextKey(false)}.
    578         *
    579         * @return the next key part
    580         */
    581        public String nextKey()
    582        {
    583            return nextKey(false);
    584        }
    585
    586        /**
    587         * Returns the next key part of this configuration key. The boolean
    588         * parameter indicates wheter a decorated key should be returned. This
    589         * affects only attribute keys: if the parameter is <b>false</b>, the
    590         * attribute markers are stripped from the key; if it is <b>true</b>,
    591         * they remain.
    592         *
    593         * @param decorated a flag if the decorated key is to be returned
    594         * @return the next key part
    595         */
    596        public String nextKey(final boolean decorated)
    597        {
    598            if (!hasNext())
    599            {
    600                throw new NoSuchElementException("No more key parts!");
    601            }
    602
    603            hasIndex = false;
    604            indexValue = -1;
    605            final String key = findNextIndices();
    606
    607            current = key;
    608            hasIndex = checkIndex(key);
    609            attribute = checkAttribute(current);
    610
    611            return currentKey(decorated);
    612        }
    613
    614        /**
    615         * Checks if there is a next element.
    616         *
    617         * @return a flag if there is a next element
    618         */
    619        @Override
    620        public boolean hasNext()
    621        {
    622            return endIndex < keyBuffer.length();
    623        }
    624
    625        /**
    626         * Returns the next object in the iteration.
    627         *
    628         * @return the next object
    629         */
    630        @Override
    631        public Object next()
    632        {
    633            return nextKey();
    634        }
    635
    636        /**
    637         * Removes the current object in the iteration. This method is not
    638         * supported by this iterator type, so an exception is thrown.
    639         */
    640        @Override
    641        public void remove()
    642        {
    643            throw new UnsupportedOperationException("Remove not supported!");
    644        }
    645
    646        /**
    647         * Returns the current key of the iteration (without skipping to the
    648         * next element). This is the same key the previous {@code next()}
    649         * call had returned. (Short form of {@code currentKey(false)}.
    650         *
    651         * @return the current key
    652         */
    653        public String currentKey()
    654        {
    655            return currentKey(false);
    656        }
    657
    658        /**
    659         * Returns the current key of the iteration (without skipping to the
    660         * next element). The boolean parameter indicates wheter a decorated key
    661         * should be returned. This affects only attribute keys: if the
    662         * parameter is <b>false</b>, the attribute markers are stripped from
    663         * the key; if it is <b>true</b>, they remain.
    664         *
    665         * @param decorated a flag if the decorated key is to be returned
    666         * @return the current key
    667         */
    668        public String currentKey(final boolean decorated)
    669        {
    670            return (decorated && !isPropertyKey()) ? constructAttributeKey(current)
    671                    : current;
    672        }
    673
    674        /**
    675         * Returns a flag if the current key is an attribute. This method can be
    676         * called after {@code next()}.
    677         *
    678         * @return a flag if the current key is an attribute
    679         */
    680        public boolean isAttribute()
    681        {
    682            // if attribute emulation mode is active, the last part of a key is
    683            // always an attribute key, too
    684            return attribute || (isAttributeEmulatingMode() && !hasNext());
    685        }
    686
    687        /**
    688         * Returns a flag whether the current key refers to a property (i.e. is
    689         * no special attribute key). Usually this method will return the
    690         * opposite of {@code isAttribute()}, but if the delimiters for
    691         * normal properties and attributes are set to the same string, it is
    692         * possible that both methods return <b>true</b>.
    693         *
    694         * @return a flag if the current key is a property key
    695         * @see #isAttribute()
    696         */
    697        public boolean isPropertyKey()
    698        {
    699            return !attribute;
    700        }
    701
    702        /**
    703         * Returns the index value of the current key. If the current key does
    704         * not have an index, return value is -1. This method can be called
    705         * after {@code next()}.
    706         *
    707         * @return the index value of the current key
    708         */
    709        public int getIndex()
    710        {
    711            return indexValue;
    712        }
    713
    714        /**
    715         * Returns a flag if the current key has an associated index. This
    716         * method can be called after {@code next()}.
    717         *
    718         * @return a flag if the current key has an index
    719         */
    720        public boolean hasIndex()
    721        {
    722            return hasIndex;
    723        }
    724
    725        /**
    726         * Creates a clone of this object.
    727         *
    728         * @return a clone of this object
    729         */
    730        @Override
    731        public Object clone()
    732        {
    733            try
    734            {
    735                return super.clone();
    736            }
    737            catch (final CloneNotSupportedException cex)
    738            {
    739                // should not happen
    740                return null;
    741            }
    742        }
    743
    744        /**
    745         * Helper method for determining the next indices.
    746         *
    747         * @return the next key part
    748         */
    749        private String findNextIndices()
    750        {
    751            startIndex = endIndex;
    752            // skip empty names
    753            while (startIndex < length()
    754                    && hasLeadingDelimiter(keyBuffer.substring(startIndex)))
    755            {
    756                startIndex += getSymbols().getPropertyDelimiter()
    757                        .length();
    758            }
    759
    760            // Key ends with a delimiter?
    761            if (startIndex >= length())
    762            {
    763                endIndex = length();
    764                startIndex = endIndex - 1;
    765                return keyBuffer.substring(startIndex, endIndex);
    766            }
    767            return nextKeyPart();
    768        }
    769
    770        /**
    771         * Helper method for extracting the next key part. Takes escaping of
    772         * delimiter characters into account.
    773         *
    774         * @return the next key part
    775         */
    776        private String nextKeyPart()
    777        {
    778            int attrIdx = keyBuffer.toString().indexOf(
    779                    getSymbols().getAttributeStart(), startIndex);
    780            if (attrIdx < 0 || attrIdx == startIndex)
    781            {
    782                attrIdx = length();
    783            }
    784
    785            int delIdx = nextDelimiterPos(keyBuffer.toString(), startIndex,
    786                    attrIdx);
    787            if (delIdx < 0)
    788            {
    789                delIdx = attrIdx;
    790            }
    791
    792            endIndex = Math.min(attrIdx, delIdx);
    793            return unescapeDelimiters(keyBuffer.substring(startIndex, endIndex));
    794        }
    795
    796        /**
    797         * Searches the next unescaped delimiter from the given position.
    798         *
    799         * @param key the key
    800         * @param pos the start position
    801         * @param endPos the end position
    802         * @return the position of the next delimiter or -1 if there is none
    803         */
    804        private int nextDelimiterPos(final String key, final int pos, final int endPos)
    805        {
    806            int delimiterPos = pos;
    807            boolean found = false;
    808
    809            do
    810            {
    811                delimiterPos = key.indexOf(getSymbols()
    812                        .getPropertyDelimiter(), delimiterPos);
    813                if (delimiterPos < 0 || delimiterPos >= endPos)
    814                {
    815                    return -1;
    816                }
    817                final int escapePos = escapedPosition(key, delimiterPos);
    818                if (escapePos < 0)
    819                {
    820                    found = true;
    821                }
    822                else
    823                {
    824                    delimiterPos = escapePos;
    825                }
    826            }
    827            while (!found);
    828
    829            return delimiterPos;
    830        }
    831
    832        /**
    833         * Checks if a delimiter at the specified position is escaped. If this
    834         * is the case, the next valid search position will be returned.
    835         * Otherwise the return value is -1.
    836         *
    837         * @param key the key to check
    838         * @param pos the position where a delimiter was found
    839         * @return information about escaped delimiters
    840         */
    841        private int escapedPosition(final String key, final int pos)
    842        {
    843            if (getSymbols().getEscapedDelimiter() == null)
    844            {
    845                // nothing to escape
    846                return -1;
    847            }
    848            final int escapeOffset = escapeOffset();
    849            if (escapeOffset < 0 || escapeOffset > pos)
    850            {
    851                // No escaping possible at this position
    852                return -1;
    853            }
    854
    855            final int escapePos = key.indexOf(getSymbols()
    856                    .getEscapedDelimiter(), pos - escapeOffset);
    857            if (escapePos <= pos && escapePos >= 0)
    858            {
    859                // The found delimiter is escaped. Next valid search position
    860                // is behind the escaped delimiter.
    861                return escapePos
    862                        + getSymbols().getEscapedDelimiter().length();
    863            }
    864            return -1;
    865        }
    866
    867        /**
    868         * Determines the relative offset of an escaped delimiter in relation to
    869         * a delimiter. Depending on the used delimiter and escaped delimiter
    870         * tokens the position where to search for an escaped delimiter is
    871         * different. If, for instance, the dot character (&quot;.&quot;) is
    872         * used as delimiter, and a doubled dot (&quot;..&quot;) as escaped
    873         * delimiter, the escaped delimiter starts at the same position as the
    874         * delimiter. If the token &quot;\.&quot; was used, it would start one
    875         * character before the delimiter because the delimiter character
    876         * &quot;.&quot; is the second character in the escaped delimiter
    877         * string. This relation will be determined by this method. For this to
    878         * work the delimiter string must be contained in the escaped delimiter
    879         * string.
    880         *
    881         * @return the relative offset of the escaped delimiter in relation to a
    882         * delimiter
    883         */
    884        private int escapeOffset()
    885        {
    886            return getSymbols().getEscapedDelimiter().indexOf(
    887                    getSymbols().getPropertyDelimiter());
    888        }
    889
    890        /**
    891         * Helper method for checking if the passed key is an attribute. If this
    892         * is the case, the internal fields will be set.
    893         *
    894         * @param key the key to be checked
    895         * @return a flag if the key is an attribute
    896         */
    897        private boolean checkAttribute(final String key)
    898        {
    899            if (isAttributeKey(key))
    900            {
    901                current = removeAttributeMarkers(key);
    902                return true;
    903            }
    904            return false;
    905        }
    906
    907        /**
    908         * Helper method for checking if the passed key contains an index. If
    909         * this is the case, internal fields will be set.
    910         *
    911         * @param key the key to be checked
    912         * @return a flag if an index is defined
    913         */
    914        private boolean checkIndex(final String key)
    915        {
    916            boolean result = false;
    917
    918            try
    919            {
    920                final int idx = key.lastIndexOf(getSymbols().getIndexStart());
    921                if (idx > 0)
    922                {
    923                    final int endidx = key.indexOf(getSymbols().getIndexEnd(),
    924                            idx);
    925
    926                    if (endidx > idx + 1)
    927                    {
    928                        indexValue = Integer.parseInt(key.substring(idx + 1, endidx));
    929                        current = key.substring(0, idx);
    930                        result = true;
    931                    }
    932                }
    933            }
    934            catch (final NumberFormatException nfe)
    935            {
    936                result = false;
    937            }
    938
    939            return result;
    940        }
    941
    942        /**
    943         * Returns a flag whether attributes are marked the same way as normal
    944         * property keys. We call this the &quot;attribute emulating mode&quot;.
    945         * When navigating through node hierarchies it might be convenient to
    946         * treat attributes the same way than other child nodes, so an
    947         * expression engine supports to set the attribute markers to the same
    948         * value than the property delimiter. If this is the case, some special
    949         * checks have to be performed.
    950         *
    951         * @return a flag if attributes and normal property keys are treated the
    952         * same way
    953         */
    954        private boolean isAttributeEmulatingMode()
    955        {
    956            return getSymbols().getAttributeEnd() == null
    957                    && StringUtils.equals(getSymbols()
    958                            .getPropertyDelimiter(), getSymbols()
    959                            .getAttributeStart());
    960        }
    961    }
    962}