Michael's updates to petclinic tutorial

src/site/apt/petclinic-tutorial.apt

@@ -19,32 +19,68 @@ 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
+
+    Start the Hypersonic server:
+
++------------------------------------------------------
+cd %spring%\samples\petclinic\db\hsqldb
+server
++------------------------------------------------------
+
+    Insert some data:
+
++------------------------------------------------------
+cd %spring%\samples\petclinic
+ant setupDB
++------------------------------------------------------
+
+** Build and deploy the Petclinic WAR file
+
+
+    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 petclinic home page.
+    You are now able to browse the whole application without any authentication needed
+
+
+* 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 and folder creation. 
+    The following example is based on Windows MS-DOS. It only involves file copy. 
-    You can adapt it on any operating system.  
+    We believe you can adapt it easily on any operating system.  
 
 +------------------------------------------------------
-mkdir %spring%\samples\petclinic\war\WEB-INF\lib
-
 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
@@ -54,27 +90,10 @@ copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\pe
 +------------------------------------------------------
 
 
-* Configure Petclinic's files
+** Configure Petclinic's files
 
-    Edit %spring%\samples\petclinic\war\WEB-INF\web.xml and insert the following block of code.
+    Edit %spring%\samples\petclinic\war\WEB-INF\web.xml. The "contextConfigLocation" specifies Spring configuration files that should be used
-    It should be inserted right after the </context-param> end-tag.
+    by the petclinic application. Locate the "contextConfigLocation" parameter and add a new line into 
-
-+------------------------------------------------------
-
-    <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>
-
-+------------------------------------------------------
-
-    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 
     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,6 +110,46 @@ copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\pe
 
 +------------------------------------------------------
 
+    Still inside web.xml, insert the following block of code.
+    It should be inserted right after the </context-param> end-tag.
+
++------------------------------------------------------
+
+    <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
+    edit %spring%\samples\petclinic\war\WEB-INF\applicationContext-security-ns.xml.
+    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>
++------------------------------------------------------
+
+** Test
+
+    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. 
+
+    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. 
+
+** Log out
+
     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:
 
@@ -106,53 +165,6 @@ copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\pe
 </table>
 
 +------------------------------------------------------
-   Our last step is to specify which URLs require authorization and which do not. Let's
-    edit %spring%\samples\petclinic\war\WEB-INF\applicationContext-security-ns.xml.
-    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>
-
-+------------------------------------------------------
-
-	
-
-
-* Start Petclinic's database
-
-    Start the Hypersonic server (this is just normal Petclinic configuration):
-
-+------------------------------------------------------
-cd %spring%\samples\petclinic\db\hsqldb
-server
-+------------------------------------------------------
-
-    Insert some data (again, normal Petclinic configuration):
-
-+------------------------------------------------------
-cd %spring%\samples\petclinic
-ant setupDB
-+------------------------------------------------------
-
-* Build and deploy the Petclinic WAR file
-
-
-    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>
 
 
 
@@ -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
+    Redeploy your web application.
-    ensure that the old Petclinic WAR is replaced by the new Petclinic WAR in your
-    servlet container. 
     Login as "peter" that does not have the "ROLE_SUPERVISOR" role.
-    - Click on "Find owners"
+
-    - Keep the "last name" field blank and validate
+    * Click on "Find owners"
-    - Select one owner in the list
+
-    - Click on "add visit"
+    * Keep the "last name" field blank and validate
-    - Add a description 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:
 
 +------------------------------------------------------