1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package android.util; 17 18 19 /** 20 * A property is an abstraction that can be used to represent a <emb>mutable</em> value that is held 21 * in a <em>host</em> object. The Property's {@link #set(Object, Object)} or {@link #get(Object)} 22 * methods can be implemented in terms of the private fields of the host object, or via "setter" and 23 * "getter" methods or by some other mechanism, as appropriate. 24 * 25 * @param <T> The class on which the property is declared. 26 * @param <V> The type that this property represents. 27 */ 28 public abstract class Property<T, V> { 29 30 private final String mName; 31 private final Class<V> mType; 32 33 /** 34 * This factory method creates and returns a Property given the <code>class</code> and 35 * <code>name</code> parameters, where the <code>"name"</code> parameter represents either: 36 * <ul> 37 * <li>a public <code>getName()</code> method on the class which takes no arguments, plus an 38 * optional public <code>setName()</code> method which takes a value of the same type 39 * returned by <code>getName()</code> 40 * <li>a public <code>isName()</code> method on the class which takes no arguments, plus an 41 * optional public <code>setName()</code> method which takes a value of the same type 42 * returned by <code>isName()</code> 43 * <li>a public <code>name</code> field on the class 44 * </ul> 45 * 46 * <p>If either of the get/is method alternatives is found on the class, but an appropriate 47 * <code>setName()</code> method is not found, the <code>Property</code> will be 48 * {@link #isReadOnly() readOnly}. Calling the {@link #set(Object, Object)} method on such 49 * a property is allowed, but will have no effect.</p> 50 * 51 * <p>If neither the methods nor the field are found on the class a 52 * {@link NoSuchPropertyException} exception will be thrown.</p> 53 */ of(Class<T> hostType, Class<V> valueType, String name)54 public static <T, V> Property<T, V> of(Class<T> hostType, Class<V> valueType, String name) { 55 return new ReflectiveProperty<T, V>(hostType, valueType, name); 56 } 57 58 /** 59 * A constructor that takes an identifying name and {@link #getType() type} for the property. 60 */ Property(Class<V> type, String name)61 public Property(Class<V> type, String name) { 62 mName = name; 63 mType = type; 64 } 65 66 /** 67 * Returns true if the {@link #set(Object, Object)} method does not set the value on the target 68 * object (in which case the {@link #set(Object, Object) set()} method should throw a {@link 69 * NoSuchPropertyException} exception). This may happen if the Property wraps functionality that 70 * allows querying the underlying value but not setting it. For example, the {@link #of(Class, 71 * Class, String)} factory method may return a Property with name "foo" for an object that has 72 * only a <code>getFoo()</code> or <code>isFoo()</code> method, but no matching 73 * <code>setFoo()</code> method. 74 */ isReadOnly()75 public boolean isReadOnly() { 76 return false; 77 } 78 79 /** 80 * Sets the value on <code>object</code> which this property represents. If the method is unable 81 * to set the value on the target object it will throw an {@link UnsupportedOperationException} 82 * exception. 83 */ set(T object, V value)84 public void set(T object, V value) { 85 throw new UnsupportedOperationException("Property " + getName() +" is read-only"); 86 } 87 88 /** 89 * Returns the current value that this property represents on the given <code>object</code>. 90 */ get(T object)91 public abstract V get(T object); 92 93 /** 94 * Returns the name for this property. 95 */ getName()96 public String getName() { 97 return mName; 98 } 99 100 /** 101 * Returns the type for this property. 102 */ getType()103 public Class<V> getType() { 104 return mType; 105 } 106 } 107