From bb7165ac6e516f8b59cdd4951d218a91ced0e4e5 Mon Sep 17 00:00:00 2001
From: Luke Taylor <luke.taylor@springsource.com>
Date: Sat, 7 Aug 2010 15:43:55 +0100
Subject: [PATCH] SEC-1530: Added information on calling getAllPrincipals() on
 SessionRegistry for direct use in an application to provide currently logged
 in users.

---
 docs/manual/src/docbook/session-mgmt.xml | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/manual/src/docbook/session-mgmt.xml b/docs/manual/src/docbook/session-mgmt.xml
index 64a9264127..a00ca41df6 100644
--- a/docs/manual/src/docbook/session-mgmt.xml
+++ b/docs/manual/src/docbook/session-mgmt.xml
@@ -144,5 +144,28 @@
             <classname>SessionRegistryImpl</classname> to be notified when a session ends. Without
             it, a user will never be able to log back in again once they have exceeded their session
             allowance, even if they log out of another session or it times out.</para>
+        <section xml:id="list-authenticated-principals">
+            <title>Querying the <interfacename>SessionRegistry</interfacename> for currently authenticated
+            users and their sessions</title>
+            <para>
+                Setting up concurrency-control, either through the namespace or using plain beans has the
+                useful side effect of providing you with a reference to the <interfacename>SessionRegistry</interfacename>
+                which you can use directly within your application, so even if you don't want to restrict the
+                number of sessions a user may have, it may be worth setting up the infrastructure anyway. You can
+                set the <literal>maximumSession</literal> property to -1 to allow unlimited sessions. If
+                 you're using the namespace, you can set an alias for the internally-created 
+                <interfacename>SessionRegistry</interfacename> using the <literal>session-registry-alias</literal>
+                attribute, providing a reference which you can inject into your own beans.</para>
+            <para>
+                The <methodname>getAllPrincipals()</methodname>
+                method supplies you with a list of the currently authenticated users. You can list a user's
+                sessions by calling the <methodname>getAllSessions(Object principal, boolean includeExpiredSessions)</methodname> method,
+                which returns a list of <classname>SessionInformation</classname> objects. You can also
+                expire a user's session by calling <methodname>expireNow()</methodname> on a
+                <methodname>SessionInformation</methodname> instance. When the user returns to the application, they
+                will be prevented from proceeding. You may find these methods useful in an administration
+                application, for example. Have a look at the Javadoc for more information.
+            </para>
+        </section>
     </section>
 </chapter>