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

Role guards
 
<p>
	Specialized guards are provided for controlling access to servlet classes and methods based on user roles.
	These are controlled via annotations on the REST class and methods:
</p>
<ul class='javatree'>
	<li class='ja'>{@link oajr.annotation.Rest}
	<ul>
		<li class='jf'>{@link oajr.annotation.Rest#roleGuard() roleGuard()}
		<li class='jf'>{@link oajr.annotation.Rest#rolesDeclared() rolesDeclared()}
	</ul>
	<li class='ja'>{@link oajr.annotation.RestMethod}
	<ul>
		<li class='jf'>{@link oajr.annotation.RestMethod#roleGuard() roleGuard()}
		<li class='jf'>{@link oajr.annotation.RestMethod#rolesDeclared() rolesDeclared()}
	</ul>
</ul>
<p>
	The <c>roleGuard()</c> annotation is an expression that defines whether a user with specified roles are allowed
	to access methods.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<jc>// Only admin users or users with both read/write and special access 
	// can run any methods on this class.</jc>
	<ja>@Rest</ja>(
		path=<js>"/foo"</js>,
		roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE &amp;&amp; ROLE_SPECIAL)"</js>
	)
	<jk>public class</jk> MyResource <jk>extends</jk> RestServlet {
		...
	}
</p>
<p>
	The syntax allows for any of the following:
</p>
<ul>
	<li><js>"foo"</js> - Single arguments.
	<li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments.
	<li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax.
	<li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax.
	<li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>.
	<li><js>"fo* &amp; *oo"</js> - Multiple AND'ed arguments, ampersand syntax.
	<li><js>"fo* &amp;&amp; *oo"</js> - Multiple AND'ed arguments, Java-AND syntax.
	<li><js>"fo* || (*oo || bar)"</js> - Parenthesis.
</ul>

<p>
 	If patterns are used, you must specify the list of declared roles using the <c>rolesDeclared()</c> annotations.
 	This declares the list of all possible user roles and is needed because the servlet API does not provide this
 	capability.
</p>

<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@Rest</ja>(
		rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>,
		roleGuard=<js>"ROLE_ADMIN || (*WRITE* &amp;&amp; *SPECIAL*)"</js>
	)
	<jk>public class</jk> MyResource <jk>extends</jk> RestServlet {
		...
	}
</p>