001 /* 002 * Created on Aug 17, 2007 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with 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 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 * 014 * Copyright @2007-2009 the original author or authors. 015 */ 016 package org.fest.reflect.method; 017 018 import static org.fest.reflect.method.Invoker.newInvoker; 019 import static org.fest.reflect.method.MethodParameterTypes.newParameterTypes; 020 import static org.fest.reflect.method.MethodReturnType.newReturnType; 021 import static org.fest.reflect.method.MethodReturnTypeRef.newReturnTypeRef; 022 import static org.fest.util.Strings.isEmpty; 023 024 import org.fest.reflect.reference.TypeRef; 025 026 027 028 /** 029 * Understands the name of a method to invoke using Java Reflection. 030 * <p> 031 * The following is an example of proper usage of this class: 032 * <pre> 033 * // Equivalent to call 'person.setName("Luke")' 034 * {@link org.fest.reflect.core.Reflection#method(String) method}("setName").{@link MethodName#withParameterTypes(Class...) withParameterTypes}(String.class) 035 * .{@link MethodParameterTypes#in(Object) in}(person) 036 * .{@link Invoker#invoke(Object...) invoke}("Luke"); 037 * 038 * // Equivalent to call 'person.concentrate()' 039 * {@link org.fest.reflect.core.Reflection#method(String) method}("concentrate").{@link MethodName#in(Object) in}(person).{@link Invoker#invoke(Object...) invoke}(); 040 * 041 * // Equivalent to call 'person.getName()' 042 * String name = {@link org.fest.reflect.core.Reflection#method(String) method}("getName").{@link MethodName#withReturnType(Class) withReturnType}(String.class) 043 * .{@link MethodReturnType#in(Object) in}(person) 044 * .{@link Invoker#invoke(Object...) invoke}(); 045 * 046 * // Equivalent to call 'jedi.getPowers()' 047 * List<String> powers = {@link org.fest.reflect.core.Reflection#method(String) method}("getPowers").{@link MethodName#withReturnType(TypeRef) withReturnType}(new {@link TypeRef TypeRef}<List<String>>() {}) 048 * .{@link MethodReturnTypeRef#in(Object) in}(person) 049 * .{@link Invoker#invoke(Object...) invoke}(); 050 * </pre> 051 * </p> 052 * 053 * @author Yvonne Wang 054 * @author Alex Ruiz 055 */ 056 public final class MethodName { 057 058 /** 059 * Creates a new <code>{@link MethodName}</code>: the starting point of the fluent interface for accessing methods 060 * using Java Reflection. 061 * @param name the name of the method to invoke using Java Reflection. 062 * @return the created <code>MethodName</code>. 063 * @throws NullPointerException if the given name is <code>null</code>. 064 * @throws IllegalArgumentException if the given name is empty. 065 */ 066 public static MethodName startMethodAccess(String name) { 067 validateIsNotNullOrEmpty(name); 068 return new MethodName(name); 069 } 070 071 private static void validateIsNotNullOrEmpty(String name) { 072 if (name == null) 073 throw new NullPointerException("The name of the method to access should not be null"); 074 if (isEmpty(name)) 075 throw new IllegalArgumentException("The name of the method to access should not be empty"); 076 } 077 078 private final String name; 079 080 private MethodName(String name) { 081 this.name = name; 082 } 083 084 /** 085 * Specifies the return type of the method to invoke. This method call is optional if the return type of the method to 086 * invoke is <code>void</code>. 087 * @param <T> the generic type of the method's return type. 088 * @param type the return type of the method to invoke. 089 * @return the created return type holder. 090 * @throws NullPointerException if the given type is <code>null</code>. 091 */ 092 public <T> MethodReturnType<T> withReturnType(Class<T> type) { 093 return newReturnType(name, type); 094 } 095 096 /** 097 * Specifies the return type reference of the method to invoke. This method call is optional if the return type of the 098 * method to invoke is <code>void</code>. 099 * @param <T> the generic type of the method's return type. 100 * @param type the return type reference of the method to invoke. 101 * @return the created return type holder. 102 * @throws NullPointerException if the given type reference is <code>null</code>. 103 * @since 1.1 104 */ 105 public <T> MethodReturnTypeRef<T> withReturnType(TypeRef<T> type) { 106 return newReturnTypeRef(name, type); 107 } 108 109 /** 110 * Specifies the parameter types of the method to invoke. This method call is optional if the method to invoke does 111 * not take arguments. 112 * @param parameterTypes the parameter types of the method to invoke. 113 * @return the created parameter types holder. 114 * @throws NullPointerException if the array of parameter types is <code>null</code>. 115 */ 116 public MethodParameterTypes<Void> withParameterTypes(Class<?>... parameterTypes) { 117 return newParameterTypes(name, parameterTypes); 118 } 119 120 /** 121 * Creates a new invoker for a method that takes no parameters and return value <code>void</code>. 122 * @param target the object containing the method to invoke. 123 * @return the created method invoker. 124 * @throws NullPointerException if the given target is <code>null</code>. 125 */ 126 public Invoker<Void> in(Object target) { 127 return newInvoker(name, target); 128 } 129 }