org.apache.juneau.rest.RestGuard Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * 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. *
// ***************************************************************************************************************************
package org.apache.juneau.rest;
import static javax.servlet.http.HttpServletResponse.*;
import org.apache.juneau.rest.annotation.*;
/**
* REST method guard.
*
* Description:
*
* Implements a guard mechanism for REST method calls that allows requests to be rejected before invocation of the REST
* method.
* For example, guards can be used to ensure that only administrators can call certain methods.
*
*
* Guards are applied to REST methods declaratively through the {@link RestResource#guards()} or
* {@link RestMethod#guards()} annotations.
*
*
* If multiple guards are specified, ALL guards must pass in order for the request to proceed.
*
*
How to implement
*
* Typically, guards will be used for permissions checking on the user making the request, but it can also be used for
* other purposes like pre-call validation of a request.
*
*
* Implementers should simply throw a {@link RestException} from the {@link #guard(RestRequest, RestResponse)}
* method to abort processing on the current request.
*
*
* Guards must implement a no-args constructor.
*
*
Example usage:
*
* public MyResource extends RestServlet {
*
* // Delete method with guard that only allows Billy to call it.
* @RestMethod (name=DELETE , guards=BillyGuard.class )
* public doDelete(RestRequest req, RestResponse res) throws Exception {...}
* }
*
*
* Example implementation:
*
* // Define a guard that only lets Billy make a request
* public BillyGuard extends RestGuard {
*
* @Override
* public boolean isRequestAllowed(RestRequest req) {
* return req.getUserPrincipal().getName().contains("Billy" );
* }
* }
*
*/
public abstract class RestGuard {
/**
* Checks the current HTTP request and throws a {@link RestException} if the guard does not permit the request.
*
*
* By default, throws an SC_FORBIDDEN exception if {@link #isRequestAllowed(RestRequest)} returns
* false .
*
*
* Subclasses are free to override this method to tailor the behavior of how to handle unauthorized requests.
*
* @param req The servlet request.
* @param res The servlet response.
* @throws RestException Thrown to abort processing on current request.
* @return
* true if request can proceed.
* Specify false if you're doing something like a redirection to a login page.
*/
public boolean guard(RestRequest req, RestResponse res) throws RestException {
if (! isRequestAllowed(req))
throw new RestException(SC_FORBIDDEN, "Access denied by guard");
return true;
}
/**
* Returns true if the specified request can pass through this guard.
*
* @param req The servlet request.
* @return true if the specified request can pass through this guard.
*/
public abstract boolean isRequestAllowed(RestRequest req);
}