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 org.apache.commons.lang3.StringUtils; 020import org.apache.commons.lang3.builder.EqualsBuilder; 021import org.apache.commons.lang3.builder.HashCodeBuilder; 022import org.apache.commons.lang3.builder.ToStringBuilder; 023 024/** 025 * <p> 026 * A data class representing a single query result produced by an {@link ExpressionEngine}. 027 * </p> 028 * <p> 029 * When passing a key to the {@code query()} method of {@code ExpressionEngine} the result can be a set of nodes or 030 * attributes - depending on the key. This class can represent both types of results. The aim is to give a user of 031 * {@code ExpressionEngine} all information needed for evaluating the results returned. 032 * </p> 033 * <p> 034 * Implementation note: Instances are immutable. They are created using the static factory methods. 035 * </p> 036 * 037 * @since 2.0 038 * @param <T> the type of the result nodes 039 */ 040public final class QueryResult<T> { 041 /** The node result. */ 042 private final T node; 043 044 /** The name of the result attribute. */ 045 private final String attributeName; 046 047 /** 048 * Creates a new instance of {@code QueryResult}. 049 * 050 * @param nd the node 051 * @param attr the attribute name 052 */ 053 private QueryResult(final T nd, final String attr) { 054 node = nd; 055 attributeName = attr; 056 } 057 058 /** 059 * Creates a {@code QueryResult} instance representing the specified result node. 060 * 061 * @param <T> the type of the result node 062 * @param resultNode the result node 063 * @return the newly created instance 064 */ 065 public static <T> QueryResult<T> createNodeResult(final T resultNode) { 066 return new QueryResult<>(resultNode, null); 067 } 068 069 /** 070 * Creates a {@code QueryResult} instance representing an attribute result. An attribute result consists of the node the 071 * attribute belongs to and the attribute name. (The value can be obtained based on this information.) 072 * 073 * @param parentNode the node which owns the attribute 074 * @param attrName the attribute name 075 * @param <T> the type of the parent node 076 * @return the newly created instance 077 */ 078 public static <T> QueryResult<T> createAttributeResult(final T parentNode, final String attrName) { 079 return new QueryResult<>(parentNode, attrName); 080 } 081 082 /** 083 * Gets the node referenced by this object. Depending on the result type, this is either the result node or the 084 * parent node of the represented attribute. 085 * 086 * @return the referenced node 087 */ 088 public T getNode() { 089 return node; 090 } 091 092 /** 093 * Gets the name of the attribute. This method is defined only for results of type attribute. 094 * 095 * @return the attribute name 096 */ 097 public String getAttributeName() { 098 return attributeName; 099 } 100 101 /** 102 * Returns a flag whether this is a result of type attribute. If result is <b>true</b>, the attribute name and value can 103 * be queried. Otherwise, only the result node is available. 104 * 105 * @return <b>true</b> for an attribute result, <b>false</b> otherwise 106 */ 107 public boolean isAttributeResult() { 108 return StringUtils.isNotEmpty(getAttributeName()); 109 } 110 111 /** 112 * Gets the attribute value if this is an attribute result. If this is not an attribute result, an exception is 113 * thrown. 114 * 115 * @param handler the {@code NodeHandler} 116 * @return the attribute value 117 * @throws IllegalStateException if this is not an attribute result 118 */ 119 public Object getAttributeValue(final NodeHandler<T> handler) { 120 if (!isAttributeResult()) { 121 throw new IllegalStateException("This is not an attribute result! " + "Attribute value cannot be fetched."); 122 } 123 return handler.getAttributeValue(getNode(), getAttributeName()); 124 } 125 126 @Override 127 public int hashCode() { 128 return new HashCodeBuilder().append(getNode()).append(getAttributeName()).toHashCode(); 129 } 130 131 /** 132 * Compares this object with another one. Two instances of {@code QueryResult} are considered equal if they are of the 133 * same result type and have the same properties. 134 * 135 * @param obj the object to compare to 136 * @return a flag whether these objects are equal 137 */ 138 @Override 139 public boolean equals(final Object obj) { 140 if (this == obj) { 141 return true; 142 } 143 if (!(obj instanceof QueryResult)) { 144 return false; 145 } 146 147 final QueryResult<?> c = (QueryResult<?>) obj; 148 return new EqualsBuilder().append(getNode(), c.getNode()).append(getAttributeName(), c.getAttributeName()).isEquals(); 149 } 150 151 /** 152 * Returns a string representation of this object. Depending on the result type either the result node or the parent 153 * node and the attribute name are contained in this string. 154 * 155 * @return a string for this object 156 */ 157 @Override 158 public String toString() { 159 final ToStringBuilder sb = new ToStringBuilder(this); 160 if (isAttributeResult()) { 161 sb.append("parentNode", getNode()).append("attribute", getAttributeName()); 162 } else { 163 sb.append("resultNode", getNode()); 164 } 165 return sb.toString(); 166 } 167}