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}