org.apache.commons.configuration2.tree.QueryResult Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-configuration2 Show documentation
Tools to assist in the reading of configuration/preferences files in various formats
The newest version!
/*
 * 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.configuration2.tree;

import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.builder.EqualsBuilder;
import org.apache.commons.lang3.builder.HashCodeBuilder;
import org.apache.commons.lang3.builder.ToStringBuilder;

/**
 * 
 * A data class representing a single query result produced by an {@link ExpressionEngine}.
 * 
 * 
 * When passing a key to the {@code query()} method of {@code ExpressionEngine} the result can be a set of nodes or
 * attributes - depending on the key. This class can represent both types of results. The aim is to give a user of
 * {@code ExpressionEngine} all information needed for evaluating the results returned.
 * 
 * 
 * Implementation note: Instances are immutable. They are created using the static factory methods.
 * 
 *
 * @since 2.0
 * @param  the type of the result nodes
 */
public final class QueryResult {
    /**
     * Creates a {@code QueryResult} instance representing an attribute result. An attribute result consists of the node the
     * attribute belongs to and the attribute name. (The value can be obtained based on this information.)
     *
     * @param parentNode the node which owns the attribute
     * @param attrName the attribute name
     * @param  the type of the parent node
     * @return the newly created instance
     */
    public static  QueryResult createAttributeResult(final T parentNode, final String attrName) {
        return new QueryResult<>(parentNode, attrName);
    }

    /**
     * Creates a {@code QueryResult} instance representing the specified result node.
     *
     * @param  the type of the result node
     * @param resultNode the result node
     * @return the newly created instance
     */
    public static  QueryResult createNodeResult(final T resultNode) {
        return new QueryResult<>(resultNode, null);
    }

    /** The node result. */
    private final T node;

    /** The name of the result attribute. */
    private final String attributeName;

    /**
     * Creates a new instance of {@code QueryResult}.
     *
     * @param nd the node
     * @param attr the attribute name
     */
    private QueryResult(final T nd, final String attr) {
        node = nd;
        attributeName = attr;
    }

    /**
     * Compares this object with another one. Two instances of {@code QueryResult} are considered equal if they are of the
     * same result type and have the same properties.
     *
     * @param obj the object to compare to
     * @return a flag whether these objects are equal
     */
    @Override
    public boolean equals(final Object obj) {
        if (this == obj) {
            return true;
        }
        if (!(obj instanceof QueryResult)) {
            return false;
        }

        final QueryResult c = (QueryResult) obj;
        return new EqualsBuilder().append(getNode(), c.getNode()).append(getAttributeName(), c.getAttributeName()).isEquals();
    }

    /**
     * Gets the name of the attribute. This method is defined only for results of type attribute.
     *
     * @return the attribute name
     */
    public String getAttributeName() {
        return attributeName;
    }

    /**
     * Gets the attribute value if this is an attribute result. If this is not an attribute result, an exception is
     * thrown.
     *
     * @param handler the {@code NodeHandler}
     * @return the attribute value
     * @throws IllegalStateException if this is not an attribute result
     */
    public Object getAttributeValue(final NodeHandler handler) {
        if (!isAttributeResult()) {
            throw new IllegalStateException("This is not an attribute result! " + "Attribute value cannot be fetched.");
        }
        return handler.getAttributeValue(getNode(), getAttributeName());
    }

    /**
     * Gets the node referenced by this object. Depending on the result type, this is either the result node or the
     * parent node of the represented attribute.
     *
     * @return the referenced node
     */
    public T getNode() {
        return node;
    }

    @Override
    public int hashCode() {
        return new HashCodeBuilder().append(getNode()).append(getAttributeName()).toHashCode();
    }

    /**
     * Returns a flag whether this is a result of type attribute. If result is true, the attribute name and value can
     * be queried. Otherwise, only the result node is available.
     *
     * @return true for an attribute result, false otherwise
     */
    public boolean isAttributeResult() {
        return StringUtils.isNotEmpty(getAttributeName());
    }

    /**
     * Returns a string representation of this object. Depending on the result type either the result node or the parent
     * node and the attribute name are contained in this string.
     *
     * @return a string for this object
     */
    @Override
    public String toString() {
        final ToStringBuilder sb = new ToStringBuilder(this);
        if (isAttributeResult()) {
            sb.append("parentNode", getNode()).append("attribute", getAttributeName());
        } else {
            sb.append("resultNode", getNode());
        }
        return sb.toString();
    }
}