[seam-commits] Seam SVN: r12447 - modules/security/trunk/api/src/main/java/org/jboss/seam/security.

[seam-commits at lists.jboss.org]

Author: shane.bryzak at jboss.com
Date: 2010-04-13 05:31:41 -0400 (Tue, 13 Apr 2010)
New Revision: 12447

Added:
   modules/security/trunk/api/src/main/java/org/jboss/seam/security/Identity.java
Log:
added Identity interface


Added: modules/security/trunk/api/src/main/java/org/jboss/seam/security/Identity.java
===================================================================
--- modules/security/trunk/api/src/main/java/org/jboss/seam/security/Identity.java	                        (rev 0)
+++ modules/security/trunk/api/src/main/java/org/jboss/seam/security/Identity.java	2010-04-13 09:31:41 UTC (rev 12447)
@@ -0,0 +1,146 @@
+package org.jboss.seam.security;
+
+import java.security.Principal;
+import java.util.Collection;
+
+import javax.security.auth.Subject;
+
+/**
+ * API for authorization and authentication via Seam security.
+ * 
+ * @author Shane Bryzak
+ */
+public interface Identity
+{   
+   /**
+    * Simple check that returns true if the user is logged in, without attempting to authenticate
+    * 
+    * @return true if the user is logged in
+    */
+   boolean isLoggedIn();
+   
+   /**
+    * Will attempt to authenticate quietly if the user's credentials are set and they haven't
+    * authenticated already.  A quiet authentication doesn't throw any exceptions if authentication
+    * fails.
+    * 
+    * @return true if the user is logged in, false otherwise
+    */
+   boolean tryLogin();
+
+   /**
+    * Return the currently authenticated Principal
+    * 
+    * @return
+    */
+   Principal getPrincipal();
+   
+   /**
+    * Return the Subject for the current session.
+    * 
+    * @return
+    */
+   Subject getSubject();
+      
+   /**
+    * Performs an authorization check, based on the specified security expression string.
+    * 
+    * @param expr The security expression string to evaluate
+    * @throws NotLoggedInException Thrown if the authorization check fails and
+    * the user is not authenticated
+    * @throws AuthorizationException Thrown if the authorization check fails and
+    * the user is authenticated
+    */
+   void checkRestriction(String expr);
+
+   /**
+    * Attempts to authenticate the user.  This method is distinct to the
+    * authenticate() method in that it raises events in response to whether
+    * authentication is successful or not.  The following events may be raised
+    * by calling login():
+    * 
+    * org.jboss.seam.security.events.LoggedInEvent - raised when authentication is successful
+    * org.jboss.seam.security.events.LoginFailedEvent - raised when authentication fails
+    * org.jboss.seam.security.events.AlreadyLoggedInEvent - raised if the user is already authenticated
+    * 
+    * @return String returns "loggedIn" if user is authenticated, or null if not.
+    */
+   String login();
+   
+   /**
+    * Attempts a quiet login, suppressing any login exceptions and not creating
+    * any faces messages. This method is intended to be used primarily as an
+    * internal API call, however has been made public for convenience.
+    */
+   void quietLogin();
+
+   /**
+    * Logs out the currently authenticated user
+    */
+   void logout();
+
+   /**
+    * Checks if the authenticated user is a member of the specified role.
+    * 
+    * @param role String The name of the role to check
+    * @return boolean True if the user is a member of the specified role
+    */
+   boolean hasRole(String role);
+   
+   /**
+    * Adds a role to the authenticated user.  If the user is not logged in,
+    * the role will be added to a list of roles that will be granted to the
+    * user upon successful authentication, but only during the authentication
+    * process.
+    * 
+    * @param role The name of the role to add
+    */
+   boolean addRole(String role);   /**
+   
+    * Removes a role from the authenticated user
+    * 
+    * @param role The name of the role to remove
+    */
+   void removeRole(String role);
+   
+   /**
+    * Checks that the current authenticated user is a member of
+    * the specified role.
+    * 
+    * @param role String The name of the role to check
+    * @throws AuthorizationException if the authenticated user is not a member of the role
+    */
+   void checkRole(String role);
+   
+   /**
+    * Checks if the currently authenticated user can perform the specified action
+    * on the specified target object.
+    * 
+    * @param target The target object for which the user wishes to perform a restricted action
+    * @param action The action that the user wishes to perform
+    * @throws NotLoggedInException if the current user is not authenticated
+    * @throws AuthorizationException if the current user does not have the necessary
+    * privileges to perform the specified action on the specified target object.   
+    */
+   void checkPermission(Object target, String action);
+   
+   /**
+    * Filters a collection of objects by a specified action, by removing the 
+    * objects from the collection for which the user doesn't have the necessary
+    * privileges to perform the specified action against that object.
+    * 
+    * @param collection The Collection to filter
+    * @param action The name of the action to filter by
+    */
+   void filterByPermission(Collection<?> collection, String action);
+   
+   /**
+    * Checks if the currently authenticated user has the necessary privileges to perform the
+    * specified action on the specified target object.
+    * 
+    * @param target  
+    * @param action
+    * @return true if the user has the required privileges, otherwise false
+    */
+   boolean hasPermission(Object target, String action);      
+}