[seam-commits] Seam SVN: r8562 - trunk/doc/Seam_Reference_Guide/en-US.

[seam-commits at lists.jboss.org]

Author: shane.bryzak at jboss.com
Date: 2008-08-03 21:22:44 -0400 (Sun, 03 Aug 2008)
New Revision: 8562

Modified:
   trunk/doc/Seam_Reference_Guide/en-US/Security.xml
Log:
documented typesafe role checks

Modified: trunk/doc/Seam_Reference_Guide/en-US/Security.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Security.xml	2008-08-04 01:12:40 UTC (rev 8561)
+++ trunk/doc/Seam_Reference_Guide/en-US/Security.xml	2008-08-04 01:22:44 UTC (rev 8562)
@@ -2966,7 +2966,7 @@
     </sect2>
     
     <sect2>
-      <title>Typesafe Security Annotations</title>
+      <title>Typesafe Permission Annotations</title>
       
       <para>
         Seam provides a number of annotations that may be used as an alternative to <literal>@Restrict</literal>, which have
@@ -3041,7 +3041,34 @@
       
       <programlisting><![CDATA[@PermissionCheck("upgrade")]]></programlisting>
       
+    </sect2>
+    
+    <sect2>
+      <title>Typesafe Role Annotations</title>    
       
+      <para>
+        In addition to supporting typesafe permission annotation, Seam Security also provides typesafe role annotations that
+        allow you to restrict access to component methods based on the role memberships of the currently authenticated user.
+        Seam provides one such annotation out of the box, <literal>org.jboss.seam.annotations.security.Admin</literal>, used
+        to restrict access to a method to users that are a member of the <literal>admin</literal> role (so long as your 
+        own application supports such a role).  To create your own role annotations, simply meta-annotate them with
+        <literal>org.jboss.seam.annotations.security.RoleCheck</literal>, like in the following example:
+      </para>
+      
+      <programlisting><![CDATA[@Target({METHOD})
+ at Documented
+ at Retention(RUNTIME)
+ at Inherited
+ at RoleCheck
+public @interface User { 
+}]]></programlisting>
+
+      <para>
+        Any methods subsequently annotated with the <literal>@User</literal> annotation as shown in the above example
+        will be automatically intercepted and the user checked for the membership of the corresponding role name
+        (which is the lower case version of the annotation name, in this case <literal>user</literal>).
+      </para>
+      
     </sect2>
     
     <sect2>
@@ -4379,8 +4406,9 @@
       <title>Permission checks for PermissionManager operations</title>
       
       <para>
-        Invoking the methods of <literal>PermissionManager</literal> requires that currently authenticated user
-        has the appropriate authorization to perform the operation.
+        Invoking the methods of <literal>PermissionManager</literal> requires that the currently-authenticated user
+        has the appropriate authorization to perform that management operation.  The following table lists the required
+        permissions that the current user must have.
       </para>
       
       <table>
@@ -4665,7 +4693,8 @@
     <title>Security Events</title>
 
     <para>
-      The following table describes a number of events (see <xref linkend="events"/>) raised by Seam Security.
+      The following table describes a number of events (see <xref linkend="events"/>) raised by Seam Security
+      in response to certain security-related events.
     </para>
 
     <table>