<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

@RestMethod(matchers)

<p>
	{@link oajr.RestMatcher RestMatchers} are used to allow multiple Java methods to be 
	tied to the same HTTP method and path, but differentiated by some request attribute such as a specific 
	header value.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<jc>// GET method that gets invoked for administrators</jc>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/*"</js>, matchers=IsAdminMatcher.<jk>class</jk>)
	<jk>public</jk> Object doGetForAdmin() {
		...
	}

	<jc>// GET method that gets invoked for everyone else</jc>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/*"</js>)
	<jk>public</jk> Object doGetForEveryoneElse() {
		...
	}
</p>
<p>
	The interface for matchers is simple:
</p>
<p class='bpcode w800'>
	<jk>public class</jk> IsAdminMatcher <jk>extends</jk> RestMatcher {

		<ja>@Override</ja> <jc>/* RestMatcher */</jc>
		<jk>public boolean</jk> matches(RestRequest req) {
			<jk>return</jk> req.isUserInRole(<js>"ADMINS_GROUP"</js>);
		}
	}
</p>

<ul class='notes'>
	<li>
		If no methods are found with a matching matcher, a <l>412 Precondition Failed</l> status is returned.
	<li>
		If multiple matchers are specified on the same method, ONLY ONE matcher needs to match for the 
		method to be invoked.
	<li>
		Note that you CANNOT define identical paths on different methods UNLESS you use matchers.
		<br>That includes paths that are only different in variable names (e.g. <l>"/foo/{bar}"</l> and 
		<l>"/foo/{baz}"</l>).
		<br>If you try to do so, a <l>ServletException</l> will be thrown on startup.
	<li>
		Methods with matchers take precedence over methods without.
		<br>Otherwise, methods are attempted in the order they appear in the class.
</ul>

<ul class='seealso'>
	<li class='ja'>{@link oajr.annotation.RestMethod#matchers RestMethod(matchers)}
	<li class='jc'>{@link oajr.matchers.MultipartFormDataMatcher}
	<li class='jc'>{@link oajr.matchers.UrlEncodedFormMatcher}
</ul>