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.beanutils; 018 019/** 020 * <p> 021 * A class representing an argument for a constructor invocation to be used by a 022 * {@link BeanDeclaration}. 023 * </p> 024 * <p> 025 * A {@code BeanDeclaration} can provide a list of instances of this class to 026 * define the constructor to be invoked on the bean class. Each constructor 027 * argument can either be a simple value or a nested {@code BeanDeclaration}. In 028 * the latter case, the bean is resolved recursively. 029 * </p> 030 * <p> 031 * The constructor to be invoked on the bean class has to be determined based on 032 * the types of the constructor arguments. To avoid ambiguity, the type name can 033 * be explicitly provided. 034 * </p> 035 * 036 * @since 2.0 037 */ 038public final class ConstructorArg 039{ 040 /** The bean declaration referenced by this constructor argument. */ 041 private final BeanDeclaration beanDeclaration; 042 043 /** The value of this constructor argument. */ 044 private final Object value; 045 046 /** The name of the argument type. */ 047 private final String typeName; 048 049 /** 050 * Creates a new instance of {@code ConstructorArg}. 051 * 052 * @param decl the associated bean declaration 053 * @param val the value of the argument 054 * @param type the type name 055 */ 056 private ConstructorArg(final BeanDeclaration decl, final Object val, final String type) 057 { 058 beanDeclaration = decl; 059 value = val; 060 typeName = type; 061 } 062 063 /** 064 * Creates a new instance of {@code ConstructorArg} for the specified 065 * {@code BeanDeclaration}. The actual value of this argument is the 066 * resolved {@code BeanDeclaration}. 067 * 068 * @param decl the {@code BeanDeclaration} 069 * @return the newly created instance of this class 070 * @throws NullPointerException if the {@code BeanDeclaration} is 071 * <b>null</b> 072 */ 073 public static ConstructorArg forBeanDeclaration(final BeanDeclaration decl) 074 { 075 return forBeanDeclaration(decl, null); 076 } 077 078 /** 079 * Creates a new instance of {@code ConstructorArg} for the specified 080 * {@code BeanDeclaration} and sets the type name explicitly. The type name 081 * is used to match this argument against the parameter type of a 082 * constructor or the bean class. 083 * 084 * @param decl the {@code BeanDeclaration} 085 * @param typeName the name of the data type of this argument 086 * @return the newly created instance of this class 087 * @throws NullPointerException if the {@code BeanDeclaration} is 088 * <b>null</b> 089 */ 090 public static ConstructorArg forBeanDeclaration(final BeanDeclaration decl, 091 final String typeName) 092 { 093 if (decl == null) 094 { 095 throw new NullPointerException("BeanDeclaration must not be null!"); 096 } 097 return new ConstructorArg(decl, null, typeName); 098 } 099 100 /** 101 * Creates a new instance of {@code ConstructorArg} for the specified simple 102 * value. The value is passed to the constructor invocation. 103 * 104 * @param value the value of this constructor argument (may be <b>null</b>) 105 * @return the newly created instance of this class 106 */ 107 public static ConstructorArg forValue(final Object value) 108 { 109 return forValue(value, null); 110 } 111 112 /** 113 * Creates a new instance of {@code ConstructorArg} for the specified simple 114 * value and sets the type name explicitly. The type name is used to match 115 * this argument against the parameter type of a constructor or the bean 116 * class. 117 * 118 * @param value the value of this constructor argument (may be <b>null</b>) 119 * @param typeName the name of the data type of this argument 120 * @return the newly created instance of this class 121 */ 122 public static ConstructorArg forValue(final Object value, final String typeName) 123 { 124 return new ConstructorArg(null, value, typeName); 125 } 126 127 /** 128 * Returns the {@code BeanDeclaration} referenced by this constructor 129 * argument. A return value of <b>null</b> means that this constructor 130 * argument does not have a bean declaration as value; in this case, the 131 * value can be queried using the {@link #getValue()} method. 132 * 133 * @return the referenced {@code BeanDeclaration} or <b>null</b> 134 */ 135 public BeanDeclaration getBeanDeclaration() 136 { 137 return beanDeclaration; 138 } 139 140 /** 141 * Returns a flag whether this constructor argument represents a 142 * {@code BeanDeclaration}. If this method returns <b>true</b>, the actual 143 * value of this argument can be obtained by resolving the bean declaration 144 * returned by {@link #getBeanDeclaration()}. Otherwise, this argument has a 145 * simple value which can be queried using {@link #getValue()}. 146 * 147 * @return a flag whether this constructor argument references a bean 148 * declaration 149 */ 150 public boolean isNestedBeanDeclaration() 151 { 152 return getBeanDeclaration() != null; 153 } 154 155 /** 156 * Returns the value of this constructor argument. This method can be 157 * queried if {@link #isNestedBeanDeclaration()} returns <b>false</b>. Note 158 * that a return value of <b>null</b> is legal (to pass <b>null</b> to a 159 * constructor argument). 160 * 161 * @return the simple value of this constructor argument 162 */ 163 public Object getValue() 164 { 165 return value; 166 } 167 168 /** 169 * Returns the optional data type name of this constructor argument. The 170 * type name can be specified as a hint to select a specific constructor if 171 * there are ambiguities. Note that it does not necessarily has to match the 172 * data type of this argument's value because a type conversion may be 173 * performed before invoking the constructor. 174 * 175 * @return the data type name of this argument if defined or <b>null</b> 176 * otherwise 177 */ 178 public String getTypeName() 179 { 180 return typeName; 181 } 182 183 /** 184 * Checks whether this constructor argument is compatible with the given 185 * class. This method is called to determine a matching constructor. It 186 * compares the argument's data type with the class name if it is defined. 187 * If no type name has been set, result is <b>true</b> as it is assumed that 188 * a type conversion can be performed when calling the constructor. This 189 * means that per default only the number of constructor arguments is 190 * checked to find a matching constructor. Only if there are multiple 191 * constructors with the same number of arguments, explicit type names have 192 * to be provided to select a specific constructor. 193 * 194 * @param argCls the class of the constructor argument to compare with 195 * @return <b>true</b> if this constructor argument is compatible with this 196 * class, <b>false</b> otherwise 197 */ 198 public boolean matches(final Class<?> argCls) 199 { 200 if (argCls == null) 201 { 202 return false; 203 } 204 205 return getTypeName() == null || getTypeName().equals(argCls.getName()); 206 } 207 208 /** 209 * Returns a string representation of this object. This string contains the 210 * value of this constructor argument and the explicit type if provided. 211 * 212 * @return a string for this object 213 */ 214 @Override 215 public String toString() 216 { 217 final StringBuilder buf = new StringBuilder(); 218 buf.append(getClass().getSimpleName()); 219 buf.append(" [ value = "); 220 buf.append(isNestedBeanDeclaration() ? getBeanDeclaration() 221 : getValue()); 222 if (getTypeName() != null) 223 { 224 buf.append(" (").append(getTypeName()).append(')'); 225 } 226 buf.append(" ]"); 227 return buf.toString(); 228 } 229}