Thread: [Springframework-developer] NEW Petclinic version

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Spring Petclinic Demo/tutorial Application
************************************************
Author: Ken Krebs kk...@kk...

Date: 21-JUNE-2003

NOTE: This document is VERY VERY VERY PRELIMINARY !!! I'm just getting started.
I will actually be providing more detailed installation instructions as well as the
tutorial instructions.

Tools I Used
============
Java SDK 1.4.1_01
Ant 1.5.1
JUnit 3.8.1
Tomcat 4.1.18
Hypersonic SQL 1.7.1   OR   Mysql 3.23.53 with mysql-connector-java-2.0.14-bin.jar
spring-full-0.8.jar compiled with files available on 21-JUNE-2003

Primary Ant Targets
===================
clean       -->   Cleans output dirs
build       -->   Compile main source tree java files into class files
webapp      -->   Builds the web application archive
docs        -->   Create Javadoc API documentation
test        -->   Run tests & reinitialize database
all         -->   Clean,build,webapp,docs,test

NOTE: Ant will need to have a copy of the db and JUnit jars in it's lib directory.

Directory Structure
=========================================================================================
f-- indicates a file
d-- indicates a directory
D-- indicates a directory that is created by the Ant build script

d-- Petclinic1 : the root directory of the project
    f-- build.xml : the Ant build script
    f-- build.properties : a properties file for the  Ant build script
    d-- src : Java source file directory tree
    d-- websrc : the web application source directory tree 
    d-- test : a parallel testing directory tree
    d-- db : database sql scripts and related files
        d-- hsqldb : directory for files related to HSQL, contains scripts and context defs
        d-- mysql : directory for files related to MYSQL, contains scripts and context defs
        f-- petclinic_tomcat_all.xml : context definition for all db's
        f-- build.xml : Ant script for populating/emptying the database
    D-- build : compiled .class files
    D-- dist : Java archive files
    D-- docs : Javadoc files
    D-- war : the web application image from which the .war file is generated

IMPORTANT NOTE: Edit the build.properties file in the project root directory to select or configure the database and
set local file specifications for your installation.

Database Overview
=================
Support has been provided for use with either MYSQL or HypersonicSQL (default). SQL text scripts are provided for
database creation. Ant scripts are provided for database population. XML files are provided for setup of Tomcat pooled
connection datasources. There are separate applicationContext.xml files provided for the tests and the webapp. The 
webapp use a JNDI pooled connection supplied by Tomcat. The test version uses DriverManagerDataSource connections.

The files db/hsqldb directory can be copied to another location and the database HSQL database can be started from there.
There are Windows batch files provided containing the Java commands for starting the HSQL server and manager that can be
run by double-clicking. The petclinic.script file will then initialize the HSQL database automatically. 

owners - PK id
types (as in pet types) - PK id
pets - PK id,  FK type_id, FK owner_id
vets - PK id
specialties - PK id
vet_specialties (link table) - FK vet_id, FK specialty_id
visits - PK id, FK pet_id 

NOTE: Each table has a corresponding table with a "_seq" suffix added to its name. These tables are used to provide primary keys.

There is not yet a lot of sample data that has been provided. When exploring the application, the most interesting owner names to search on are "Davis" and "Coleman". I will probably add more sample data later.
If you wish to add to the sample data, please send me your insert script code and I will integrate it.

Spring Framework Parts Demonstrated
===================================
Beans
    - XmlBeanFactory (singleton & prototype)
    - InitializingBean
    - BeanUtils
    - CustomDateEditor

Context
    - ApplicationContext
    - ClassPathXmlApplicationContext
    - ApplicationContextAware
    - ApplicationContextException
    - ResourceBundleMessageSource

Logging support
    - Commons Log & Logfactory
    - Log4J configuration

Validation
    - Validator
    - Errors

Web application
    - ContextLoaderListener
    - DispatcherServlet
    - BindTag
    - ResourceBundleViewResolver
    - JstlView
    - RedirectView
    - SimpleUrlHandlerMapping
    - PropertiesMethodNameResolver
    - AbstractFormController
    - SimpleFormController
    - ServletRequestDataBinder
    - ModelAndView
    - MultiActionController

JDBC support
    - MappingSqlQuery
    - SqlParameter
    - SqlUpdate
    - DriverManagerDataSource
    - AbstractDataFieldMaxValueIncrementer
    - HsqlMaxValueIncrementer
    - MySQLMaxValueIncrementer

JNDI support
    - JndiObjectFactoryBean

Business Classes
================
petclinic.Clinic (interface) - The high-level business interface API
petclinic.ClinicImpl - The default implementation of Clinic.
                       Provides caches of all specialties, all vets, all pet types,
                       as well as owners and their pets and visits that have been found.
JavaBeans:
    petclinic.Entity (simple JavaBean superclass of all database related Javabeans)
    petclinic.NamedEntity (adds name property to Entity, used to provide specialties and pet types)
    petclinic.Person (superclass of Vet and Owner)
    petclinic.Vet (holds List of specialties)
    petclinic.Owner (holds List of pets)
    petclinic.Pet (holds List of visits)
    petclinic.Visit
Exceptions:
    petclinic.NoSuchIDException (unchecked)
Validators:
    petclinic.validation.FindOwnerValidator
    petclinic.validation.OwnerValidator
    petclinic.validation.PetValidator
    petclinic.validation.VisitValidator

Persistence Classes
===================
petclinic.ClinicDAO (interface) - The high-level persistence interface API
petclinic.ClinicJdbcDAO - The default implementation of ClinicDAO.
                          Provides inner class Data Access Objects that implement
                          8 types of Queries, 3 types of Inserts, and 2 types of Updates.

NOTE: The business and persistence classes are COMPLETELY independent of the presentation layer.

Presentation (web application) Classes
======================================
petclinic.web.ClinicController - subclass of MultiactionController to handle simple display oriented URL's
petclinic.web.AbstractSearchFormController - subclass of SimpleFormController adds the notion of a search form via an abstract search method,
        OnSubmit triggers display of 1 of 3 views :
            formView : if no items found
            selectView : if multiple items found
            successView : if a single item found
petclinic.web.FindOwnerForm - subclass of petclinic.web.AbstractSearchFormController which implements the search method
petclinic.web.AbstractClinicForm - subclass of SimpleFormController that is the superclass of the Add and Edit forms
petclinic.web.AddOwnerForm - used to add a new Owner
petclinic.web.EditOwnerForm - used to edit an existing Owner
petclinic.web.AddPetForm - used to add a new Pet
petclinic.web.EditPetForm - used to edit an existing Pet
petclinic.web.AddVisitForm - adds a new Visit
petclinic.WebUtils - provides static utility methods

Test Classes
============
petclinic.ClinicImplTest - a simple and incomplete JUnit test class for ClinicImpl

Views & Implemented Use Cases
=============================
welcomeView - home screen provides links to display vets list, find an owner, or view documentation
vetsView - displays all vets and their specialties
findOwnersForm - allows user to search for owners by last name
findOwnersRedirectView - redirects to findOwnerForm
selectOwnerView - allows user to select from multiple owners with the same last name
ownerView - displays a user's data and a list of the owner's pets and their data
ownerRedirect - redirects to ownerView
ownerForm - allows adding/editing an owner
petForm - allows adding/editing a pet
visitForm - allows adding a visit

NOTE: All views are implemented using JSP & JSTL

JSP Pages
=========
NOTES: all JSP's are stored under /WEB-INF/jsp except for index.jsp which is the configured "welcome-file".
The use of JSP technology in the appplication is not exposed to the user.
All pages are simple implementations focusing only on functionality.

index.jsp - redirects to the welcome page.
includes.jsp - statically included in all JSP's, sets session="false" and specifies the taglibs in use.
uncaughtException.jsp - the configured "error-page" displays a stack trace.
welcome.jsp - displays links to search for an owner or display the vets page.
vets.jsp - displays a list of vets and their specialties.
findOwners.jsp - displays a form allowing the user to search for an owner by Last Name.
owners.jsp - displays a list of owners meeting the search criteria with a selection button for each owner.
owner.jsp - displays an owner and the pets owned along with the visit history.
ownerForm.jsp - displays a form that allows adding or editing an owner.
petForm.jsp - displays a form that allows adding or editing a pet.
visitForm.jsp - displays a form that allows adding a visit.

The following JSP's each display a form field and the bound error data for that field.
    address.jsp
    city.jsp
    telephone.jsp
    lastname.jsp
    firstname.jsp

The following JSTL tags are used:
    c:out
    c:redirect
    c:url
    c:forEach
    c:if
    fmt:message
    fmt:formatDate

NOTE: I welcome ANY comments, criticisms, or suggestions. The application is intentionally
incomplete but if you have suggestions for additions that provide useful, additional tutorial
value, I would be glad to hear them. Version 1 of the tutorial is intended to provide an
introduction to the core functionality of Spring, not its more advanced features.

Ken Krebs
kk...@kk...

Thread: [Springframework-developer] NEW Petclinic version

springframework-developer