From seam-commits at lists.jboss.org Wed Jun 25 20:48:05 2008
Content-Type: multipart/mixed; boundary="===============2113816797090009339=="
MIME-Version: 1.0
From: seam-commits at lists.jboss.org
To: seam-commits at lists.jboss.org
Subject: [seam-commits] Seam SVN: r8419 - trunk/doc/Seam_Reference_Guide/en-US.
Date: Wed, 25 Jun 2008 20:48:02 -0400
Message-ID: <E1KBfec-0002ey-Nv@committer01.frg.pub.inap.atl.jboss.com>

--===============2113816797090009339==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: shane.bryzak(a)jboss.com
Date: 2008-06-25 20:48:02 -0400 (Wed, 25 Jun 2008)
New Revision: 8419

Modified:
   trunk/doc/Seam_Reference_Guide/en-US/Security.xml
Log:
more proofreading, documented typesafe security annotations

Modified: trunk/doc/Seam_Reference_Guide/en-US/Security.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/doc/Seam_Reference_Guide/en-US/Security.xml	2008-06-25 19:47:15 U=
TC (rev 8418)
+++ trunk/doc/Seam_Reference_Guide/en-US/Security.xml	2008-06-26 00:48:02 U=
TC (rev 8419)
@@ -2339,7 +2339,7 @@
     <title>Authorization</title>
 =

     <para>
-      There are a number of authorization features provided by the Seam Se=
curity API for securing access to
+      There are a number of authorization mechanisms provided by the Seam =
Security API for securing access to
       components, component methods, and pages.  This section describes ea=
ch of these.  An important thing to
       note is that if you wish to use any of the advanced features (such a=
s rule-based permissions) then
       your <literal>components.xml</literal> may need to be configured to =
support this - see the Configuration section
@@ -2400,8 +2400,8 @@
         </mediaobject>        =

       =

         <para>
-          Within this documentation, permissions are represented in the fo=
rm <literal>name:action</literal> (generally
-          omitting the recipient, although in reality one is always requir=
ed).
+          Within this documentation, permissions are generally represented=
 in the form <literal>target:action</literal> =

+          (omitting the recipient, although in reality one is always requi=
red).
         </para>  =

       </sect3>
 =

@@ -2453,7 +2453,7 @@
         <para>
           In this example, the implied permission required to call the <li=
teral>delete()</literal> method is
           <literal>account:delete</literal>.  The equivalent of this would=
 be to write
-          <literal>@Restrict("#{s:hasPermission('account','delete',null)}"=
)</literal>.  Now let's look at
+          <literal>@Restrict("#{s:hasPermission('account','delete')}")</li=
teral>.  Now let's look at
           another example:
         </para>
 =

@@ -2492,7 +2492,7 @@
         <programlisting role=3D"JAVA"><![CDATA[@Name("account")
 public class AccountAction {
     @In Account selectedAccount;
-    @Restrict("#{s:hasPermission('account','modify',selectedAccount)}")
+    @Restrict("#{s:hasPermission(selectedAccount,'modify')}")
     public void modify() {
         selectedAccount.modify();
     }
@@ -2516,7 +2516,7 @@
         </para>
 =

         <programlisting role=3D"JAVA"><![CDATA[public void deleteCustomer(=
) {
-    Identity.instance().checkRestriction("#{s:hasPermission('customer','de=
lete',selectedCustomer)}");
+    Identity.instance().checkRestriction("#{s:hasPermission(selectedCustom=
er,'delete')}");
 }]]></programlisting>
 =

         <para>
@@ -2546,7 +2546,7 @@
         <programlisting role=3D"JAVA"><![CDATA[if (!Identity.instance().ha=
sRole("admin"))
      throw new AuthorizationException("Must be admin to perform this actio=
n");
 =

-if (!Identity.instance().hasPermission("customer", "create", null))
+if (!Identity.instance().hasPermission("customer", "create"))
      throw new AuthorizationException("You may not create new customers");=
]]></programlisting>
 =

       </sect3>
@@ -2607,9 +2607,9 @@
     <h:column>
         <f:facet name=3D"header">Action</f:facet>
         <s:link value=3D"Modify Client" action=3D"#{clientAction.modify}"
-                rendered=3D"#{s:hasPermission('client','modify',cl)"/>
+                rendered=3D"#{s:hasPermission(cl,'modify')"/>
         <s:link value=3D"Delete Client" action=3D"#{clientAction.delete}"
-                rendered=3D"#{s:hasPermission('client','delete',cl)"/>
+                rendered=3D"#{s:hasPermission(cl,'delete')"/>
     </h:column>
 </h:dataTable>]]></programlisting>
 =

@@ -2755,9 +2755,9 @@
   no-loop
   activation-group "permissions"
 when
-  check: PermissionCheck(name =3D=3D "memberBlog", action =3D=3D "insert",=
 granted =3D=3D false)
-  Principal(principalName : name)
-  MemberBlog(member : member -> (member.getUsername().equals(principalName=
)))
+  principal: Principal()
+  memberBlog: MemberBlog(member : member -> (member.getUsername().equals(p=
rincipal.getName())))
+  check: PermissionCheck(target =3D=3D memberBlog, action =3D=3D "insert",=
 granted =3D=3D false)
 then
   check.grant();
 end;]]></programlisting>
@@ -2765,11 +2765,11 @@
        <para>
          This rule will grant the permission <literal>memberBlog:insert</l=
iteral> if the currently authenticated
          user (indicated by the <literal>Principal</literal> fact) has the=
 same name as the member for which the
-         blog entry is being created.  The "<literal>principalName : name<=
/literal>" structure that can be seen in the
-         <literal>Principal</literal> fact (and other places) is a variabl=
e binding - it binds the <literal>name</literal>
-         property of the <literal>Principal</literal> to a variable called=
 <literal>principalName</literal>.  Variable bindings
-         allow the value to be referred to in other places, such as the fo=
llowing line which compares the member's username
-         to the <literal>Principal</literal> name.  For more details, plea=
se refer to the JBoss Rules documentation.
+         blog entry is being created.  The "<literal>principal: Principal(=
)</literal>" structure that can be seen in the
+         example code is a variable binding - it binds the instance of the=
 <literal>Principal</literal> object from the
+         working memory (placed there during authentication) and assigns i=
t to a variable called <literal>principal</literal>.
+         Variable bindings allow the value to be referred to in other plac=
es, such as the following line which compares the =

+         member's username to the <literal>Principal</literal> name.  For =
more details, please refer to the JBoss Rules documentation.
        </para>
 =

        <para>
@@ -2825,8 +2825,74 @@
         that <literal>@Restrict</literal> does.
       </para>
       =

+      <para>
+        Out of the box, Seam comes with annotations for standard CRUD-base=
d permissions, however it is a simple matter to =

+        add your own.  The following annotations are provided in the <lite=
ral>org.jboss.seam.annotations.security</literal> package:
+      </para>
       =

-    =

+      <itemizedlist>
+        <listitem>
+          <para>@Insert</para>
+        </listitem>
+        <listitem>
+          <para>@Read</para>
+        </listitem>
+        <listitem>
+          <para>@Update</para>
+        </listitem>
+        <listitem>
+          <para>@Delete</para>
+        </listitem>
+      </itemizedlist>
+      =

+      <para>
+        To use these annotations, simply place them on the method or param=
eter for which you wish to perform a security check.
+        If placed on a method, then they should specify a target class for=
 which the permission will be checked.  Take the
+        following example:
+      </para>
+      =

+      <programlisting><![CDATA[  @Insert(Customer.class)
+  public void createCustomer() {
+    ...
+  }]]></programlisting>
+  =

+      <para>
+        In this example, a permission check will be performed for the user=
 to ensure that they have the rights to create
+        new <literal>Customer</literal> objects.  The target of the permis=
sion check will be <literal>Customer.class</literal>
+        (the actual <literal>java.lang.Class</literal> instance itself), a=
nd the action is the lower case representation of the =

+        annotation name, which in this example is <literal>insert</literal=
>.
+      </para>
+      =

+      <para>
+        It is also possible to annotate the parameters of a component meth=
od in the same way.  If this is done, then it is
+        not required to specify a permission target (as the parameter valu=
e itself will be the target of the permission check):
+      </para>
+      =

+      <programlisting><![CDATA[  public void updateCustomer(@Update Custom=
er customer) {
+    ...
+  }]]></programlisting>
+  =

+      <para>
+        To create your own security annotation, you simply need to annotat=
e it with <literal>@PermissionCheck</literal>, for example:
+      </para>
+      =

+      <programlisting><![CDATA[@Target({METHOD, PARAMETER})
+(a)Documented
+(a)Retention(RUNTIME)
+(a)Inherited
+(a)PermissionCheck
+public @interface Promote {
+   Class value() default void.class;
+}]]></programlisting>
+
+      <para>
+        If you wish to override the default permisison action name (which =
is the lower case version of the annotation name) with
+        another value, you can specify it within the <literal>@PermissionC=
heck</literal> annotation:
+      </para>
+      =

+      <programlisting><![CDATA[@PermissionCheck("upgrade")]]></programlist=
ing>
+      =

+      =

     </sect2>
 =

     <sect2>


--===============2113816797090009339==--