DefaultExpressionEngineSymbols.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.configuration2.tree;

  18. import org.apache.commons.lang3.builder.EqualsBuilder;
  19. import org.apache.commons.lang3.builder.HashCodeBuilder;
  20. import org.apache.commons.lang3.builder.ToStringBuilder;

  21. /**
  22.  * <p>
  23.  * A class representing the various symbols that are supported in keys recognized by {@link DefaultExpressionEngine}.
  24.  * </p>
  25.  * <p>
  26.  * An instance of this class is associated with each instance of {@code DefaultExpressionEngine}. It determines which
  27.  * concrete symbols are used to define elements like separators, attributes, etc. within a configuration key.
  28.  * </p>
  29.  * <p>
  30.  * Instances are created using the nested {@code Builder} class. They are immutable and can be shared between arbitrary
  31.  * components.
  32.  * </p>
  33.  *
  34.  * @since 2.0
  35.  */
  36. public final class DefaultExpressionEngineSymbols {
  37.     /**
  38.      * A builder class for creating instances of {@code DefaultExpressionEngineSymbols}.
  39.      */
  40.     public static class Builder {
  41.         /** Stores the property delimiter. */
  42.         private String propertyDelimiter;

  43.         /** Stores the escaped property delimiter. */
  44.         private String escapedDelimiter;

  45.         /** Stores the attribute start marker. */
  46.         private String attributeStart;

  47.         /** Stores the attribute end marker. */
  48.         private String attributeEnd;

  49.         /** Stores the index start marker. */
  50.         private String indexStart;

  51.         /** Stores the index end marker. */
  52.         private String indexEnd;

  53.         /**
  54.          * Creates a new, uninitialized instance of {@code Builder}. All symbols are undefined.
  55.          */
  56.         public Builder() {
  57.         }

  58.         /**
  59.          * Creates a new instance of {@code Builder} whose properties are initialized from the passed in
  60.          * {@code DefaultExpressionEngineSymbols} object. This is useful if symbols are to be created which are similar to the
  61.          * passed in instance.
  62.          *
  63.          * @param c the {@code DefaultExpressionEngineSymbols} object serving as starting point for this builder
  64.          */
  65.         public Builder(final DefaultExpressionEngineSymbols c) {
  66.             propertyDelimiter = c.getPropertyDelimiter();
  67.             escapedDelimiter = c.getEscapedDelimiter();
  68.             indexStart = c.getIndexStart();
  69.             indexEnd = c.getIndexEnd();
  70.             attributeStart = c.getAttributeStart();
  71.             attributeEnd = c.getAttributeEnd();
  72.         }

  73.         /**
  74.          * Creates the {@code DefaultExpressionEngineSymbols} instance based on the properties set for this builder object. This
  75.          * method does not change the state of this builder. So it is possible to change properties and create another
  76.          * {@code DefaultExpressionEngineSymbols} instance.
  77.          *
  78.          * @return the newly created {@code DefaultExpressionEngineSymbols} instance
  79.          */
  80.         public DefaultExpressionEngineSymbols create() {
  81.             return new DefaultExpressionEngineSymbols(this);
  82.         }

  83.         /**
  84.          * Sets the string representing the end marker of an attribute in a property key.
  85.          *
  86.          * @param attributeEnd the attribute end marker
  87.          * @return a reference to this object for method chaining
  88.          */
  89.         public Builder setAttributeEnd(final String attributeEnd) {
  90.             this.attributeEnd = attributeEnd;
  91.             return this;
  92.         }

  93.         /**
  94.          * Sets the string representing the start marker of an attribute in a property key. Attribute start and end marker are
  95.          * used together to detect attributes in a property key.
  96.          *
  97.          * @param attributeStart the attribute start marker
  98.          * @return a reference to this object for method chaining
  99.          */
  100.         public Builder setAttributeStart(final String attributeStart) {
  101.             this.attributeStart = attributeStart;
  102.             return this;
  103.         }

  104.         /**
  105.          * Sets the string representing an escaped property delimiter. With this string a delimiter that belongs to the key of a
  106.          * property can be escaped. If for instance &quot;.&quot; is used as property delimiter, you can set the escaped
  107.          * delimiter to &quot;\.&quot; and can then escape the delimiter with a back slash.
  108.          *
  109.          * @param escapedDelimiter the escaped property delimiter
  110.          * @return a reference to this object for method chaining
  111.          */
  112.         public Builder setEscapedDelimiter(final String escapedDelimiter) {
  113.             this.escapedDelimiter = escapedDelimiter;
  114.             return this;
  115.         }

  116.         /**
  117.          * Sets the string representing the end of an index in a property key.
  118.          *
  119.          * @param indexEnd the index end
  120.          * @return a reference to this object for method chaining
  121.          */
  122.         public Builder setIndexEnd(final String indexEnd) {
  123.             this.indexEnd = indexEnd;
  124.             return this;
  125.         }

  126.         /**
  127.          * Sets the string representing the start of an index in a property key. Index start and end marker are used together to
  128.          * detect indices in a property key.
  129.          *
  130.          * @param is the index start
  131.          * @return a reference to this object for method chaining
  132.          */
  133.         public Builder setIndexStart(final String is) {
  134.             this.indexStart = is;
  135.             return this;
  136.         }

  137.         /**
  138.          * Sets the string representing a delimiter for properties.
  139.          *
  140.          * @param propertyDelimiter the property delimiter
  141.          * @return a reference to this object for method chaining
  142.          */
  143.         public Builder setPropertyDelimiter(final String propertyDelimiter) {
  144.             this.propertyDelimiter = propertyDelimiter;
  145.             return this;
  146.         }
  147.     }

  148.     /** Constant for the default property delimiter. */
  149.     public static final String DEFAULT_PROPERTY_DELIMITER = ".";

  150.     /** Constant for the default escaped property delimiter. */
  151.     public static final String DEFAULT_ESCAPED_DELIMITER = DEFAULT_PROPERTY_DELIMITER + DEFAULT_PROPERTY_DELIMITER;

  152.     /** Constant for the default attribute start marker. */
  153.     public static final String DEFAULT_ATTRIBUTE_START = "[@";

  154.     /** Constant for the default attribute end marker. */
  155.     public static final String DEFAULT_ATTRIBUTE_END = "]";

  156.     /** Constant for the default index start marker. */
  157.     public static final String DEFAULT_INDEX_START = "(";

  158.     /** Constant for the default index end marker. */
  159.     public static final String DEFAULT_INDEX_END = ")";

  160.     /**
  161.      * An instance with default symbols. This instance is used by the default instance of {@code DefaultExpressionEngine}.
  162.      */
  163.     public static final DefaultExpressionEngineSymbols DEFAULT_SYMBOLS = createDefaultSmybols();

  164.     /**
  165.      * Creates the {@code DefaultExpressionEngineSymbols} object with default symbols.
  166.      *
  167.      * @return the default symbols instance
  168.      */
  169.     private static DefaultExpressionEngineSymbols createDefaultSmybols() {
  170.         return new Builder().setPropertyDelimiter(DEFAULT_PROPERTY_DELIMITER).setEscapedDelimiter(DEFAULT_ESCAPED_DELIMITER).setIndexStart(DEFAULT_INDEX_START)
  171.             .setIndexEnd(DEFAULT_INDEX_END).setAttributeStart(DEFAULT_ATTRIBUTE_START).setAttributeEnd(DEFAULT_ATTRIBUTE_END).create();
  172.     }

  173.     /** Stores the property delimiter. */
  174.     private final String propertyDelimiter;

  175.     /** Stores the escaped property delimiter. */
  176.     private final String escapedDelimiter;

  177.     /** Stores the attribute start marker. */
  178.     private final String attributeStart;

  179.     /** Stores the attribute end marker. */
  180.     private final String attributeEnd;

  181.     /** Stores the index start marker. */
  182.     private final String indexStart;

  183.     /** Stores the index end marker. */
  184.     private final String indexEnd;

  185.     /**
  186.      * Creates a new instance of {@code DefaultExpressionEngineSymbols}.
  187.      *
  188.      * @param b the builder for defining the properties of this instance
  189.      */
  190.     private DefaultExpressionEngineSymbols(final Builder b) {
  191.         propertyDelimiter = b.propertyDelimiter;
  192.         escapedDelimiter = b.escapedDelimiter;
  193.         indexStart = b.indexStart;
  194.         indexEnd = b.indexEnd;
  195.         attributeStart = b.attributeStart;
  196.         attributeEnd = b.attributeEnd;
  197.     }

  198.     /**
  199.      * Compares this object with another one. Two instances of {@code DefaultExpressionEngineSymbols} are considered equal
  200.      * if all of their properties are equal.
  201.      *
  202.      * @param obj the object to compare to
  203.      * @return a flag whether these objects are equal
  204.      */
  205.     @Override
  206.     public boolean equals(final Object obj) {
  207.         if (this == obj) {
  208.             return true;
  209.         }
  210.         if (!(obj instanceof DefaultExpressionEngineSymbols)) {
  211.             return false;
  212.         }

  213.         final DefaultExpressionEngineSymbols c = (DefaultExpressionEngineSymbols) obj;
  214.         return new EqualsBuilder().append(getPropertyDelimiter(), c.getPropertyDelimiter()).append(getEscapedDelimiter(), c.getEscapedDelimiter())
  215.             .append(getIndexStart(), c.getIndexStart()).append(getIndexEnd(), c.getIndexEnd()).append(getAttributeStart(), c.getAttributeStart())
  216.             .append(getAttributeEnd(), c.getAttributeEnd()).isEquals();
  217.     }

  218.     /**
  219.      * Gets the string representing an attribute end marker.
  220.      *
  221.      * @return the attribute end marker
  222.      */
  223.     public String getAttributeEnd() {
  224.         return attributeEnd;
  225.     }

  226.     /**
  227.      * Gets the string representing an attribute start marker.
  228.      *
  229.      * @return the attribute start marker
  230.      */
  231.     public String getAttributeStart() {
  232.         return attributeStart;
  233.     }

  234.     /**
  235.      * Gets the string representing an escaped property delimiter.
  236.      *
  237.      * @return the escaped property delimiter
  238.      */
  239.     public String getEscapedDelimiter() {
  240.         return escapedDelimiter;
  241.     }

  242.     /**
  243.      * Gets the string representing the end of an index in a property key.
  244.      *
  245.      * @return the index end marker
  246.      */
  247.     public String getIndexEnd() {
  248.         return indexEnd;
  249.     }

  250.     /**
  251.      * Gets the string representing the start of an index in a property key.
  252.      *
  253.      * @return the index start marker
  254.      */
  255.     public String getIndexStart() {
  256.         return indexStart;
  257.     }

  258.     /**
  259.      * Gets the string used as delimiter in property keys.
  260.      *
  261.      * @return the property delimiter
  262.      */
  263.     public String getPropertyDelimiter() {
  264.         return propertyDelimiter;
  265.     }

  266.     /**
  267.      * Returns a hash code for this object.
  268.      *
  269.      * @return a hash code
  270.      */
  271.     @Override
  272.     public int hashCode() {
  273.         return new HashCodeBuilder().append(getPropertyDelimiter()).append(getEscapedDelimiter()).append(getIndexStart()).append(getIndexEnd())
  274.             .append(getAttributeStart()).append(getAttributeEnd()).toHashCode();
  275.     }

  276.     /**
  277.      * Returns a string representation for this object. This string contains the values of all properties.
  278.      *
  279.      * @return a string for this object
  280.      */
  281.     @Override
  282.     public String toString() {
  283.         return new ToStringBuilder(this).append("propertyDelimiter", getPropertyDelimiter()).append("escapedDelimiter", getEscapedDelimiter())
  284.             .append("indexStart", getIndexStart()).append("indexEnd", getIndexEnd()).append("attributeStart", getAttributeStart())
  285.             .append("attributeEnd", getAttributeEnd()).toString();
  286.     }
  287. }