{8.1.0-new} Role guards

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:

- {@link oajr.annotation.Rest}
  - {@link oajr.annotation.Rest#roleGuard() roleGuard()}
  - {@link oajr.annotation.Rest#rolesDeclared() rolesDeclared()}
- {@link oajr.annotation.RestMethod}
  - {@link oajr.annotation.RestMethod#roleGuard() roleGuard()}
  - {@link oajr.annotation.RestMethod#rolesDeclared() rolesDeclared()}

The roleGuard() annotation is an expression that defines whether a user with specified roles are allowed to access methods.

##### Example:

// Only admin users or users with both read/write and special access // can run any methods on this class. @Rest( path="/foo", roleGuard="ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)" ) public class MyResource extends RestServlet { ... }

The syntax allows for any of the following:

- "foo" - Single arguments.
- "foo,bar,baz" - Multiple OR'ed arguments.
- "foo | bar | baz" - Multiple OR'ed arguments, pipe syntax.
- "foo || bar || baz" - Multiple OR'ed arguments, Java-OR syntax.
- "fo*" - Patterns including '*' and '?'.
- "fo* & *oo" - Multiple AND'ed arguments, ampersand syntax.
- "fo* && *oo" - Multiple AND'ed arguments, Java-AND syntax.
- "fo* || (*oo || bar)" - Parenthesis.

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

##### Example:

@Rest( rolesDeclared="ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL", roleGuard="ROLE_ADMIN || (*WRITE* && *SPECIAL*)" ) public class MyResource extends RestServlet { ... }