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.beanutils.expression; 18 19 /** 20 * Property Name Expression Resolver. 21 * <p> 22 * Methods such as PropertyUtilsBean's <code>setNestedProperty()</code> method 23 * use a <code>Resolver</code> to process a <i>property name</i> 24 * expression and resolve <i>nested</i>, <i>indexed</i> and <i>mapped</i> 25 * property names. The following code provides an example usage 26 * demonstrating all the methods: 27 * 28 * <pre> 29 * // Iterate through a nested property expression 30 * while (resolver.hasNested(name)) { 31 * 32 * // isolate a single property from a nested expresion 33 * String next = resolver.next(name); 34 * 35 * // Process... 36 * String property = resolver.getProperty(next); 37 * if (resolver.isIndexed(next)) { 38 * 39 * int index = resolver.getIndex(next); 40 * bean = getIndexedProperty(bean, property, index); 41 * 42 * } else if (resolver.isMapped(next)) { 43 * 44 * String key = resolver.getKey(next); 45 * bean = getMappedProperty(bean, property, key); 46 * 47 * } else { 48 * 49 * bean = getSimpleProperty(bean, property); 50 * 51 * } 52 * 53 * // remove the processed property from the expression 54 * name = resolver.remove(name); 55 * } 56 * </pre> 57 * 58 * In order to create an implementation, it is important to understand how 59 * BeanUtils/PropertyUtils uses the <code>resolver</code>. The following are 60 * the main methods that use it: 61 * <ul> 62 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean}</li> 63 * <ul> 64 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getIndexedProperty(Object, String)}</li> 65 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getMappedProperty(Object, String)}</li> 66 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getNestedProperty(Object, String)}</li> 67 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getPropertyDescriptor(Object, String)}</li> 68 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getSimpleProperty(Object, String)}</li> 69 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setIndexedProperty(Object, String, Object)}</li> 70 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setMappedProperty(Object, String, Object)}</li> 71 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setNestedProperty(Object, String, Object)}</li> 72 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setSimpleProperty(Object, String, Object)}</li> 73 * </ul> 74 * <li>{@link org.apache.commons.beanutils.BeanUtilsBean}</li> 75 * <ul> 76 * <li>{@link org.apache.commons.beanutils.BeanUtilsBean#copyProperty(Object, String, Object)}</li> 77 * <li>{@link org.apache.commons.beanutils.BeanUtilsBean#setProperty(Object, String, Object)}</li> 78 * </ul> 79 * <li>{@link org.apache.commons.beanutils.locale.LocaleBeanUtilsBean}</li> 80 * <ul> 81 * <li>{@link org.apache.commons.beanutils.locale.LocaleBeanUtilsBean#setProperty(Object, 82 * String, Object, String)}</li> 83 * </ul> 84 * </ul> 85 * 86 * @version $Id$ 87 * @see org.apache.commons.beanutils.PropertyUtilsBean#setResolver(Resolver) 88 * @since 1.8.0 89 */ 90 public interface Resolver { 91 92 /** 93 * Extract the index value from the property expression or -1. 94 * 95 * @param expression The property expression 96 * @return The index value or -1 if the property is not indexed 97 * @throws IllegalArgumentException If the indexed property is illegally 98 * formed or has an invalid (non-numeric) value 99 */ 100 int getIndex(String expression); 101 102 /** 103 * Extract the map key from the property expression or <code>null</code>. 104 * 105 * @param expression The property expression 106 * @return The index value 107 * @throws IllegalArgumentException If the mapped property is illegally formed 108 */ 109 String getKey(String expression); 110 111 /** 112 * Return the property name from the property expression. 113 * 114 * @param expression The property expression 115 * @return The property name 116 */ 117 String getProperty(String expression); 118 119 /** 120 * Indicates whether or not the expression 121 * contains nested property expressions or not. 122 * 123 * @param expression The property expression 124 * @return The next property expression 125 */ 126 boolean hasNested(String expression); 127 128 /** 129 * Indicate whether the expression is for an indexed property or not. 130 * 131 * @param expression The property expression 132 * @return <code>true</code> if the expresion is indexed, 133 * otherwise <code>false</code> 134 */ 135 boolean isIndexed(String expression); 136 137 /** 138 * Indicate whether the expression is for a mapped property or not. 139 * 140 * @param expression The property expression 141 * @return <code>true</code> if the expresion is mapped, 142 * otherwise <code>false</code> 143 */ 144 boolean isMapped(String expression); 145 146 /** 147 * Extract the next property expression from the 148 * current expression. 149 * 150 * @param expression The property expression 151 * @return The next property expression 152 */ 153 String next(String expression); 154 155 /** 156 * Remove the last property expresson from the 157 * current expression. 158 * 159 * @param expression The property expression 160 * @return The new expression value, with first property 161 * expression removed - null if there are no more expressions 162 */ 163 String remove(String expression); 164 165 }