<!--
/***************************************************************************************************************************
 * 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.
 ***************************************************************************************************************************/
 -->

Guards

<p>
	Guards are classes that control access to REST classes and methods.
</p>
<p>
	Guards are associated with resource classes and methods via the following:
</p>
<ul class='javatree'>
	<li class='ja'>{@link oajr.annotation.Rest#guards() Rest(guards)} 
	<li class='ja'>{@link oajr.annotation.RestMethod#guards() RestMethod(guards)} 
	<li class='jm'>{@link oajr.RestContextBuilder#guards(Class...)} 
</ul>
<p class='bpcode w800'>
	<jc>// Define a guard that only lets Billy make a request</jc>
	<jk>public</jk> BillyGuard <jk>extends</jk> RestGuard {

		<ja>@Override</ja> <jc>/* RestGuard */</jc>
		<jk>public boolean</jk> isRequestAllowed(RestRequest req) {
			<jk>return</jk> req.getUserPrincipal().getName().equals(<js>"Billy"</js>);
		}
	}

	<jc>// Servlet with class-level guard applied</jc>
	<ja>@Rest</ja>(guards=BillyGuard.<jk>class</jk>)
	<jk>public</jk> MyRestServlet <jk>extends</jk> BasicRestServlet {

 		<jc>// Delete method that only Billy is allowed to call.</jc>
 		<ja>@RestMethod</ja>(name=<js>"DELETE"</js>)
		<jk>public</jk> doDelete(RestRequest req, RestResponse res) <jk>throws</jk> Exception {...}
 	}
</p>
<p>
	A common use for guards is to only allow admin access to certain Java methods...
</p>
<p class='bpcode w800'>
	<jc>// DELETE method</jc>
	<ja>@RestMethod</ja>(name=<jsf>DELETE</jsf>, guards={AdminGuard.<jk>class</jk>})
	<jk>public void</jk> doDelete(RestRequest req, RestResponse res) <jk>throws</jk> Exception {...}
</p>
<p class='bpcode w800'>
	<jk>public class</jk> AdminGuard <jk>extends</jk> RestGuard {

		<ja>@Override</ja> <jc>/* RestGuard */</jc>
		<jk>public boolean</jk> isRequestAllowed(RestRequest req) {
			<jk>return</jk> req.getUserPrincipal().isUserInRole(<js>"ADMIN"</js>);
		}
	}
</p>
<p>
	A guard failure results in an <l>HTTP 401 Unauthorized</l> response.
	However, this can be configured by overriding the 
	{@link oajr.RestGuard#guard(RestRequest,RestResponse)} and processing the response 
	yourself.
</p>
<p class='bpcode w800'>
	<jk>public class</jk> AdminGuard <jk>extends</jk> RestGuard {

		<ja>@Override</ja> <jc>/* RestGuard */</jc>
		<jk>public boolean</jk> guard(RestRequest req, RestResponse res) <jk>throws</jk> RestException {
			<jk>if</jk> (! isOkay(req))
				<jk>throw new</jk> RestException(<jsf>SC_FORBIDDEN</jsf>, <js>"Access denied!!!"</js>);
			<jk>return true</jk>;
		}
	}
</p>
<p>
	When guards are associated at the class-level, it's equivalent to associating guards on all Java methods on 
	the servlet.
	If multiple guards are present, ALL guards must pass.
</p>
<ul class='seealso'>
	<li class='jf'>{@link oajr.RestContext#REST_guards}
</ul>