[jboss-cvs] JBossAS SVN: r63111 - projects/security/security-docs/trunk/docs/guide/en/modules.

[jboss-cvs-commits at lists.jboss.org]

Author: anil.saldhana at jboss.com
Date: 2007-05-17 00:21:09 -0400 (Thu, 17 May 2007)
New Revision: 63111

Added:
   projects/security/security-docs/trunk/docs/guide/en/modules/securitycache.xml
   projects/security/security-docs/trunk/docs/guide/en/modules/securityclient.xml
Log:
SECURITY-53: integration doc

Added: projects/security/security-docs/trunk/docs/guide/en/modules/securitycache.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/securitycache.xml	                        (rev 0)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/securitycache.xml	2007-05-17 04:21:09 UTC (rev 63111)
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="securitycache">
+  <title>Security Cache</title>
+
+  <para>The Security Managers for authentication, authorization, mapping etc
+  can make use of security caches for performance purposes. The generic
+  SecurityCache interface is defined as follows:</para>
+
+  <programlisting>package org.jboss.security.cache;
+
+import java.util.Map; 
+
+/**
+ *  Generic Security Cache Interface for usage
+ *  by the security integration layers like authentication,
+ *  authorization etc. 
+ */
+public interface SecurityCache&lt;T&gt;
+{
+   /**
+    * Add a cache entry
+    * @param key
+    * @param contextMap a contextual map
+    * @throws SecurityCacheException
+    */
+   void addCacheEntry(T key, Map&lt;String,Object&gt; contextMap) throws SecurityCacheException;
+   
+   /**
+    * Cache Entry present?
+    * @param key Key for the cache entry
+    * @return true- cache entry exists, false-otherwise
+    */
+   boolean cacheHit(T key);
+   
+   /**
+    * Perform a cache operation
+    * @param key Key for the cache entry
+    * @param contextMap A contextual map
+    * @throws SecurityCacheException
+    */
+   void cacheOperation(T key, Map&lt;String,Object&gt; contextMap) throws SecurityCacheException; 
+   
+   /**
+    * Get Cache Entry
+    * @param &lt;Y&gt;
+    * @param T key
+    * @return Cache Entry
+    * @throws SecurityCacheException
+    */
+   &lt;Y&gt; Y get(T key) throws SecurityCacheException;
+}
+</programlisting>
+</chapter>
\ No newline at end of file

Added: projects/security/security-docs/trunk/docs/guide/en/modules/securityclient.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/securityclient.xml	                        (rev 0)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/securityclient.xml	2007-05-17 04:21:09 UTC (rev 63111)
@@ -0,0 +1,119 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="securityclient">
+  <title>Security Client</title>
+
+  <para>The Security Client class is a generic client that can do plain
+  username/password, JAAS or SASL forms of services.</para>
+
+  <programlisting>package org.jboss.security.client;
+ 
+import javax.security.auth.callback.CallbackHandler;
+import javax.security.auth.login.LoginException; 
+
+/**
+ *  Generic Security Client class &lt;br/&gt;
+ *  &lt;b&gt;Basic Users:&lt;/b&gt;&lt;br/&gt;
+ *  &lt;p&gt;Basic users will just use the methods that set the username and credential 
+ *  @see {@link #setUserName(String)} and @see {@link #setCredential(Object)} &lt;/p&gt;
+ *  &lt;b&gt;Intermediate Users:&lt;/b&gt;&lt;/br/&gt;
+ *  &lt;p&gt;You can specify usage of JAAS as the framework in the client implementation.
+ *  In this case, you will @see {@link #setLoginConfigName(String)} and
+ *  @see #setCallbackHandler(CallbackHandler)&lt;/p&gt;
+ *  &lt;b&gt;Advanced Users:&lt;/b&gt;
+ *  &lt;p&gt;You will use the @see {@link #setSASLMechanism(String)} method&lt;/p&gt; 
+ */
+public abstract class SecurityClient
+{   
+   protected Object userPrincipal = null; 
+   protected Object credential = null;
+   protected CallbackHandler callbackHandler = null;
+   protected String loginConfigName = null;
+   protected String saslMechanism = null;
+   protected String saslAuthorizationId = null;
+   
+   protected boolean jaasDesired = false;
+   protected boolean saslDesired = false;
+   
+   /**
+    * Login with the desired method
+    * @throws LoginException
+    */
+   public void login() throws LoginException
+   {
+      if(jaasDesired)
+         performJAASLogin();
+      else
+         if(saslDesired)
+            peformSASLLogin();
+         else
+            performSimpleLogin(); 
+   }
+   
+   /**
+    * Log Out
+    */
+   public void logout()
+   {
+      setSimple(null,null);
+      setJAAS(null,null);
+      setSASL(null,null,null);
+      cleanUp();
+   }
+   
+   /**
+    * Set the user name and credential for simple login (non-jaas, non-sasl)
+    * @param username (Can be null)
+    * @param credential (Can be null)
+    */
+   public void setSimple(Object username, Object credential)
+   {
+      this.userPrincipal = username;
+      this.credential = credential;
+   }
+   
+   /**
+    * Set the JAAS Login Configuration Name and Call back handler
+    * @param configName can be null
+    * @param cbh can be null
+    */
+   public void setJAAS(String configName, CallbackHandler cbh)
+   {
+      this.loginConfigName = configName;
+      this.callbackHandler = cbh;
+      clearUpDesires();
+      this.jaasDesired = true;
+   }
+   
+   /**
+    * Set the mechanism and other parameters for SASL Client
+    * @param mechanism
+    * @param authorizationId
+    * @param cbh
+    */
+   public void setSASL(String mechanism, String authorizationId,
+         CallbackHandler cbh)
+   {
+      this.saslMechanism = mechanism;
+      this.saslAuthorizationId = authorizationId;
+      this.callbackHandler = cbh;
+      clearUpDesires();
+      this.saslDesired = true;
+   }
+   
+   protected abstract void performJAASLogin() throws LoginException;
+   protected abstract void peformSASLLogin();
+   protected abstract void performSimpleLogin();
+   
+   /**
+    * Provide an opportunity for client implementations to clean up
+    */
+   protected abstract void cleanUp();
+   
+   private void clearUpDesires()
+   {
+      jaasDesired = false;
+      saslDesired = false;  
+   } 
+}
+</programlisting>
+</chapter>
\ No newline at end of file