/*
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the "License").  You may not use this file except
 * in compliance with the License.
 * 
 * You can obtain a copy of the license at
 * http://www.opensource.org/licenses/cddl1.php
 * See the License for the specific language governing
 * permissions and limitations under the License.
 */

/*
 * SecurityContext.java
 *
 * Created on September 11, 2007, 8:29 AM
 *
 * @author Ryan J. McDonough <ryan@damnhandy.com>
 */

package javax.ws.rs.core;

import java.security.Principal;

/**
 * An injectable interface that provides access to security releated
 * information.
 *
 * @author Ryan J. McDonough <ryan@damnhandy.com>
 */
public interface SecurityContext {
    

    /**
     * Returns a java.security.Principal object containing the 
     * name of the current authenticated user. If the user 
     * has not been authenticated, the method returns null.
     *
     * @return the Princial that identifies the caller
     */
    public Principal getUserPrincipal();
    
    /**
     * Returns a boolean indicating whether the authenticated user is included 
     * in the specified logical "role". If the user has not been authenticated,
     * the method returns false.
     *
     * @param role
     */
    public boolean isUserInRole(String role);
    
    /**
     * Returns a boolean indicating whether this request was made 
     * using a secure channel, such as HTTPS.
     *
     * @return true if the request was made using a secure channel
     */
    public boolean isTransportSecure();
    
    /**
     * Returns the string value of the authentication scheme used to protect 
     * the resource. If the resource is not authenticated, null is returned.
     */
    public String getAuthenticationScheme();
    
}