001/*license*\ 002 Codelet: Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com) 003 004 This software is dual-licensed under the: 005 - Lesser General Public License (LGPL) version 3.0 or, at your option, any later version; 006 - Apache Software License (ASL) version 2.0. 007 008 Either license may be applied at your discretion. More information may be found at 009 - http://en.wikipedia.org/wiki/Multi-licensing. 010 011 The text of both licenses is available in the root directory of this project, under the names "LICENSE_lgpl-3.0.txt" and "LICENSE_asl-2.0.txt". The latest copies may be downloaded at: 012 - LGPL 3.0: https://www.gnu.org/licenses/lgpl-3.0.txt 013 - ASL 2.0: http://www.apache.org/licenses/LICENSE-2.0.txt 014\*license*/ 015package com.github.aliteralmind.codelet.simplesig; 016 import java.lang.reflect.Method; 017 import com.github.xbn.lang.reflect.RTNoSuchMethodException; 018 import com.github.xbn.lang.CrashIfObject; 019 import java.util.List; 020/** 021 <p>Search term for methods.</p> 022 <A NAME="xmpl_method"></a><h3>{@link com.github.aliteralmind.codelet.simplesig.MethodSigSearchTerm}: Example</h3> 023 024{@.codelet.and.out com.github.aliteralmind.codelet.examples.simplesig.MethodSigSearchTermXmpl%()} 025 026 * @since 0.1.0 027 * @author Copyright (C) 2014, Jeff Epstein ({@code aliteralmind __DASH__ github __AT__ yahoo __DOT__ com}), dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. <a href="http://codelet.aliteralmind.com">{@code http://codelet.aliteralmind.com}</a>, <a href="https://github.com/aliteralmind/codelet">{@code https://github.com/aliteralmind/codelet}</a> 028 **/ 029public class MethodSigSearchTerm extends SimpleParamSigSearchTerm { 030 /** 031 <p>Create a new instance.</p> 032 033 <h4>Examples</h4> 034 035<blockquote><pre>doSomething()</pre></blockquote> 036 037 <p>A function named {@code "doSomething"} with exactly zero parameters.</p> 038 039<blockquote><pre>doSomething(*)</pre></blockquote> 040 041 <p>One or more parameters of any type.</p> 042 043<blockquote><pre>doSomething(String, *)</pre></blockquote> 044 045 <p>A {@code java.lang.String}, followed by one or more parameters of any type.</p> 046 047<blockquote><pre>doSomething(String, *, int...)</pre></blockquote> 048 049 <p>A {@code java.lang.String} and {@code int}-ellipsis, with one or more parameters of any type between.</p> 050 051 <p>This first calls 052 <br/> <code>{@link SimpleParamSigSearchTerm#SimpleParamSigSearchTerm(String, Appendable, Appendable) super}(search_termSig)</code></p> 053 054 * @param search_termSig The function name may not be empty. 055 */ 056 public MethodSigSearchTerm(String search_termSig, Appendable debugBasics_ifNonNull, Appendable dbgDoesMatch_ifNonNull) { 057 super(search_termSig, debugBasics_ifNonNull, dbgDoesMatch_ifNonNull); 058 if(getMethodName().length() == 0) { 059 throw new SimpleParamSigSearchTermFormatException(search_termSig, "Method shortcut has no method name: \"" + search_termSig + "\""); 060 } 061 } 062 /** 063 <p>Does any match?.</p> 064 065 * @param all_methods May not be {@code null}. 066 * @return If 067 <br/> <code>all_methods.{@link AllSimpleParamSignatures#getMethodMap() getMethodMap}().get({@link SimpleParamSigSearchTerm#getMethodName() getMethodName}())</code> 068 <br/>returns a non-null list, this returns <code>{@link SimpleParamSigSearchTerm#doesMatchAnyProt(List) doesMatchAnyProt}(<i>[the-list]</i>)*</code> 069 * @see #doesMatchOnlyOne(AllSimpleParamSignatures) doesMatchOnlyOne 070 */ 071 public boolean doesMatchAny(AllSimpleParamSignatures all_methods) { 072 List<MethodSimpleParamSig> methodsWithNameList = null; 073 try { 074 methodsWithNameList = all_methods.getMethodMap().get(getMethodName()); 075 if(methodsWithNameList == null) { 076 return false; 077 } 078 return doesMatchAnyProt(methodsWithNameList); 079 } catch(RuntimeException rx) { 080 throw CrashIfObject.nullOrReturnCause(all_methods, "all_methods", null, rx); 081 } 082 } 083 /** 084 <p>Does exactly one match?.</p> 085 086 * @param all_methods May not be {@code null}. 087 * @return If 088 <br/> <code>all_methods.{@link AllSimpleParamSignatures#getMethodMap() getMethodMap}().get({@link SimpleParamSigSearchTerm#getMethodName() getMethodName}())</code> 089 <br/>returns a non-null list, this returns <code>{@link SimpleParamSigSearchTerm#doesMatchOnlyOneProt(List) doesMatchOnlyOneProt}(<i>[the-list]</i>)*</code> 090 * @see #doesMatchAny(AllSimpleParamSignatures) doesMatchAny 091 */ 092 public boolean doesMatchOnlyOne(AllSimpleParamSignatures all_methods) { 093 List<MethodSimpleParamSig> methodsWithNameList = null; 094 try { 095 methodsWithNameList = all_methods.getMethodMap().get(getMethodName()); 096 if(methodsWithNameList == null) { 097 return false; 098 } 099 return doesMatchOnlyOneProt(methodsWithNameList); 100 } catch(RuntimeException rx) { 101 throw CrashIfObject.nullOrReturnCause(all_methods, "all_methods", null, rx); 102 } 103 } 104 /** 105 <p>Get a new list of all matches.</p> 106 107 * @param all_methods May not be {@code null}. 108 * @param crashIf_zero If {@code com.github.xbn.lang.reflect.CrashIfZero#YES YES}, then zero matches is unacceptable. May not be {@code null}. 109 * @return {@linkplain SimpleParamSigSearchTerm#getAllMatchesProt(List, CrashIfZero) all matches}, or {@code null} if {@linkplain #doesMatchAny(AllSimpleParamSignatures) no matches} 110 * @exception RTNoSuchMethodException If zero matches and {@code crashIf_zero} is {@code YES}. 111 */ 112 public List<MethodSimpleParamSig> getAllMatches(AllSimpleParamSignatures all_methods, CrashIfZero crashIf_zero) { 113 List<MethodSimpleParamSig> methodsWithNameList = null; 114 try { 115 methodsWithNameList = all_methods.getMethodMap().get(getMethodName()); 116 if(methodsWithNameList == null) { 117 if(crashIf_zero.isNo()) { 118 return null; 119 } else { 120 throw new RTNoSuchMethodException("getMethodName()=\"" + getMethodName() + "\""); 121 } 122 } 123 @SuppressWarnings("unchecked") 124 List<MethodSimpleParamSig> matches = (List<MethodSimpleParamSig>)getAllMatchesProt( 125 methodsWithNameList, crashIf_zero); 126 return matches; 127 } catch(RuntimeException rx) { 128 throw CrashIfObject.nullOrReturnCause(all_methods, "all_methods", null, rx); 129 } 130 } 131 /** 132 <p>Get the first and only match.</p> 133 134 * @return <code>{@link #getFirstMatch(AllSimpleParamSignatures, CrashIfZero, CrashIfMoreThanOne) getFirstMatch}(all_methods, {@link CrashIfZero}.{@link CrashIfZero#YES YES}, {@link CrashIfMoreThanOne CrashIfMoreThanOne}.{@link CrashIfMoreThanOne#YES YES})</code> 135 * @see #doesMatchOnlyOne(AllSimpleParamSignatures) doesMatchOnlyOne 136 * @see #getFirstMatch(AllSimpleParamSignatures, CrashIfZero, CrashIfMoreThanOne) getFirstMatch 137 * @see #getAllMatches(AllSimpleParamSignatures, CrashIfZero) getOnlyMatch 138 */ 139 public MethodSimpleParamSig getOnlyMatch(AllSimpleParamSignatures all_methods) { 140 return getFirstMatch(all_methods, CrashIfZero.YES, CrashIfMoreThanOne.YES); 141 } 142 /** 143 <p>Get the first match.</p> 144 145 * @param all_methods May not be {@code null}. 146 * @param crashIf_zero If {@code com.github.xbn.lang.reflect.CrashIfZero#YES YES}, then zero matches is unacceptable. May not be {@code null}. 147 * @return The {@linkplain SimpleParamSigSearchTerm#getFirstMatchProt(List, CrashIfZero, CrashIfMoreThanOne) first match}, or {@code null} if no matches. 148 * @exception RTNoSuchMethodException If zero matches and {@code crashIf_zero} is {@code YES}. 149 * @see #getOnlyMatch(AllSimpleParamSignatures) getOnlyMatch 150 */ 151 public MethodSimpleParamSig getFirstMatch(AllSimpleParamSignatures all_methods, CrashIfZero crashIf_zero, CrashIfMoreThanOne crashIf_moreThanOne) { 152 List<MethodSimpleParamSig> methodsWithNameList = null; 153 try { 154 methodsWithNameList = all_methods.getMethodMap().get(getMethodName()); 155 if(methodsWithNameList == null) { 156 if(crashIf_zero.isNo()) { 157 return null; 158 } else { 159 throw new RTNoSuchMethodException("getMethodName()=\"" + getMethodName() + "\""); 160 } 161 } 162 return (MethodSimpleParamSig)getFirstMatchProt(methodsWithNameList, crashIf_zero, crashIf_moreThanOne); 163 } catch(RuntimeException rx) { 164 throw CrashIfObject.nullOrReturnCause(all_methods, "all_methods", null, rx); 165 } 166 } 167 /** 168 <p>Get the single matching method from an all-signature object.</p> 169 170 * @return <code>(new {@link #MethodSigSearchTerm(String, Appendable, Appendable) MethodSigSearchTerm}(sig_searchTerm, debugBasics_ifNonNull, dbgDoesMatch_ifNonNull)). 171 <br/> {@link MethodSigSearchTerm#getOnlyMatch(AllSimpleParamSignatures) getOnlyMatch}(all_sigs).{@link MethodSimpleParamSig#getMethod() getMethod}()</code> 172 */ 173 public static final Method getMethodFromAllSigsAndSearchTerm(AllSimpleParamSignatures all_sigs, String sig_searchTerm, Appendable debugBasics_ifNonNull, Appendable dbgDoesMatch_ifNonNull) { 174 try { 175 return (new MethodSigSearchTerm(sig_searchTerm, debugBasics_ifNonNull, dbgDoesMatch_ifNonNull)). 176 getOnlyMatch(all_sigs).getMethod(); 177 } catch(RTNoSuchMethodException nsmx) { 178 throw new RTNoSuchMethodException("Attempting to get java.lang.reflect.Method object for JavaDoc link. target_class:" + all_sigs.getContainingClass().getName(), nsmx); 179 } catch(RuntimeException rx) { 180 throw CrashIfObject.nullOrReturnCause(all_sigs, "all_sigs", null, rx); 181 } 182 } 183}