001 /* 002 * Created on Aug 17, 2006 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with 005 * the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on 010 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the 011 * specific language governing permissions and limitations under the License. 012 * 013 * Copyright @2006-2009 the original author or authors. 014 */ 015 package org.fest.reflect.field; 016 017 import static org.fest.reflect.field.FieldType.newFieldType; 018 import static org.fest.reflect.field.FieldTypeRef.newFieldTypeRef; 019 import static org.fest.util.Strings.isEmpty; 020 021 import org.fest.reflect.reference.TypeRef; 022 023 024 /** 025 * Understands the name of a field to access using Java Reflection. 026 * <p> 027 * The following is an example of proper usage of this class: 028 * <pre> 029 * // Retrieves the value of the field "name" 030 * String name = {@link org.fest.reflect.core.Reflection#field(String) field}("name").{@link FieldName#ofType(Class) ofType}(String.class).{@link FieldType#in(Object) in}(person).{@link Invoker#get() get}(); 031 * 032 * // Sets the value of the field "name" to "Yoda" 033 * {@link org.fest.reflect.core.Reflection#field(String) field}("name").{@link FieldName#ofType(Class) ofType}(String.class).{@link FieldType#in(Object) in}(person).{@link Invoker#set(Object) set}("Yoda"); 034 * 035 * // Retrieves the value of the field "powers" 036 * List<String> powers = {@link org.fest.reflect.core.Reflection#field(String) field}("powers").{@link #ofType(TypeRef) ofType}(new {@link TypeRef TypeRef}<List<String>>() {}).{@link FieldTypeRef#in(Object) in}(jedi).{@link Invoker#get() get}(); 037 * 038 * // Sets the value of the field "powers" 039 * List<String> powers = new ArrayList<String>(); 040 * powers.add("heal"); 041 * {@link org.fest.reflect.core.Reflection#field(String) field}("powers").{@link #ofType(TypeRef) ofType}(new {@link TypeRef TypeRef}<List<String>>() {}).{@link FieldTypeRef#in(Object) in}(jedi).{@link Invoker#set(Object) set}(powers); 042 * </pre> 043 * </p> 044 * 045 * @author Alex Ruiz 046 */ 047 public final class FieldName { 048 049 private final String name; 050 051 /** 052 * Creates a new <code>{@link FieldName}</code>: the starting point of the fluent interface for accessing fields 053 * using Java Reflection. 054 * @param name the name of the field to access using Java Reflection. 055 * @return the created <code>FieldName</code>. 056 * @throws NullPointerException if the given name is <code>null</code>. 057 * @throws IllegalArgumentException if the given name is empty. 058 */ 059 public static FieldName beginFieldAccess(String name) { 060 validateIsNotNullOrEmpty(name); 061 return new FieldName(name); 062 } 063 064 private static void validateIsNotNullOrEmpty(String name) { 065 if (name == null) 066 throw new NullPointerException("The name of the field to access should not be null"); 067 if (isEmpty(name)) 068 throw new IllegalArgumentException("The name of the field to access should not be empty"); 069 } 070 071 private FieldName(String name) { 072 this.name = name; 073 } 074 075 /** 076 * Sets the type of the field to access. 077 * @param <T> the generic type of the field type. 078 * @param type the type of the field to access. 079 * @return a recipient for the field type. 080 * @throws NullPointerException if the given type is <code>null</code>. 081 */ 082 public <T> FieldType<T> ofType(Class<T> type) { 083 return newFieldType(name, type); 084 } 085 086 /** 087 * Sets the type reference of the field to access. This method reduces casting when the type of the field to access 088 * uses generics. 089 * <p> 090 * For example: 091 * <pre> 092 * List<String> powers = {@link org.fest.reflect.core.Reflection#field(String) field}("powers").{@link #ofType(TypeRef) ofType}(new {@link TypeRef TypeRef}<List<String>>() {}).{@link FieldTypeRef#in(Object) in}(jedi).{@link Invoker#get() get}(); 093 * </pre> 094 * </p> 095 * @param <T> the generic type of the field type. 096 * @param type the type of the field to access. 097 * @return a recipient for the field type. 098 * @throws NullPointerException if the given type reference is <code>null</code>. 099 * @since 1.1 100 */ 101 public <T> FieldTypeRef<T> ofType(TypeRef<T> type) { 102 return newFieldTypeRef(name, type); 103 } 104 }