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.beanutils.expression; 018 019/** 020 * Property Name Expression Resolver. 021 * <p> 022 * Methods such as PropertyUtilsBean's <code>setNestedProperty()</code> method 023 * use a <code>Resolver</code> to process a <i>property name</i> 024 * expression and resolve <i>nested</i>, <i>indexed</i> and <i>mapped</i> 025 * property names. The following code provides an example usage 026 * demonstrating all the methods: 027 * 028 * <pre> 029 * // Iterate through a nested property expression 030 * while (resolver.hasNested(name)) { 031 * 032 * // isolate a single property from a nested expresion 033 * String next = resolver.next(name); 034 * 035 * // Process... 036 * String property = resolver.getProperty(next); 037 * if (resolver.isIndexed(next)) { 038 * 039 * int index = resolver.getIndex(next); 040 * bean = getIndexedProperty(bean, property, index); 041 * 042 * } else if (resolver.isMapped(next)) { 043 * 044 * String key = resolver.getKey(next); 045 * bean = getMappedProperty(bean, property, key); 046 * 047 * } else { 048 * 049 * bean = getSimpleProperty(bean, property); 050 * 051 * } 052 * 053 * // remove the processed property from the expression 054 * name = resolver.remove(name); 055 * } 056 * </pre> 057 * 058 * In order to create an implementation, it is important to understand how 059 * BeanUtils/PropertyUtils uses the <code>resolver</code>. The following are 060 * the main methods that use it: 061 * <ul> 062 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean} 063 * <ul> 064 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getIndexedProperty(Object, String)}</li> 065 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getMappedProperty(Object, String)}</li> 066 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getNestedProperty(Object, String)}</li> 067 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getPropertyDescriptor(Object, String)}</li> 068 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getSimpleProperty(Object, String)}</li> 069 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setIndexedProperty(Object, String, Object)}</li> 070 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setMappedProperty(Object, String, Object)}</li> 071 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setNestedProperty(Object, String, Object)}</li> 072 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setSimpleProperty(Object, String, Object)}</li> 073 * </ul> 074 * </li> 075 * <li>{@link org.apache.commons.beanutils.BeanUtilsBean} 076 * <ul> 077 * <li>{@link org.apache.commons.beanutils.BeanUtilsBean#copyProperty(Object, String, Object)}</li> 078 * <li>{@link org.apache.commons.beanutils.BeanUtilsBean#setProperty(Object, String, Object)}</li> 079 * </ul> 080 * </li> 081 * <li>{@link org.apache.commons.beanutils.locale.LocaleBeanUtilsBean} 082 * <ul> 083 * <li>{@link org.apache.commons.beanutils.locale.LocaleBeanUtilsBean#setProperty(Object, 084 * String, Object, String)}</li> 085 * </ul> 086 * </li> 087 * </ul> 088 * 089 * @version $Id$ 090 * @see org.apache.commons.beanutils.PropertyUtilsBean#setResolver(Resolver) 091 * @since 1.8.0 092 */ 093public interface Resolver { 094 095 /** 096 * Extract the index value from the property expression or -1. 097 * 098 * @param expression The property expression 099 * @return The index value or -1 if the property is not indexed 100 * @throws IllegalArgumentException If the indexed property is illegally 101 * formed or has an invalid (non-numeric) value 102 */ 103 int getIndex(String expression); 104 105 /** 106 * Extract the map key from the property expression or <code>null</code>. 107 * 108 * @param expression The property expression 109 * @return The index value 110 * @throws IllegalArgumentException If the mapped property is illegally formed 111 */ 112 String getKey(String expression); 113 114 /** 115 * Return the property name from the property expression. 116 * 117 * @param expression The property expression 118 * @return The property name 119 */ 120 String getProperty(String expression); 121 122 /** 123 * Indicates whether or not the expression 124 * contains nested property expressions or not. 125 * 126 * @param expression The property expression 127 * @return The next property expression 128 */ 129 boolean hasNested(String expression); 130 131 /** 132 * Indicate whether the expression is for an indexed property or not. 133 * 134 * @param expression The property expression 135 * @return <code>true</code> if the expresion is indexed, 136 * otherwise <code>false</code> 137 */ 138 boolean isIndexed(String expression); 139 140 /** 141 * Indicate whether the expression is for a mapped property or not. 142 * 143 * @param expression The property expression 144 * @return <code>true</code> if the expresion is mapped, 145 * otherwise <code>false</code> 146 */ 147 boolean isMapped(String expression); 148 149 /** 150 * Extract the next property expression from the 151 * current expression. 152 * 153 * @param expression The property expression 154 * @return The next property expression 155 */ 156 String next(String expression); 157 158 /** 159 * Remove the last property expresson from the 160 * current expression. 161 * 162 * @param expression The property expression 163 * @return The new expression value, with first property 164 * expression removed - null if there are no more expressions 165 */ 166 String remove(String expression); 167 168}