DevFW-CICD/spring-petclinic
12
0
Fork 1
mirror of https://github.com/spring-projects/spring-petclinic.git synced 2025-04-24 19:32:48 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
spring-petclinic/src/main/webapp/html/tutorial.html
Costin Leau 521d01db95 SPR-6447 
SPR-6448
+ commit the gross of the files
+ added maven pom
2013-01-09 17:13:17 +08:00

1153 lines
No EOL
59 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Spring PetClinic Application</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<link rel="stylesheet" href="../styles/petclinic.css" type="text/css">
</head>
<body>
<div id="main">
<h1>The Spring PetClinic Application</h1>
<!--
<table class="updated">
<tr><td>Updated:</td><td>25.NOV.2009</td><td>Costin Leau(<strong>Work In Progress: not yet fully updated regarding Spring 3.0</strong>)</td></tr>
<tr><td></td><td>11.OCT.2009</td><td>Sam Brannen</td></tr>
<tr><td></td><td>21.OCT.2007</td><td>Sam Brannen</td></tr>
<tr><td></td><td>30.JUN.2006</td><td>Costin Leau</td></tr>
<tr><td></td><td>01.DEC.2004</td><td>Ken Krebs</td></tr>
<tr><td></td><td>16.AUG.2003</td><td>Ken Krebs</td></tr>
</table>
-->
<!-- === INTRODUCTION ====================================================== -->
<h2>Introduction</h2>
<p>
The Spring Framework is a collection of small, well-focused, loosely coupled Java
frameworks that can be used independently or collectively to build
industrial strength applications of many different types. The PetClinic
sample application is designed to show how the Spring
application frameworks can be used to build simple, but powerful
database-oriented applications. It will demonstrate the use
of Spring's core functionality:
</p>
<ul>
<li>JavaBeans based application configuration using Inversion-Of-Control</li>
<li>Model-View-Controller web Presentation Layer</li>
<li>Practical database access through JDBC, Hibernate, or Java Persistence API</li>
<li>Application monitoring based on JMX</li>
<li>Declarative Transaction Management using AOP</li>
<li>Data Validation that supports but is not dependent on the Presentation Layer</li>
</ul>
<p>
The Spring frameworks provide a great deal of useful infrastructure to
simplify the tasks faced by application developers. This infrastructure
helps developers to create applications that are:
</p>
<ul>
<li>
<span style="font-weight: bold; text-decoration: underline;">concise</span>
by handling a lot of the complex control flow that is needed to use the
Java API's, such as JDBC, JNDI, JTA, RMI, and EJB.
</li>
<li>
<span style="font-weight: bold; text-decoration: underline;">flexible</span>
by simplifying the process of external application configuration
through the use of Reflection and JavaBeans. This allows the developer to
achieve a clean separation of configuration data from application code.
All application and web application objects, including validators,
workflow controllers, and views, are JavaBeans that can be configured
externally.</li>
<li>
<span style="font-weight: bold; text-decoration: underline;">testable</span>
by supplying an interface based design to maximize pluggability. This
facilitates unit testing of Business Logic without requiring the
presence of application or live database servers.</li>
<li>
<span style="font-weight: bold; text-decoration: underline;">maintainable</span>
by facilitating a clean separation of the application layers. It most
importantly helps maintain the independence of the Business Layer
from the Presentation layer. PetClinic demonstrates the use of a
Model-View-Controller
based web presentation framework that can work seamlessly with many
different types of view technologies. The Spring web application
framework helps developers to implement their Presentation as a clean
and thin layer focused on its main missions of translating user actions
into application events and rendering model data.</li>
</ul>
<p>
It is assumed that users of this tutorial will have a basic knowledge
of object-oriented design, Java, Servlets, JSP, and relational
databases. It also assumes a basic knowledge of the use of a Java EE web
application container.
</p>
<p>
Since the purpose of the sample application is tutorial in nature, the
implementation presented here will of course provide only a small
subset of the functionality that would be needed by a real world version of a
PetClinic application.
</p>
<!-- === REQUIREMENTS ====================================================== -->
<h2>PetClinic Sample Application Requirements</h2>
<p>
The application requirement is for an information system that is
accessible through a web browser. The users of the application are
employees of the clinic who in the course of their work need to view
and manage information regarding the veterinarians, the clients, and their
pets. The sample application supports the following:
</p>
<h3>Use Cases</h3>
<ul>
<li>View a list of veterinarians and their specialties</li>
<li>View information pertaining to a pet owner</li>
<li>Update the information pertaining to a pet owner</li>
<li>Add a new pet owner to the system</li>
<li>View information pertaining to a pet</li>
<li>Update the information pertaining to a pet</li>
<li>Add a new pet to the system</li>
<li>View information pertaining to a pet's visitation history</li>
<li>Add information pertaining to a visit to the pet's visitation history</li>
</ul>
<h3>Business Rules</h3>
<ol>
<li>An owner may not have multiple pets with the same case-insensitive name.</li>
</ol>
<!-- === DESIGN AND IMPLEMENTATION ========================================= -->
<h2>PetClinic Sample Application Design &amp; Implementation</h2>
<h3>Server Technology</h3>
<p>
The sample application should be usable with any Java EE web application
container that is compatible with the Servlet 2.4 and JSP 2.0
specifications. Some of the deployment files provided are designed
specifically for Apache Tomcat. These files specify container-supplied
connection-pooled data sources. It is not necessary to use these files.
The application has been configured by default to use a data source
with connection pooling. Configuration details are
provided in the Developer Instructions section. The view technologies
that are to be used for rendering the application are Java Server Pages
(JSP) along with the Java Standard Tag Library (JSTL).
</p>
<h3>Database Technology</h3>
<p>
The sample application uses a relational database for data storage.
Support has been provided for a choice of 1 of 2 database selections,
MySql or HypersonicSQL. HypersonicSQL version 1.8.0 is the default
choice. It is possible to
easily configure the application to use either database. Configuration
details are provided in the Developer Instructions section.
</p>
<h3>Development Environment</h3>
<p>
A copy of the Spring runtime library jar file is provided with the
sample application along with some of the other required jar files. The
developer will need to obtain the following tools externally, all of
which are freely available:
</p>
<ul>
<li>Java SDK 1.5.x</li>
<li>Maven 2.0.10+</li>
<li>Ant 1.7.1 (for executing scripts, if needed, against the in-memory database)</li>
<li>Tomcat 6.x.x, or some other Java Servlet container</li>
<li>(Optional) MySQL 5.x with MySQL Connector/J 5.x</li>
</ul>
<p>
<strong>NOTE:</strong> The version numbers listed are those that were used
in the development of the PetClinic application. Other versions of the same
tools may or may not work.
</p>
<p>
Download links for the various tools needed are provided in the Developer
Instructions section.
</p>
<h3>PetClinic Database</h3>
<p>
The following is an overview of the database schema used in PetClinic.
Detailed field descriptions can be found in the
<span style="font-weight: bold; font-style: italic;">"initDB.txt"</span>
SQL script files in the database-specific "db" sub-directories. All "id" key
fields are of Java type <span style="font-weight: bold; font-style: italic;">int</span>.
</p>
<p>
TABLE: <span style="font-weight: bold; font-style: italic;">owners</span><br>
&nbsp;&nbsp;&nbsp; PRIMARY KEY <span style="font-weight: bold;">id</span>
</p>
<p>
TABLE: <span style="font-weight: bold; font-style: italic;">types</span><br>
&nbsp;&nbsp;&nbsp; PRIMARY KEY <span style="font-weight: bold;">id</span>
</p>
<p>
TABLE: <span style="font-weight: bold; font-style: italic;">pets</span><br>
&nbsp;&nbsp;&nbsp; PRIMARY KEY <span style="font-weight: bold;">id</span><br>
&nbsp;&nbsp;&nbsp; FOREIGN KEY <span style="font-weight: bold;">type_id</span>
references the <span style="font-weight: bold; font-style: italic;">types</span>
table<span style="font-weight: bold;"> id</span> field<br>
&nbsp;&nbsp;&nbsp; FOREIGN KEY <span style="font-weight: bold;">owner_id</span>
references the <span style="font-weight: bold; font-style: italic;">owners</span>
table <span style="font-weight: bold;">id</span> field
</p>
<p>
TABLE: <span style="font-weight: bold; font-style: italic;">vets</span><br>
&nbsp;&nbsp;&nbsp; PRIMARY KEY <span style="font-weight: bold;">id</span>
</p>
<p>
TABLE: <span style="font-weight: bold; font-style: italic;">specialties</span><br>
&nbsp;&nbsp;&nbsp; PRIMARY KEY <span style="font-weight: bold;">id</span><br>
</p>
<p>
TABLE: <span style="font-weight: bold; font-style: italic;">vet_specialties</span> -
a link table for <span style="font-weight: bold; font-style: italic;">vets</span>
and their <span style="font-weight: bold; font-style: italic;">specialties</span><br>
&nbsp;&nbsp;&nbsp; FOREIGN KEY <span style="font-weight: bold;">vet_id</span>
references the <span style="font-weight: bold; font-style: italic;">vets</span>
table<span style="font-weight: bold;"> id</span> field<br>
&nbsp;&nbsp;&nbsp; FOREIGN KEY <span style="font-weight: bold;">specialty_id</span>
references the <span style="font-weight: bold; font-style: italic;">specialties</span>
table <span style="font-weight: bold;">id</span> field
</p>
<p>
TABLE: <span style="font-weight: bold; font-style: italic;">visits</span><br>
&nbsp;&nbsp;&nbsp; PRIMARY KEY <span style="font-weight: bold;">id</span><br>
&nbsp;&nbsp;&nbsp; FOREIGN KEY <span style="font-weight: bold;">pet_id</span>
references the <span style="font-weight: bold; font-style: italic;">pets</span>
table <span style="font-weight: bold;">id</span> field
</p>
<h3>Directory Structure</h3>
<p>
d-- indicates a directory holding source code, configuration files, etc.<br>
D-- indicates a directory that is created by the build script
</p>
<p>
d-- <span style="font-weight: bold; font-style: italic;">petclinic</span>:
the root directory of the project contains build related files<br>
&nbsp;&nbsp;&nbsp; d-- <span style="font-weight: bold; font-style: italic;">src</span>: contains
Java source code files and ORM configuration files<br>
&nbsp;&nbsp;&nbsp; d-- <span style="font-weight: bold; font-style: italic;">war</span>: contains
the web application resource files<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; d-- <span style="font-weight: bold; font-style: italic;">html</span>: contains
tutorial files<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; D-- <span style="font-weight: bold; font-style: italic;">docs</span>: contains
Javadoc files<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; d-- <span style="font-weight: bold; font-style: italic;">web-inf</span>:
contains web application configuration files and application context
files<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
d-- <span style="font-weight: bold; font-style: italic;">jsp</span>:
contains Java Server Page files<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
D--<span style="font-weight: bold;"> <span style="font-style: italic;">lib</span></span>:
contains application dependencies<br>
&nbsp;&nbsp;&nbsp; d-- <span style="font-weight: bold; font-style: italic;">test</span>: contains
testing related
Java source code files<br>
&nbsp;&nbsp;&nbsp; d-- <span style="font-weight: bold; font-style: italic;">db</span>: contains
database SQL scripts and other related files/directories<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; d-- <span style="font-weight: bold; font-style: italic;">hsqldb</span>:
contains files related to HSQL, contains scripts and a&nbsp;Tomcat
context definition file<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; d-- <span style="font-weight: bold; font-style: italic;">mysql</span>:
contains files related to MySQL, contains scripts and a Tomcat context
definition file<br>
&nbsp;&nbsp;&nbsp; D-- <span style="font-weight: bold; font-style: italic;">.classes</span>:
contains compiled Java class files<br>
&nbsp;&nbsp;&nbsp; D-- <span style="font-weight: bold; font-style: italic;">.testclasses</span>:
contains compiled testing related Java class files<br>
&nbsp;&nbsp;&nbsp; D-- <span style="font-weight: bold; font-style: italic;">junit-reports</span>:
contains generated xml-formatted test reports<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; D-- <span style="font-weight: bold; font-style: italic;">reports/html</span>:
contains generated html-formatted test reports<br>
&nbsp;&nbsp;&nbsp; D-- <span style="font-weight: bold; font-style: italic;">dist</span>: contains
packaged archives of files
</p>
<!-- === DESIGN ============================================================ -->
<h2>PetClinic Application Design</h2>
<h3>Logging</h3>
<p>
Spring supports the use of the Apache Commons Logging API. This API
provides the ability to use Java 1.4 loggers, the simple Commons loggers,
and Apache log4j loggers. PetClinic uses log4j to provide sophisticated
and configurable logging capabilities. The file,
<span style="font-weight: bold; font-style: italic;">src/main/resources/log4j.properties</span>
configures the definition of <strong>log4j</strong>loggers.
</p>
<h3>Business Layer</h3>
<p>
The Business Layer consists of a number of basic JavaBean classes
representing the application domain objects and associated validation
objects that are used by the Presentation Layer. The validation objects
used in PetClinic are all implementations of the
<strong>org.springframework.validation.Validator</strong> interface.
</p>
<ul>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.Entity</span>
is a simple JavaBean superclass used for all persistable objects.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.NamedEntity</span>
is an extension of <span style="font-weight: bold;">Entity</span> that adds a name property.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.Specialty</span>
is an extension of <span style="font-weight: bold;">NamedEntity</span>.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.PetType</span>
is an extension of <span style="font-weight: bold;">NamedEntity</span>.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.Person</span> is
an extension of <span style="font-weight: bold;">Entity</span> that provides a superclass for all objects that
implement the notion of a person.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.Vet</span> is
an extension of <span style="font-weight: bold;">Person</span> that implements a
veterinarian. It holds a <span style="font-weight: bold;">List</span> of
specialties that the <span style="font-weight: bold;">Vet</span> is capable of.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.Owner</span>
is an extension of <span style="font-weight: bold;">Person</span> that implements a pet owner.
It holds a <span style="font-weight: bold;">List</span> of pets owned.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.Pet</span>
is an extension of <span style="font-weight: bold;">NamedEntity</span> that
implements a pet. It holds a <span style="font-weight: bold;">List</span> of
visits made concerning the pet.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.Visit</span>
is a simple JavaBean that implements the notion of a clinic visit
for a pet. </li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.util.EntityUtils</span>
provides utility methods for handling entities.</li>
</ul>
<ul>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.validation.OwnerValidator</span>
is a Spring <span style="font-weight: bold;">Validator</span> that
verifies correct data entry for the Add and Edit Owner forms.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.validation.PetValidator</span>
is a Spring <span style="font-weight: bold;">Validator</span> that
verifies correct data entry for the Add and Edit Pet forms.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.validation.VisitValidator</span>
is a Spring <span style="font-weight: bold;">Validator</span> that
verifies correct data entry for the AddVisit form.</li>
</ul>
<h3>Business / Persistence Layer</h3>
<p>
Since the PetClinic application is all about database access and there is
very little business logic in the application outside of that, there is
no separation of the primary Business and Persistence Layer API's.
While this design technique should not be used for an application with more
complex business logic, it is acceptable here because all of the
non-persistence related business rules have been implemented in
business objects and have not leaked into the Persistence Layer. The most
important facet of the design is that the Business and Persistence
Layers are <strong>COMPLETELY</strong> independent of the Presentation Layer.
</p>
<p>
The Persistence Layer can be configured to use either HSQL or MySQL
with any one of the following data access technologies aided by
infrastructure provided by Spring:
</p>
<ul>
<li>JDBC</li>
<li>Hibernate 3</li>
<li>Java Persistence API</li>
</ul>
<p>
<span style="font-weight: bold;">NOTE:</span> Spring also provides
infrastructure for using other
<strong>O</strong>bject/<strong>R</strong>elational <strong>M</strong>apping
frameworks such as JDO and iBATIS SqlMaps, but these are not demonstrated in PetClinic.
(See the 'jpetstore' sample application that ships with the full Spring Framework
distribution for an example of using iBatis and Spring.)
</p>
<p>
One of the key elements provided by Spring is the use of a common set
of meaningful data access exceptions that can be used regardless of
which database or access strategy is used. All of these exceptions
derive from <strong>org.springframework.dao.DataAccessException</strong>.
Since most exceptions encountered during database access are indicative
of programming errors, <strong>DataAccessException</strong> is an
abstract <strong>RuntimeException</strong> whose derivatives only need
to be caught by application code to handle recoverable errors when it
makes sense to do so. This greatly simplifies application code compared
to, for example, code using JDBC directly where <strong>SqlExceptions</strong>
must be caught and database specific error codes must be decoded.
Examination of the PetClinic source code will show that the
persistence-oriented code is completely focused on the relevant
transfer of data to/from the referenced objects without extraneous
error handling.
</p>
<p>
The high-level business/persistence API for PetClinic is the
<span style="font-weight: bold;">org.springframework.samples.petclinic.Clinic</span>
interface. Each persistence strategy in PetClinic is a different implementation of the
<span style="font-weight: bold;">Clinic</span> interface. In each case, the
<span style="font-weight: bold;">Clinic</span> implementation is fronted by
a transactional proxy, configured via the
<span style="font-weight: bold;">@Transactional</span> annotation, that also
implements <span style="font-weight: bold;">Clinic</span>. These objects
are standard Java dynamic proxies which are created by an instance of
<span style="font-weight: bold;">org.springframework.transaction.interceptor.TransactionProxyFactoryBean</span>.
These proxies are configured in the respective application context file
via <strong>&lt;tx:annotation-driven /&gt;</strong> and specify that all
<span style="font-weight: bold;">Clinic</span> methods are run in a
transactional context. The transaction managers used in PetClinic are all
implementations of the
<span style="font-weight: bold;">org.springframework.transaction.PlatformTransactionManager</span>
interface. All of the implementations are by default configured
to use a local <span style="font-weight: bold;">DataSource</span> that
will work in any environment through the use of an instance of
<span style="font-weight: bold;">org.springframework.jdbc.datasource.DriverManagerDataSource</span>.
While this is appropriate for use in a demo or single user
program, a connection pooling <span style="font-weight: bold;">DataSource</span>,
such as an instance of <span style="font-weight: bold;">org.apache.commons.dbcp.BasicDataSource</span>,
is more appropriate for use in a multi-user application. Another
alternative is to obtain one through the Java EE environment
using an instance of
<span style="font-weight: bold;">org.springframework.jndi.JndiObjectFactoryBean</span>.
</p>
<h3>JDBC Clinic Implementation</h3>
<p>
Spring provides a number of high-level database
access convenience classes in the package
<span style="font-weight: bold;">org.springframework.jdbc.object</span>.
These classes and the lower-level Spring classes that they use in the
<span style="font-weight: bold;">org.springframework.jdbc.core</span> package
provide a higher level of abstraction for using JDBC that keeps the developer
from having to correctly implement the handling of the checked
<span style="font-weight: bold;">SqlExceptions</span> with ugly error-prone
nested try-catch-finally blocks. Using the classes in this package
allows the developer to focus efforts on the functionality being
implemented rather than the mechanics of error handling. When using
these classes, it is the responsibility of the developer to provide the
SQL needed and to map the parameters to/from the respective domain
object. This typically is done by extending one of the
<span style="font-weight: bold;">org.springframework.jdbc.object</span> classes,
initializing its SQL, and overriding a method that takes care of
the mapping. In this way, the developer gets to focus on implementing
functionality rather than application plumbing. These classes also
take care of closing connections to prevent hard to find resource
leakage problems. It should be noted that instances of these classes
are lightweight, reusable, and threadsafe.
</p>
<p>
The JDBC implementation of the Clinic interface is
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.jdbc.SimpleJdbcClinic</span>,
which uses Java 5 language features,
<strong>org.springframework.jdbc.core.simple.SimpleJdbcTemplate</strong>, and
<strong>org.springframework.jdbc.core.simple.SimpleJdbcInsert</strong>.
It also takes advantage of classes like
<strong>org.springframework.jdbc.core.namedparam.BeanPropertySqlParameterSource</strong> and
<strong>org.springframework.jdbc.core.simple.ParameterizedBeanPropertyRowMapper</strong>
which provide automatic mapping between JavaBean properties and JDBC
parameters or query results. SimpleJdbcClinic is a rewrite of the
AbstractJdbcClinic which was the base class for JDBC implementations of
the Clinic interface for Spring 2.0.
</p>
<p>
The transaction manager used in the JDBC Clinic Implementation is an
instance of <span style="font-weight: bold;">org.springframework.jdbc.datasource.DataSourceTransactionManager</span>
that can be used for local transactions.
</p>
<h3>Hibernate 3 Clinic Implementation</h3>
<p>
The Hibernate 3 implementation of the <span style="font-weight: bold;">Clinic</span>
interface is
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.hibernate.HibernateClinic</span>.
To simplify using Hibernate, Spring provides the
<span style="font-weight: bold;">org.springframework.orm.hibernate3.LocalSessionFactoryBean</span>.
The Hibernate configuration is provided by the file <span style="font-style: italic;">src/main/resources/petclinic.hbm.xml</span>.
</p>
<h3>Java Persistence API (JPA) Clinic Implementation</h3>
<p>
The JPA implementation of the <span style="font-weight: bold;">Clinic</span>
interface is
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.jpa.EntityManagerClinic</span>,
which is based on native JPA usage combined with Spring's
<span style="font-weight: bold;">@Repository</span> and
<span style="font-weight: bold;">@Transactional</span> annotations but
otherwise has no dependencies on any Spring API's.
To simplify JPA usage, Spring provides (among other classes) the
<span style="font-weight: bold;">org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean</span>.
The JPA configuration is provided by
<span style="font-style: italic;">src/main/resources/META-INF/orm.xml</span> and
<span style="font-style: italic;"> src/main/resources/META-INF/persistence.xml.</span>
</p>
<h3>ApplicationContext</h3>
<p>
A Spring <span style="font-weight: bold;">org.springframework.context.ApplicationContext</span> object
provides a map of user-defined JavaBeans that specify either a singleton
object or the initial construction of prototype instances. These beans
constitute the <span style="font-weight: bold;">Business/Persistence
Layer</span> of PetClinic. The following beans are defined in all 3
versions (1 per access strategy) of the PetClinic
<span style="font-style: italic;">src/main/webapp/WEB-INF/applicationContext-*.xml</span>
file:
</p>
<ol>
<li>A <span style="font-weight: bold; font-style: italic;">PropertyPlaceholderConfigurer</span>,
which is configured via
<strong>&lt;context:property-placeholder ... /&gt;</strong> and
is a singleton bean that replaces ${...} placeholders with values from a
properties file, in this case, JDBC-related settings for the
<span style="font-weight: bold; font-style: italic;">dataSource</span> bean
described below
(see <span style="font-weight: bold; font-style: italic;">src/main/resources/jdbc.properties</span>).
</li>
<li><span style="font-weight: bold; font-style: italic;">dataSource</span>,
which is a singleton bean that defines the implementation of the source
of database connections used by the application.
</li>
<li><span style="font-weight: bold; font-style: italic;">transactionManager</span>,
which is a singleton bean that defines the implementation of the transaction
management strategy for the application.
</li>
<li><span style="font-weight: bold; font-style: italic;">clinic</span>,
which is a singleton bean that defines the implementation of the
<span style="font-weight: bold;">Clinic</span> interface that provides the
primary Business Layer API of the application.
</li>
</ol>
<h3>Presentation Layer</h3>
<p>
The Presentation Layer is implemented as a Java EE Web Application and
provides a very thin and concise Model-View-Controller type user
interface to the Business and Persistence Layers.
</p>
<p>
The PetClinic web application is configured via the following files:
</p>
<ul>
<li><span style="font-weight: bold; font-style: italic;">src/main/webapp/WEB-INF/web.xml</span>:
the web application configuration file.</li>
<li><span style="font-weight: bold; font-style: italic;">src/main/webapp/WEB-INF/petclinic-servlet.xml</span>:
configures the petclinic dispatcher servlet and the other controllers
and forms that it uses. The beans defined in this file reference the
Business/Persistence Layer beans defined in
<span style="font-style: italic;">applicationContext-*.xml.</span></li>
<li><span style="font-weight: bold; font-style: italic;">src/main/resources/messages*.properties</span>:
configures the definition of internationalizable message resources.</li>
</ul>
<p>
Examine the comments provided in each of these files for a more
in-depth understanding of the details of how the application is
configured.
</p>
<h3>General</h3>
<ul>
<li>In <span style="font-weight: bold; font-style: italic;">web.xml</span>,
a context-param, "<span style="font-weight: bold;">webAppRootkey</span>",
provides the key for a system property that specifies the root directory
for the web application. This parameter,
<span style="font-weight: bold;">"petclinic.root"</span>, can be used to aid
in configuring the application.</li>
<li>In <span style="font-weight: bold; font-style: italic;">web.xml</span>,
a <span style="font-weight: bold;">org.springframework.web.context.ContextLoaderListener</span>
is defined that loads the root <span style="font-weight: bold;">ApplicationContext</span>
object of this webapp at startup, by default from the designated
<span style="font-weight: bold; font-style: italic;">/WEB-INF/applicationContext-*.xml</span>.
The root <span style="font-weight: bold;">org.springframework.web.context.WebApplicationContext</span>
of PetClinic is an instance of
<span style="font-weight: bold;">org.springframework.web.context.support.XmlWebApplicationContext</span>
and is the parent of all servlet-specific <span style="font-weight: bold;">ApplicationContexts</span>.
The Spring root <span style="font-weight: bold;">ApplicationContext</span> object
provides a map of user-defined JavaBeans that can be used in any and
all layers of the application. Beans defined in the root
<span style="font-weight: bold;">ApplicationContext</span> are automatically
available in all child <span style="font-weight: bold;">ApplicationContext</span>
objects as (external) bean references. Beans defined in an
<span style="font-weight: bold;">ApplicationContext</span> can also be
accessed directly by Java code through
<span style="font-style: italic;">getBean(name)</span> method calls.
</li>
<li>In <span style="font-weight: bold; font-style: italic;">web.xml</span>,
a <span style="font-weight: bold;">Servlet</span> named
<span style="font-weight: bold;">"petclinic"</span> is specified to act as
a dispatcher for the entire application. This
<span style="font-weight: bold;">org.springframework.web.servlet.DispatcherServlet</span>
is used to handle all URL's matching the pattern <span style="font-weight: bold;">"*.do"</span>.
As with any <span style="font-weight: bold;">Servlet</span>, multiple URL mappings may
be defined. It is also possible to define multiple instances of
<span style="font-weight: bold;">DispatcherServlet</span>. Each
<span style="font-weight: bold;">DispatcherServlet</span> dispatches
requests to registered handlers (<span style="font-weight: bold;">Controller</span>
interface implementations or POJOs annotated with <strong>@Controller</strong>)
indirectly through a
<span style="font-weight: bold;">org.springframework.web.servlet.handler.HandlerMapping</span>
implementation. Each <span style="font-weight: bold;">DispatcherServlet</span>
has its own <span style="font-weight: bold;">ApplicationContext</span>,
by default defined in <span style="font-weight: bold;">"{servlet-name}-servlet.xml"</span>.
In this case, it is in the file <span style="font-weight: bold;">"petclinic-servlet.xml"</span>.
This <span style="font-weight: bold;">ApplicationContext</span> is
used to specify the various web application user interface beans and
the URL mappings that are used by the <span style="font-weight: bold;">DispatcherServlet</span>
to control the handling of requests.
</li>
</ul>
<p>
The files <span style="font-weight: bold; font-style: italic;">web.xml</span> and
<span style="font-weight: bold; font-style: italic;">log4j.properties</span> specify
the configuration of logging in the system:
</p>
<ul>
<li>In <span style="font-weight: bold; font-style: italic;">web.xml</span>,
a <span style="font-weight: bold;">"log4jConfigLocation"</span> context-param
is specified that sets the location of the
<span style="font-weight: bold;">log4j</span> configuration file. The
default location for this file is
<span style="font-weight: bold; font-style: italic;">/WEB-INF/classes/log4j.properties</span>.
Specifying this parameter explicitly allows the location to be changed
from the default and is also used to cause periodic
<span style="font-weight: bold;">log4j</span> configuration refresh checks.</li>
<li>In <span style="font-weight: bold; font-style: italic;">web.xml</span>,
a <span style="font-weight: bold;">Log4jConfigListener</span> is
specified that will initialize <span style="font-weight: bold;">log4j</span> using
the specified configuration file when the web app starts. The
<span style="font-weight: bold;">Log4jConfigListener</span> is commented out
in the file because of a conflict when using JBoss. It should also be
noted that if the container initializes Servlets before Listeners as
some pre-Servlet 2.4 containers do, a <b>Log4jConfigServlet</b> should
be used instead.</li>
<li>In <span style="font-weight: bold; font-style: italic;">log4j.properties</span>,
the following loggers are specified:
<ul>
<li><span style="font-weight: bold; font-style: italic;">"stdout"</span> provides
logging messages to the container's log file.</li>
<li><span style="font-weight: bold; font-style: italic;">"logfile"</span> provides
logging messages to a rolling file that is specified using the
previously defined "petclinic.root".</li>
</ul>
</li>
</ul>
<p>
Examination and study of these logging files will provide insight into
the operation of the Spring framework and the application as well as
valuable troubleshooting information should something not work
correctly.
</p>
<h3>DispatcherServlet</h3>
<p>
The following beans are accessible to the
<span style="font-weight: bold;">DispatcherServlet</span> and are defined
in the PetClinic
<span style="font-weight: bold; font-style: italic;">petclinic-servlet.xml</span>
file. This dispatcher uses these definitions to delegate actual display
and form processing tasks to implementations of the Spring
<span style="font-weight: bold;">org.springframework.web.servlet.mvc.Controller</span>
interface. The <span style="font-weight: bold;">DispatcherServlet</span>
acts as the main application <span style="font-weight: bold;">Front Controller</span>
and is responsible for dispatching all requests to the appropriate
<span style="font-weight: bold;">Controller</span> indirectly through a URL
mapping handler. These <span style="font-weight: bold;">Controllers</span> are
responsible for the mechanics of interaction with the user and ultimately
delegate action to the Business/Persistence Layers.
</p>
<ul>
<li>
<span style="font-weight: bold; font-style: italic;">messageSource</span>
is a singleton bean that defines a message source for this
<span style="font-weight: bold;">ApplicationContext</span>. Messages are
loaded from localized <span style="font-weight: bold;">"messages_xx"</span>
files in the classpath, such as
<span style="font-weight: bold; font-style: italic;">"/WEB-INF/classes/messages.properties"</span>
or <span style="font-weight: bold; font-style: italic;">"/WEB-INF/classes/messages_de.properties"</span>.
<span style="font-style: italic;">getMessage()</span> calls to this context
will use this source. Child contexts can have their own message sources,
which will inherit all messages from this source and are able to define new
messages and override ones defined in the primary message source.
</li>
<li>
<span style="font-weight: bold; font-style: italic;">InternalResourceViewResolver</span>
is a singleton bean that defines the view mappings used by the dispatcher.
Specifically, logical view names returned by Controllers will be mapped to
physical paths using the configured 'prefix' and 'suffix' properties. For
example, a logical view name of "vets" will be mapped to "/WEB-INF/jsp/vets.jsp".
</li>
<li>
<span style="font-weight: bold; font-style: italic;">SimpleMappingExceptionResolver</span>
is a singleton bean that defines how exceptions are propagated. Exceptions
encountered that are not specified are propagated to the servlet container.
</li>
<li>
<span style="font-weight: bold; font-style: italic;">&lt;context:component-scan ... /&gt;</span>
is used to autodetect the controllers in the
<strong>org.springframework.samples.petclinic.web</strong> package, which
are POJOs labeled with the <strong>@Controller</strong> annotation.
<ul>
<li>
<strong>ClinicController</strong> is a singleton, annotation-driven
<em>MultiActionController</em> that is used by the dispatcher to handle
non-form based display tasks. A method is provided to handle each
type of request that is supported.
</li>
<li>
In addition, there are 6 singleton, annotation-driven <em>Form</em> controllers,
which are used to handle the various Search, Add and Edit form processing
tasks for the dispatcher.
</li>
</ul>
</li>
<li>
The form-based controllers within the PetClinic application provide
<strong>@RequestMapping</strong> annotations at the type level for path
mapping URLs and @RequestMapping at the method level for request type
mappings (e.g., GET and POST). In contrast, <strong>ClinicController</strong>
&ndash; which is not form-based &ndash; provides @RequestMapping only at
the method level for path mapping URLs.
<strong>DefaultAnnotationHandlerMapping</strong> is driven by these
annotations and is enabled by default with Java 5+.
</li>
</ul>
<h3>Views</h3>
<p>
The <span style="font-weight: bold;">Controllers</span> used by the
dispatcher handle the work flow of the application. The actual display
tasks are delegated by the <span style="font-weight: bold;">Controllers</span>
to implementations of the Spring <span style="font-weight: bold;">View
</span>interface. These <span style="font-weight: bold;">View</span> objects are
themselves beans that can render a particular type of view. The
handling <span style="font-weight: bold;">Controller</span> supplies the
<span style="font-weight: bold;">View</span> with a data model to render.
The data model is provided to the <span style="font-weight: bold;">View</span>
as a <span style="font-weight: bold;">Map</span> of objects.
<span style="font-weight: bold;">Views</span> are only responsible for
rendering a display of the data model and performing any display logic
that is particular to the type of <span style="font-weight: bold;">View</span>
being rendered. Spring provides support for rendering many different types of
views: JSP, XSLT, PDF, Velocity templates, Excel files, and others. By
using a <span style="font-weight: bold;">View</span> mapping strategy,
Spring supplies the developer with a great deal of flexibility in supporting
easily configurable view substitution.
</p>
<p>
<strong>ClinicController</strong> relies on
<strong>RequestToViewNameTranslator</strong> to automatically infer the
logical view name from the incoming request URL; whereas, all <em>Form</em>
controllers in the PetClinic application return logical view names as Strings.
These logical view names are then mapped to physical paths via the
configured <strong>InternalResourceViewResolver</strong> (see the
DispatcherServlet section above for further details). Logical view names that
are prepended with <em>&quot;redirect:&quot;</em> will be resolved to instances
of <strong>RedirectView</strong>, which simply redirects to another URL.
The other resolved <strong>View</strong>s will be instances of
<strong>JstlView</strong>, which provides some handy support for
internationalization &amp; localization in JSP pages that use JSTL.
</p>
<h3>Messages</h3>
<p>
The <span style="font-weight: bold; font-style: italic;">messages*.properties</span>
files are loaded from the classpath to provide localized messages for
the supported languages. PetClinic supplies a localized
<strong>"welcome"</strong> message as well as localized form entry error
messages in the default (i.e., English) and German properties files.
See the "countries" sample application for a more detailed example of Spring's
support for internationalization.
</p>
<h3>Presentation Layer classes</h3>
<ul>
<li>
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.web.ClinicController</span>
is an annotation-driven, POJO <em>MultiActionController</em>
that is used to handle simple display-oriented URLs.
</li>
<li>
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.web.FindOwnersForm</span>
is an annotation-driven, POJO <em>Form</em> controller that is used to search for
<strong>Owner</strong>s by last name.
</li>
<li>
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.web.AddOwnerForm</span>
is an annotation-driven, POJO <em>Form</em> controller that is used to add a new <strong>Owner</strong>
to the system.
</li>
<li>
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.web.EditOwnerForm</span>
is an annotation-driven, POJO <em>Form</em> controller that is used to edit an existing <strong>Owner</strong>.
A copy of the existing <strong>Owner</strong> is used for editing.
</li>
<li>
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.web.AddPetForm</span>
is an annotation-driven, POJO <em>Form</em> controller that is used to add a new <strong>Pet</strong>
to an existing <strong>Owner</strong>.
</li>
<li>
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.web.EditPetForm</span>
is an annotation-driven, POJO <em>Form</em> controller that is used to edit an existing <strong>Pet</strong>.
A copy of the existing <strong>Pet</strong> is used for editing.
</li>
<li>
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.web.AddVisitForm</span>
is an annotation-driven, POJO <em>Form</em> controller that is used to add a new <strong>Visit</strong>
to an existing <strong>Pet</strong>.
</li>
</ul>
<h3>Logical Views &amp; Implemented Use Cases</h3>
<ul>
<li><span style="font-weight: bold; font-style: italic;">welcome</span> is
the "home" screen. It provides links to display a list of all vets,
find an owner, or view documentation.</li>
<li><span style="font-weight: bold; font-style: italic;">vets</span> displays
all vets and their specialties.</li>
<li><span style="font-weight: bold; font-style: italic;">findOwners</span>
is used to find owners by last name.</li>
<li><span style="font-weight: bold; font-style: italic;">findOwnersRedirect</span>
redirects to findOwner.</li>
<li><span style="font-weight: bold; font-style: italic;">selectOwner</span>
allows user to select from a list of multiple owners with the same last
name.</li>
<li><span style="font-weight: bold; font-style: italic;">owner</span> displays
a owner's data and a list of the owner's pets and their data.</li>
<li><span style="font-weight: bold; font-style: italic;">ownerRedirect</span>
redirects to owner.</li>
<li><span style="font-weight: bold; font-style: italic;">owner</span> supports
<span style="font-weight: bold; font-style: italic;">AddOwnerForm</span>
and <span style="font-weight: bold; font-style: italic;">EditOwnerForm</span></li>
<li><span style="font-weight: bold; font-style: italic;">pet</span> supports
<span style="font-weight: bold; font-style: italic;">AddPetForm</span>
and <span style="font-weight: bold; font-style: italic;">web.EditPetForm</span></li>
<li><span style="font-weight: bold; font-style: italic;">visit</span> supports
<span style="font-weight: bold; font-style: italic;">AddVisitForm</span></li>
<li><span style="font-weight: bold; font-style: italic;">dataAccessFailure</span>
displays a stacktrace</li>
</ul>
<h3>Java Server Pages</h3>
<ul>
<li><span style="font-weight: bold; font-style: italic;">index.jsp</span>
redirects to the "welcome" page.</li>
<li><span style="font-weight: bold; font-style: italic;">includes.jsp</span> is
statically included in <span style="text-decoration: underline;">all</span>
JSP's used in the application. It specifies the taglibs that are in use.</li>
<li><span style="font-weight: bold; font-style: italic;">header.jsp</span> and
<span style="font-style: italic; font-weight: bold;">footer.jsp</span>
display info common to virtually all pages. Spring also supplies
support for the integration of <a href="http://www.lifl.fr/%7Edumoulin/tiles">Tiles</a>
(included in Struts) but this is not used in PetClinic.</li>
<li><span style="font-weight: bold; font-style: italic;">dataAccessFailure.jsp</span>
is the error page configured via
<span style="font-weight: bold; font-style: italic;">SimpleMappingExceptionResolver</span>,
which displays a stack trace and normally wouldn't be used in a production
version of an application. It can be seen in action by entering a URL of
"editOwner.do" or "editPet.do" with an invalid request parameter, for example:
<a href="http://localhost:8080/org.springframework.samples.petclinic/owner.do?ownerId=-1">/petclinic/owner.do?ownerId=-1</a>.
The handlers for these URLs normally expect to see a respective "ownerId" or "petId"
request parameter corresponding to an Owner or Pet in the database. Thus,
these handlers will throw a <strong>DataAccessException</strong> when such
a request parameter is provided which references a non-existing entity.</li>
<li><span style="font-weight: bold; font-style: italic;">uncaughtException.jsp</span>
is the <span style="font-weight: bold; font-style: italic;">web.xml</span> configured
"error-page". It displays a stack trace and normally wouldn't be used
in a production version of an application. It can be seen in action by
entering a URL of "editOwner.do" or "editPet.do" without a valid request
parameter, for example:
<a href="http://localhost:8080/org.springframework.samples.petclinic/owner.do">/petclinic/owner.do</a>.
The handlers for these URLs normally expect to see a respective "ownerId" or "petId"
request parameter and throw a <strong>ServletException</strong> when such
a request parameter is not found.</li>
<li><span style="font-weight: bold; font-style: italic;">welcome.jsp</span> implements
<span style="font-weight: bold; font-style: italic;">welcome</span>.</li>
<li><span style="font-weight: bold; font-style: italic;">vets.jsp</span> implements
<span style="font-weight: bold; font-style: italic;">vets</span>.</li>
<li><span style="font-weight: bold; font-style: italic;">findOwners.jsp</span> implements
<span style="font-weight: bold; font-style: italic;">findOwners</span>.</li>
<li><span style="font-weight: bold; font-style: italic;">owners.jsp</span> implements
<span style="font-weight: bold; font-style: italic;">selectOwner</span>.</li>
<li><span style="font-weight: bold; font-style: italic;">owner.jsp</span> implements
<span style="font-weight: bold; font-style: italic;">owner</span>.</li>
<li><span style="font-weight: bold; font-style: italic;">ownerForm.jsp</span> implements
<span style="font-weight: bold; font-style: italic;">ownerForm</span>.</li>
<li><span style="font-weight: bold; font-style: italic;">petForm.jsp</span> implements
<span style="font-weight: bold; font-style: italic;">petForm</span>.</li>
<li><span style="font-weight: bold; font-style: italic;">visitForm.jsp</span> implements
<span style="font-weight: bold; font-style: italic;">visitForm</span>.</li>
</ul>
<p>
The following items should be noted regarding the web application
implementation design:
</p>
<ol>
<li>all JSP's are stored under <span style="font-weight: bold; font-style: italic;">/WEB-INF/jsp</span> except
for <span style="font-weight: bold; font-style: italic;">index.jsp</span> which
is the configured "welcome-file"</li>
<li>The use of JSP technology in the application is not exposed to
the user, i.e., the end user never sees a URL ending in
<span style="font-weight: bold; font-style: italic;">".jsp".</span></li>
<li>By convention, all URL's in the application ending in
<span style="font-weight: bold; font-style: italic;">".do"</span> are
handled by web application controllers. Static html pages ending in
<span style="font-weight: bold; font-style: italic;">".html"</span>, such as
Javadoc, will be directly served to the end user.</li>
<li>The results of all form entries are handled using browser round
trip redirection to minimize possible end user confusion.</li>
<li>All pages are extremely simple JSP implementations that focus
only on providing the necessary functionality.</li>
<li>References to <span style="font-weight: bold;">Entity</span> objects
are passed around in the application by supplying the object's <code>ID</code>
as a request parameter.</li>
</ol>
<h3>Testing</h3>
<ul>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.OwnerTests</span>
is a simple JUnit 4 based TestCase that supports Business Rule #1.</li>
<li><span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.AbstractClinicTests</span>
is a JUnit 4 based TestCase requiring a live database connection that is
used to confirm correct operation of the database access objects in the
various implementations of the <strong>Clinic</strong> interface.
&quot;AbstractClinicTests-context.xml&quot; declares a common
<strong>javax.sql.DataSource</strong>. Subclasses specify additional
context locations which declare a
<strong>org.springframework.transaction.PlatformTransactionManager</strong>
and a concrete implementation of <strong>Clinic</strong>.
<p>
AbstractClinicTests extends
<strong>AbstractTransactionalJUnit4SpringContextTests</strong>,
one of the valuable testing support classes provided by the
<em>Spring TestContext Framework</em> found in the
<code>org.springframework.test.context</code> package. The
annotation-driven configuration used here represents best practice for
integration tests with Spring. Note, however, that
AbstractTransactionalJUnit4SpringContextTests serves only as a convenience
for extension. For example, if you do not wish for your test classes to be
tied to a Spring-specific class hierarchy, you may configure your tests with
annotations such as <strong>@ContextConfiguration</strong>,
<strong>@TestExecutionListeners</strong>, <strong>@Transactional</strong>, etc.
</p>
<p>
AbstractClinicTests and its subclasses benefit from the following services
provided by the Spring TestContext Framework:
</p>
<ul>
<li><strong>Spring IoC container caching</strong> which spares us
unnecessary set up time between test execution.</li>
<li><strong>Dependency Injection</strong> of test fixture instances,
meaning that we don't need to perform application context lookups. See the
use of <strong>@Autowired</strong> on the <code>clinic</code> instance
variable, which uses autowiring <em>by type</em>. As an alternative, we
could annotate <code>clinic</code> with JSR 250's
<strong>@Resource</strong> to achieve dependency injection <em>by name</em>.
<em>(see: <strong>@ContextConfiguration</strong>,
<strong>DependencyInjectionTestExecutionListener</strong>)</em></li>
<li><strong>Transaction management</strong>, meaning each test method is
executed in its own transaction, which is automatically rolled back by
default. Thus, even if tests insert or otherwise change database state, there
is no need for a teardown or cleanup script.
<em>(see: <strong>@TransactionConfiguration</strong>,
<strong>@Transactional</strong>, <strong>TransactionalTestExecutionListener</strong>)</em></li>
<li><strong>Useful inherited protected fields</strong>, such as a
<strong>SimpleJdbcTemplate</strong> that can be used to verify
database state after test operations or to verify the results of
queries performed by application code. An
<strong>ApplicationContext</strong> is also inherited and can be
used for explicit bean lookup if necessary.
<em>(see: <strong>AbstractJUnit4SpringContextTests</strong>,
<strong>AbstractTransactionalJUnit4SpringContextTests</strong>)</em></li>
</ul>
<p>
The <em>Spring TestContext Framework</em> and related unit and
integration testing support classes are shipped in
<code>spring-test.jar</code>.
</p>
</li>
</ul>
<h3>Downloads</h3>
<ul>
<li>Download and install the
<a href="http://www.springsource.com/download/community?project=Spring%20Framework" target="_blank">Spring Framework</a>
(the PetClinic sample application is included)</li>
<li>Download and install a <a href="http://java.sun.com/" target="_blank">Java</a>
Software Developer Kit, version 1.5 or later</li>
<li>Download and install <a href="http://maven.apache.org" target="_blank">Apache Maven</a>,
preferably version 2.0.10 or later</li>
<li>Download and install <a href="http://ant.apache.org" target="_blank">Apache Ant</a>,
preferably version 1.7.1 or later</li>
<li>Download and install <a href="http://jakarta.apache.org/tomcat/index.html" target="_blank">Apache Tomcat</a>,
preferably version 6.0.20 or later</li>
<li>Download and install <a href="http://dev.mysql.com/downloads/" target="_blank">MySQL</a>,
preferably version 5.1.x or later (optional)</li>
<li><a href="http://hsqldb.sourceforge.net/" target="_blank">Hypersonic SQL</a>, and
<a href="http://hibernate.org/" target="_blank">Hibernate</a> are provided with the
application.</li>
<li>PetClinic and Spring use the <a href="http://www.apache.org/" target="_blank">Apache</a>
<a href="http://commons.apache.org/logging/" target="_blank">Commons Logging</a>
and <a href="http://logging.apache.org/log4j/" target="_blank">log4j</a>
packages.</li>
</ul>
<h3>Maven Setup</h3>
<p>
Make sure that the Maven executable is in your command shell path.
</p>
<h3>MYSQL Setup (optional)</h3>
<p>
Add the PetClinic database to a running MySQL server by following the
explicit instructions found in
<span style="font-weight: bold; font-style: italic;">db/mysql/petclinic_db_setup_mysql.txt</span>.
PetClinic expects by default to be able to access the server via the
standard port <code>3306</code>. To use a different port, it will be
necessary to change the PetClinic Database Setup.
</p>
<h3>PetClinic Database Setup</h3>
<p>
To use a Java EE server supplied connection-pooled data source with
Tomcat, it will be necessary to use and possibly edit the appropriate
context definition file for the petclinic webapp. To use it, deploy a
copy of the appropriate context definition file in Tomcat's webapps
directory and restart the server. Consult the Tomcat log files if
something goes wrong when starting either Tomcat or the PetClinic
application. The context files are named
<span style="font-weight: bold; font-style: italic;">petclinic_tomcat_*.xml</span>,
where <strong>*</strong> is either &quot;hsqldb&quot; or &quot;mysql&quot;.
There is a context file supplied for each
database in its respective directory. There is also a context file
<span style="font-weight: bold; font-style: italic;">db/petclinic_tomcat_all.xml</span>
that will provide a JNDI connection-pooled DataSource for all supported
databases. Should you use this file, you must of course make sure that all the
database servers are running when you restart Tomcat.
</p>
<p>
<a name="dbNotes"></a>
<span style="font-weight: bold;">NOTES:</span>
</p>
<ol>
<li>Should you deploy one of the context files or define a context in
Tomcat's <span style="font-weight: bold; font-style: italic;">server.xml</span>,
Tomcat will not automatically deploy the webapp from the
<span style="font-weight: bold; font-style: italic;">petclinic.war</span> file.
The webapp will then need to be manually extracted to the target
directory.</li>
<li>The context files will also configure logging to supply a
separate log file for the petclinic context. This will separate the
container logging for petclinic from that of the other webapps. This
should not be confused with the application log file provided through
<span style="font-weight: bold;">log4j.</span></li>
<li>An Ant script (<span style="font-weight: bold; font-style: italic;">db/build.xml</span>)
has been provided that can be used to re-initialize either database. To
select or configure the data source and database used for the webapp and
for testing, you will need to edit the following files:
<ul>
<li><span style="font-weight: bold; font-style: italic;">src/main/webapp/WEB-INF/applicationContext-*.xml</span>:
for configuring the DataSource in the webapp</li>
<li><span style="font-weight: bold; font-style: italic;">src/main/resources/jdbc.properties</span>:
for configuring JDBC connection settings for both the webapp and testing</li>
<li><span style="font-weight: bold; font-style: italic;">build.properties</span>:
for running the &quot;tests&quot; target in Ant</li>
</ul>
</li>
</ol>
<h3>Building the PetClinic Application</h3>
<p>
Open a command line shell and navigate to the directory containing
PetClinic. Make sure the database is running and execute
&quot;mvn clean package&quot;. This will run clean and compile everything
and execute the tests, including integration tests against an in-memory
database.
</p>
<h3>Deploying the PetClinic Application</h3>
<p>
Deploy the web application to the server in the usual way (see
<a href="#dbNotes">notes</a> regarding database setup). If you need
instructions for web application deployment, see the Tomcat
documentation for details. The Web Application aRchive file is
<span style="font-weight: bold; font-style: italic;">org.springframework.samples.petclinic.war</span>
and can be found in the
<span style="font-weight: bold; font-style: italic;">target/artifacts</span> directory.
</p>
<h3>Using the PetClinic Application</h3>
<p>
Make sure the PetClinic web application is running and browse to
<a href="http://localhost:8080/org.springframework.samples.petclinic/">http://localhost:8080/org.springframework.samples.petclinic/</a>.
</p>
<table class="footer">
<tr>
<td><a href="../welcome.do">Home</a></td>
<td align="right"><img src="../images/springsource-logo.png"/></td>
</tr>
</table>
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink