001 /*** 002 * 003 * Copyright (c) 2007 Paul Hammant 004 * All rights reserved. 005 * 006 * Redistribution and use in source and binary forms, with or without 007 * modification, are permitted provided that the following conditions 008 * are met: 009 * 1. Redistributions of source code must retain the above copyright 010 * notice, this list of conditions and the following disclaimer. 011 * 2. Redistributions in binary form must reproduce the above copyright 012 * notice, this list of conditions and the following disclaimer in the 013 * documentation and/or other materials provided with the distribution. 014 * 3. Neither the name of the copyright holders nor the names of its 015 * contributors may be used to endorse or promote products derived from 016 * this software without specific prior written permission. 017 * 018 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 019 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 020 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 021 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 022 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 023 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 024 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 025 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 026 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 027 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 028 * THE POSSIBILITY OF SUCH DAMAGE. 029 */ 030 031 package com.thoughtworks.paranamer; 032 033 import java.lang.reflect.AccessibleObject; 034 import java.lang.reflect.Constructor; 035 import java.lang.reflect.Method; 036 037 /** 038 * Paranamer allows lookups of methods and constructors by parameter names. 039 * 040 * @author Paul Hammant 041 * @author Mauro Talevi 042 */ 043 public interface Paranamer { 044 045 static final String[] EMPTY_NAMES = new String[0]; 046 047 /** 048 * Parameter names are available, but not for that class. 049 * @deprecated 050 */ 051 int NO_PARAMETER_NAMES_FOR_CLASS = 2; 052 053 /** 054 * Parameter names are available for that class, but not for that constructor or 055 * method. 056 * @deprecated 057 */ 058 int NO_PARAMETER_NAMES_FOR_CLASS_AND_MEMBER = 3; 059 060 /** 061 * Parameter names are generally not available. 062 * @deprecated 063 */ 064 int NO_PARAMETER_NAMES_LIST = 1; 065 066 /** 067 * Parameter names are available for that class and constructor/method. 068 * @deprecated 069 */ 070 int PARAMETER_NAMES_FOUND = 0; 071 072 /** 073 * Determine if the parameter names are available. 074 * <p> 075 * Known issues: 076 * <ul> 077 * <li>If a method that belongs to the superclass is requested, this call may fail 078 * where {@link #lookupParameterNames(AccessibleObject)} will succeed.</li> 079 * <li>If a method or constructor is overloaded, this call may pass where 080 * {@link #lookupParameterNames(AccessibleObject)} will fail.</li> 081 * </ul> 082 * Use of this method is discouraged. 083 * 084 * @param clazz 085 * the name of the class to which the method or constructor belongs. 086 * @param constructorOrMethodName 087 * the base name of the {@link Method} or {@link Constructor}. If a 088 * request is being made for the constructor, this should be 089 * <code>"<init>"</code>. 090 * @return An int encoding the parameter names availability. 091 * @throws NullPointerException 092 * if either parameter is null. 093 * @throws SecurityException 094 * if reflection is not permitted on clazz 095 * @deprecated since 1.5, use the overloaded lookupParameterNames instead 096 */ 097 public int areParameterNamesAvailable(Class clazz, 098 String constructorOrMethodName); 099 100 /** 101 * Lookup the parameter names of a given method. 102 * 103 * @param methodOrConstructor 104 * the {@link Method} or {@link Constructor} for which the parameter names 105 * are looked up. 106 * @return A list of the parameter names. 107 * @throws ParameterNamesNotFoundException 108 * if no parameter names were found. 109 * @throws NullPointerException 110 * if the parameter is null. 111 * @throws SecurityException 112 * if reflection is not permitted on the containing {@link Class} of the 113 * parameter 114 */ 115 public String[] lookupParameterNames(AccessibleObject methodOrConstructor); 116 117 /** 118 * Lookup the parameter names of a given method. 119 * 120 * @param methodOrConstructor 121 * the {@link Method} or {@link Constructor} for which the parameter names 122 * are looked up. 123 * @return A list of the parameter names. 124 * @throws ParameterNamesNotFoundException 125 * if no parameter names were found. 126 * @throws NullPointerException 127 * if the parameter is null. 128 * @throws SecurityException 129 * if reflection is not permitted on the containing {@link Class} of the 130 * parameter 131 */ 132 public String[] lookupParameterNames(AccessibleObject methodOrConstructor, boolean throwExceptionIfMissing); 133 134 }