Updating PetClinic build documentation regarding migration to Spring Build.

org.springframework.samples.petclinic/readme.txt

-=========================================
-== Spring PetClinic sample application ==
-=========================================
+==========================================================================
+=== Spring PetClinic Sample Application
+==========================================================================
 
 @author Ken Krebs
 @author Juergen Hoeller
@@ -9,95 +9,94 @@
 @author Sam Brannen
 @author Scott Andrews
 
---------------------------------------------------------------------------------
-
-
-1. DATA ACCESS STRATEGIES
+==========================================================================
+=== Data Access Strategies
+==========================================================================
 
 PetClinic features alternative DAO implementations and application
-configurations for JDBC, Hibernate and JPA, with HSQLDB and MySQL as target
-databases. The default PetClinic configuration is JDBC on HSQLDB. See
-"src/jdbc.properties", "war/WEB-INF/web.xml" and
-"war/WEB-INF/applicationContext-*.xml" for details. A simple comment change in
-"web.xml" switches between the data access strategies.
-
-The JDBC and Hibernate versions of PetClinic also demonstrate JMX support via
-the use of "<context:mbean-export/>" for exporting MBeans. SimpleJdbcClinic
-exposes the SimpleJdbcClinicMBean management interface via JMX through the use
-of the @ManagedResource and @ManagedOperation annotations; whereas, the
-HibernateStatistics service is exposed via JMX through auto-detection of the
-service MBean. You can start up the JDK's JConsole to manage the exported bean.
-
-The Spring distribution comes with all required Hibernate and TopLink Essentials
-(JPA RI) JAR files to be able to build and run PetClinic on those two ORM tools.
-
-All data access strategies can work with JTA for transaction management, by
-activating the JtaTransactionManager and a JndiObjectFactoryBean that refers to
-a transactional container DataSource. The default for JDBC is
-DataSourceTransactionManager; for Hibernate, HibernateTransactionManager; for
-JPA, JpaTransactionManager. Those local strategies allow for working with any
-locally defined DataSource.
-
-Note that in the default case, the sample configurations for Hibernate and JPA
-specify Spring's non-pooling DriverManagerDataSource as a local DataSource.
-You can change the DataSource definition to a Commons DBCP BasicDataSource to
-get proper connection pooling. See "war/WEB-INF/applicationContext-jdbc.xml" for
-an example.
-
---------------------------------------------------------------------------------
-
-
-2. BUILD AND DEPLOYMENT
-
-This directory contains the web app source. For deployment, it needs to be built
-with Apache Ant 1.6 or higher.
-
-Run "build.bat" in this directory for available targets (e.g. "build.bat build",
-"build.bat warfile"). You can use "warfile.bat" as a shortcut for WAR file
-creation. The WAR file will be created in the "dist" directory.
-
-You can also invoke an existing installation of Ant with this directory as the
-execution directory. Note that you must do this in order to execute the "tests"
-target, as you need the JUnit task from Ant's optional.jar, which is not
-included in this sample application.
-
-By default, an embedded HSQL instance in configured.  No other steps are 
-necessary to get the data source up and running.
-
-For MySQL, you'll need to use the corresponding schema and SQL scripts in the
-"db/mysql" subdirectory. Follow the steps outlined in
+configurations for JDBC, Hibernate, and JPA, with HSQLDB and MySQL as
+target databases. The default PetClinic configuration is JDBC on HSQLDB.
+See "src/main/resources/jdbc.properties" as well as web.xml and
+applicationContext-*.xml in the "src/main/webapp/WEB-INF" folder for
+details. A simple comment change in web.xml switches between the data
+access strategies.
+
+The JDBC and Hibernate versions of PetClinic also demonstrate JMX support
+via the use of <context:mbean-export/> for exporting MBeans.
+SimpleJdbcClinic exposes the SimpleJdbcClinicMBean management interface
+via JMX through the use of the @ManagedResource and @ManagedOperation
+annotations; whereas, the HibernateStatistics service is exposed via JMX
+through auto-detection of the service MBean. You can start up the JDK's
+JConsole to manage the exported bean.
+
+All data access strategies can work with JTA for transaction management by
+activating the JtaTransactionManager and a JndiObjectFactoryBean that
+refers to a transactional container DataSource. The default for JDBC is
+DataSourceTransactionManager; for Hibernate, HibernateTransactionManager;
+for JPA, JpaTransactionManager. Those local strategies allow for working
+with any locally defined DataSource.
+
+Note that the sample configurations for JDBC, Hibernate, and JPA configure
+a BasicDataSource from the Apache Commons DBCP project for connection
+pooling.
+
+==========================================================================
+=== Build and Deployment
+==========================================================================
+
+The Spring PetClinic sample application is built using Spring Build, which
+is a custom build solution based on Ant and Ivy for dependency management.
+For deployment, the web application needs to be built with Apache Ant 1.6
+or higher. When the project is first built, Spring Build will use Ivy to
+automatically download all required dependencies. Thus the initial build
+may take a few minutes depending on the speed of your Internet connection,
+but subsequent builds will be much faster.
+
+Available build commands:
+
+- ant clean        --> cleans the project
+- ant clean test   --> cleans the project and runs all tests
+- ant clean jar    --> cleans the project and builds the WAR
+
+After building the project with "ant clean jar", you will find the
+resulting WAR file in the "target" directory. By default, an embedded
+HSQLDB instance in configured. No other steps are necessary to get the
+data source up and running: you can simply deploy the built WAR file
+directly to your Servlet container.
+
+For MySQL, you'll need to use the corresponding schema and SQL scripts in
+the "db/mysql" subdirectory. Follow the steps outlined in
 "db/mysql/petclinic_db_setup_mysql.txt" for explicit details.
 
-In you intend to use a local DataSource, the JDBC settings can be adapted in
-"src/jdbc.properties". To use a JTA DataSource, you need to set up corresponding
-DataSources in your Java EE container.
+In you intend to use a local DataSource, the JDBC settings can be adapted
+in "src/main/resources/jdbc.properties". To use a JTA DataSource, you need
+to set up corresponding DataSources in your Java EE container.
 
 Notes on enabling Log4J:
- - Log4J is disabled by default, due to JBoss issues
- - Uncomment the Log4J listener in "WEB-INF/web.xml"
-
---------------------------------------------------------------------------------
-
+ - Log4J is disabled by default due to issues with JBoss.
+ - Uncomment the Log4J listener in "WEB-INF/web.xml" to enable logging.
 
-3. JPA ON TOMCAT
+==========================================================================
+=== JPA on Tomcat
+==========================================================================
 
-Notes on using the Java Persistence API (JPA) on Apache Tomcat 4.x or higher,
-with a persistence provider that requires class instrumentation (such as TopLink
-Essentials):
+This section provides tips on using the Java Persistence API (JPA) on
+Apache Tomcat 4.x or higher with a persistence provider that requires
+class instrumentation (such as TopLink Essentials).
 
-To use JPA class instrumentation, Tomcat has to be instructed to use a custom
-class loader which supports instrumentation. See the JPA section of the Spring
-reference manual for complete details.
+To use JPA class instrumentation, Tomcat has to be instructed to use a
+custom class loader which supports instrumentation. See the JPA section of
+the Spring reference manual for complete details.
 
 The basic steps are:
- - Copy "spring-tomcat-weaver.jar" from the Spring distribution to
-   "TOMCAT_HOME/server/lib".
+ - Copy "org.springframework.instrument.tomcat-3.0.0.RELEASE.jar" from the
+   Spring distribution to "TOMCAT_HOME/server/lib".
  - If you're running on Tomcat 5.x, modify "TOMCAT_HOME/conf/server.xml"
    and add a new "<Context>" element for 'petclinic' (see below). You can 
    alternatively deploy the WAR including "META-INF/context.xml" from this 
-   sample application's "war" directory, in which case you will need to
-   uncomment the Loader element in that file to enable the use of the
-   TomcatInstrumentableClassLoader.
+   sample application's "src/main/webapp" directory, in which case you
+   will need to uncomment the Loader element in that file to enable the
+   use of the TomcatInstrumentableClassLoader.
 
 <Context path="/petclinic" docBase="/petclinic/location" ...>
   <!-- please note that useSystemClassLoaderAsParent is available since Tomcat 5.5.20; remove it if previous versions are being used -->