/* | |
* Copyright 2005-2008 Les Hazlewood | |
* | |
* Licensed 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.jsecurity.mgt; | |
import org.jsecurity.authc.AuthenticationException; | |
import org.jsecurity.authc.AuthenticationToken; | |
import org.jsecurity.authc.Authenticator; | |
import org.jsecurity.authz.Authorizer; | |
import org.jsecurity.session.SessionFactory; | |
import org.jsecurity.subject.PrincipalCollection; | |
import org.jsecurity.subject.Subject; | |
/** | |
* A <tt>SecurityManager</tt> executes all security operations for <em>all</em> Subjects (aka users) across a | |
* single application. | |
* | |
* <p>The interface itself primarily exists as a convenience - it extends the {@link Authenticator}, | |
* {@link Authorizer}, and {@link SessionFactory} interfaces, thereby consolidating | |
* these behaviors into a single point of reference. For most JSecurity usages, this simplifies configuration and | |
* tends to be a more convenient approach than referencing <code>Authenticator</code>, <code>Authorizer</code>, and | |
* <code>SessionFactory</code> instances seperately; instead one only needs to interact with a | |
* single <tt>SecurityManager</tt> instance.</p> | |
* | |
* <p>In addition to the above three interfaces, three unique methods are provided by this interface by itself, | |
* {@link #login}, {@link #logout} and {@link #getSubject}. A {@link Subject Subject} executes | |
* authentication, authorization, and session operations for a <em>single</em> user, and as such can only be | |
* managed by <tt>A SecurityManager</tt> which is aware of all three functions. The three parent interfaces on the | |
* other hand do not 'know' about <tt>Subject</tt>s to ensure a clean separation of concerns. | |
* | |
* <p><b>Usage Note</b>: In actuality the large majority of application programmers won't interact with a SecurityManager | |
* very often, if at all. <em>Most</em> application programmers only care about security operations for the currently | |
* executing user. | |
* | |
* <p>In that case, the application programmer can call the | |
* {@link #getSubject() getSubject()} method and then use that returned instance for continued interaction with | |
* JSecurity. If your application code does not have a direct handle to the application's | |
* <code>SecurityManager</code>, you can use {@link org.jsecurity.SecurityUtils SecurityUtils} anywhere in your code | |
* to achieve the same result. | |
* | |
* <p>Framework developers on the other hand might find working with an actual SecurityManager useful. | |
* | |
* @see DefaultSecurityManager | |
* | |
* @since 0.2 | |
* | |
* @author Les Hazlewood | |
*/ | |
public interface SecurityManager extends Authenticator, Authorizer, SessionFactory { | |
/** | |
* Logs in a user, returning a Subject instance if the authentication is successful or throwing an | |
* <code>AuthenticationException</code> if it is not. | |
* | |
* <p>Note that using this method is an alternative to calling | |
* <code>{@link Subject#login(org.jsecurity.authc.AuthenticationToken) Subject.login(authenticationToken)}</code>. | |
* However most application developers find calling <code>subject.login(token)</code> more convenient than calling | |
* this method on the <code>SecurityManager</code> directly. | |
* | |
* @param authenticationToken the token representing the Subject's principal(s) and credential(s) | |
* @return an authenticated Subject upon a successful attempt | |
* @throws AuthenticationException if the login attempt failed. | |
* @since 0.9 | |
*/ | |
Subject login( AuthenticationToken authenticationToken ) throws AuthenticationException; | |
/** | |
* Logs out the specified Subject from the system. | |
* | |
* <p>Note that most application developers should not call this method unless they have a good reason for doing | |
* so. The preferred way to logout a Subject is to call <code>{@link Subject#logout Subject.logout()}</code>, not | |
* the <code>SecurityManager</code> directly. | |
* | |
* @param subjectIdentifier the identifier of the subject/user to log out. | |
* @see #getSubject() | |
* @since 0.9 | |
*/ | |
void logout( PrincipalCollection subjectIdentifier ); | |
/** | |
* Returns the <tt>Subject</tt> instance representing the currently executing user. | |
* @return the <tt>Subject</tt> instance representing the currently executing user. | |
* @since 0.9 | |
*/ | |
Subject getSubject(); | |
} |