Michael's updates to petclinic tutorial

src/site/apt/petclinic-tutorial.apt

@@ -19,62 +19,81 @@ Tutorial: Adding Security to Spring Petclinic
 
     You will also need to download:
 
-    * Spring 2.5.2 with dependencies ZIP file
+    * {{{http://www.springframework.org/download}Spring 2.5.2 with dependencies ZIP file}}
 
-    * Spring Security 2.0
+    * {{{http://www.springframework.org/download}Spring Security 2.0}}
 
 
     Unzip both files. After unzipping Spring Security, you'll need to unzip the
     spring-security-sample-tutorial-2.0.war file, because we need some files that are
     included within it. After unzipping the war file, you will see a folder called 
     spring-security-samples-tutorial-2.0.0.
-    
+
     In the code below, we'll refer to the respective unzipped
     locations as %spring% and %spring-sec-tutorial% (with the later variable 
     referring to the unzipped WAR, not the original ZIP). There is no need to setup 
     any environment variables to complete the tutorial.
 
 
-* Add required Spring Security files to Petclinic
+* 1st part: Run the Petclinic application without Spring Security
+	
+	In order to make sure that you work in a stable environment, we will first
+	set up the Petclinic application, without Spring Security.
 
+** Start Petclinic's database
 
-    We now need to put some extra files into Petclinic. 
-    The following example is based on Windows MS-DOS. It only involves file copy and folder creation. 
-    You can adapt it on any operating system.  
+    Start the Hypersonic server:
 
 +------------------------------------------------------
-mkdir %spring%\samples\petclinic\war\WEB-INF\lib
+cd %spring%\samples\petclinic\db\hsqldb
+server
++------------------------------------------------------
 
-copy %spring-sec-tutorial%\WEB-INF\applicationContext-security-ns.xml %spring%\samples\petclinic\war\WEB-INF
-copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-core-2.0.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib
-copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-core-tiger-2.0.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib
-copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-acl-2.0.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib
-copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-taglibs-2.0.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib
-copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\petclinic\war\WEB-INF\lib
+    Insert some data:
+
++------------------------------------------------------
+cd %spring%\samples\petclinic
+ant setupDB
 +------------------------------------------------------
 
+** Build and deploy the Petclinic WAR file
 
-* Configure Petclinic's files
 
-    Edit %spring%\samples\petclinic\war\WEB-INF\web.xml and insert the following block of code.
-    It should be inserted right after the </context-param> end-tag.
+    Use Petclinic's Ant build script and deploy to your servlet container:
 
++------------------------------------------------------
+cd %spring%\samples\petclinic
+build warfile
+copy dist\petclinic.war %TOMCAT_HOME%\webapps
 +------------------------------------------------------
 
-    <filter>
-        <filter-name>springSecurityFilterChain</filter-name>
-        <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
-    </filter>
+    Finally, start your container and try to visit the petclinic home page.
+    You are now able to browse the whole application without any authentication needed
 
-    <filter-mapping>
-      <filter-name>springSecurityFilterChain</filter-name>
-      <url-pattern>/*</url-pattern>
-    </filter-mapping>
 
+* Second part: set up Spring security
+
+** Add required Spring Security files to Petclinic
+
+
+    We now need to put some extra files into Petclinic. 
+    The following example is based on Windows MS-DOS. It only involves file copy. 
+    We believe you can adapt it easily on any operating system.  
+
++------------------------------------------------------
+copy %spring-sec-tutorial%\WEB-INF\applicationContext-security-ns.xml %spring%\samples\petclinic\war\WEB-INF
+copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-core-2.0.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib
+copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-core-tiger-2.0.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib
+copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-acl-2.0.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib
+copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-taglibs-2.0.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib
+copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\petclinic\war\WEB-INF\lib
 +------------------------------------------------------
 
-    Still inside web.xml, the "contextConfigLocation" specifies Spring configuration files that should be used
-    by the petclinic application. Locate the "contextConfigLocation" parameter, and add a new line into 
+
+** Configure Petclinic's files
+
+    Edit %spring%\samples\petclinic\war\WEB-INF\web.xml. The "contextConfigLocation" specifies Spring configuration files that should be used
+    by the petclinic application. Locate the "contextConfigLocation" parameter and add a new line into 
     the existing param-value. Now that we are using Spring Security, It should also declare 
     applicationContext-security-ns.xml (Spring config file for Spring Security).
     The resulting block will look like this:
@@ -91,19 +110,20 @@ copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\pe
 
 +------------------------------------------------------
 
-    To make it easier to experiment with the application, users should be able to log out of the application. 
-    Edit %spring%\samples\petclinic\war\WEB-INF\jsp\footer.jsp. Add a new "logout" link, as shown:
+    Still inside web.xml, insert the following block of code.
+    It should be inserted right after the </context-param> end-tag.
 
 +------------------------------------------------------
 
-<table class="footer">
-    <tr>
-      <td><a href="<c:url value="/welcome.do"/>">Home</a></td>
-      <td style="text-align:right;color:silver">PetClinic :: a Spring Framework demonstration</td>
-      <td align="right"><img src="<c:url value="/images/springsource-logo.png"/>"/></td>
-      <td align="right"><a href="<c:url value="/j_spring_security_logout"/>">Logout</a></td>
-    </tr>
-</table>
+    <filter>
+        <filter-name>springSecurityFilterChain</filter-name>
+        <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
+    </filter>
+
+    <filter-mapping>
+      <filter-name>springSecurityFilterChain</filter-name>
+      <url-pattern>/*</url-pattern>
+    </filter-mapping>
 
 +------------------------------------------------------
    Our last step is to specify which URLs require authorization and which do not. Let's
@@ -111,49 +131,41 @@ copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\pe
     All URLs ending with '.do' will be protected.
 
 +------------------------------------------------------
-
-
-
-<http auto-config="true">
-    <intercept-url pattern="/*.do" access="ROLE_USER" />
-    <intercept-url pattern="/**" access="IS_AUTHENTICATED_ANONYMOUSLY" />
-</http>
-
+	<http auto-config="true">
+		<intercept-url pattern="/*.do" access="ROLE_USER" />
+		<intercept-url pattern="/**" access="IS_AUTHENTICATED_ANONYMOUSLY" />
+	</http>
 +------------------------------------------------------
 
-	
-
+** Test
 
-* Start Petclinic's database
+    Redeploy your web application. Use the earlier process to do that. Be careful to
+    ensure that the old Petclinic WAR is replaced by the new Petclinic WAR in your
+    servlet container. 
 
-    Start the Hypersonic server (this is just normal Petclinic configuration):
+    Finally, start your container and try to visit the home page.
+    Your request should be intercepted and you will be forced to login.
+    You can now log in using  the usernames and passwords that are documented at the end
+    of applicationContext-security-ns.xml file. 
 
-+------------------------------------------------------
-cd %spring%\samples\petclinic\db\hsqldb
-server
-+------------------------------------------------------
+** Log out
 
-    Insert some data (again, normal Petclinic configuration):
+    To make it easier to experiment with the application, users should be able to log out of the application. 
+    Edit %spring%\samples\petclinic\war\WEB-INF\jsp\footer.jsp. Add a new "logout" link, as shown:
 
 +------------------------------------------------------
-cd %spring%\samples\petclinic
-ant setupDB
-+------------------------------------------------------
-
-* Build and deploy the Petclinic WAR file
 
+<table class="footer">
+    <tr>
+      <td><a href="<c:url value="/welcome.do"/>">Home</a></td>
+      <td style="text-align:right;color:silver">PetClinic :: a Spring Framework demonstration</td>
+      <td align="right"><img src="<c:url value="/images/springsource-logo.png"/>"/></td>
+      <td align="right"><a href="<c:url value="/j_spring_security_logout"/>">Logout</a></td>
+    </tr>
+</table>
 
-    Use Petclinic's Ant build script and deploy to your servlet container:
-
-+------------------------------------------------------
-cd %spring%\samples\petclinic
-build warfile
-copy dist\petclinic.war %TOMCAT_HOME%\webapps
 +------------------------------------------------------
 
-    Finally, start your container and try to visit the home page.
-    Your request should be intercepted and you will be forced to login.</p>
-
 
 
 * Optional Bonus: Securing the Middle Tier
@@ -162,6 +174,7 @@ copy dist\petclinic.war %TOMCAT_HOME%\webapps
     from being able to add clinic visits unless authorized. We'll make it so
     you need to hold ROLE_SUPERVISOR to add a clinic visit.
 
+** protect-pointcut
 
     Finally, we need to declare a protect-pointcut that will hold the security restriction. 
     Inside %spring%\samples\petclinic\war\WEB-INF\applicationContext-security-ns.xml, update
@@ -170,27 +183,35 @@ copy dist\petclinic.war %TOMCAT_HOME%\webapps
 +------------------------------------------------------
 
 	<global-method-security secured-annotations="enabled">
-		<protect-pointcut expression="execution(* org.springframework.samples.petclinic.Clinic.storeVisit(..))" access="ROLE_SUPERVISOR"/>
+		<protect-pointcut expression="execution(* org.springframework.samples.petclinic.Clinic.storeVisit(..))" 
+		access="ROLE_SUPERVISOR"/>
 	</global-method-security>
 
 +------------------------------------------------------
 
-    Redeploy your web application. Use the earlier process to do that. Be careful to
-    ensure that the old Petclinic WAR is replaced by the new Petclinic WAR in your
-    servlet container. 
+    Redeploy your web application.
     Login as "peter" that does not have the "ROLE_SUPERVISOR" role.
-    - Click on "Find owners"
-    - Keep the "last name" field blank and validate
-    - Select one owner in the list
-    - Click on "add visit"
-    - Add a description and validate
+
+    * Click on "Find owners"
+
+    * Keep the "last name" field blank and validate
+
+    * Select one owner in the list
+
+    * Click on "add visit"
+
+    * Add a description and validate
+
     Access should be denied.
-    
+
     Now log out and try  "rod", who has ROLE_SUPERVISOR. It should be working.
 
+** The "sec" tag-library
+
     To clean things up a bit, you might want to wrap up by hiding the "add visit" link
     unless you are authorized to use it. Spring Security provides a tag library to help
-    you do that. Edit %spring%\samples\petclinic\war\WEB-INF\jsp\owner.jsp. Add
+    you do that. Edit %spring%\samples\petclinic\war\WEB-INF\jsp\owner.jsp (please 
+    make sure that you are opening owner.jsp, not owners.jsp !!). Add
     the following line to the top of the file:
 
 +------------------------------------------------------