From 0b069ebe460a68f539ab22cc6f724e169cb1c26e Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sun, 11 Oct 2009 15:53:51 +0000 Subject: [PATCH] Updating PetClinic build documentation regarding migration to Spring Build. --- .../readme.txt | 155 +++++++++--------- 1 file changed, 77 insertions(+), 78 deletions(-) diff --git a/org.springframework.samples.petclinic/readme.txt b/org.springframework.samples.petclinic/readme.txt index 8ccb9d6660..6dcb667d94 100644 --- a/org.springframework.samples.petclinic/readme.txt +++ b/org.springframework.samples.petclinic/readme.txt @@ -1,6 +1,6 @@ -========================================= -== 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 "" 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 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 "" 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.