The Spring Python PetClinic Application

Updated :
    23-OCT-2008 - Greg Turnquist, updated with new terminology
    30-APR-2008 - Greg Turnquist, updated for new site
    09-DEC-2006 - Greg Turnquist, adapted for Spring Python
    01-DEC-2004 - Ken Krebs
    16-AUG-2003 - Ken Krebs

Introduction

Spring Python is a collection of small, well-focused, loosely coupled Python 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 Python application frameworks can be used to build simple, but powerful database-oriented applications. It will demonstrate the use of Spring Python's core functionality:

• Object-based application configuration using Inversion-Of-Control (In java, these are called JavaBeans)

• Model-View-Controller web Presentation Layer

• Practical database access through MySQL

The Spring Python 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 :

• concise by handling a lot of the complex control flow that is needed to use certain Python API's, such as DB-2 API, remoting through PYRO

• flexible by simplifying the process of external application configuration through the use of Introspection and object creation. This allows the developer to achieve a clean separation of configuration data from application code. All application objects, including database connection factories, templates, and proxies are objects that can be configured externally.

• maintainable 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 Petclinic web application demonstrates "plugging in" to one popular Python web framework, CherryPy, while keeping the database layer and the model definitions neatly separated. This 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.

It is assumed that users of this tutorial will have a basic knowledge of object-oriented design, Python, and relational databases.

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.

PetClinic Sample Application Requirements

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:

Use Cases:

• View a list of veterinarians and their specialties

• View information pertaining to a pet owner

• Update the information pertaining to a pet owner

• Add a new pet owner to the system

• View information pertaining to a pet

• Update the information pertaining to a pet

• Add a new pet to the system

• View information pertaining to a pet's visitation history

• Add information pertaining to a visit to the pet's visitation history

Business Rules:

1. An owner may not have multiple pets with the same case-insensitive name.

PetClinic Sample Application Design & Implementation

Server Technology
The sample application is written using CherryPy as the web container. CherryPy applications are self-contained web servers utilizing Python's built in HTTPServer objects. CherryPy applications do not require a 3rd party web server, such as Apache or IIS. However, it is possible to configure the CherryPy web application to be fronted by a web server, and even spawned.
In order to run the application, you must install CherryPy. You can download the package from their web site and install it through the traditional Python mechanism.

If you are running Ubuntu/Linux, type: sudo apt-get install python-cherrypy

Database Technology
The sample application uses a relational database for data storage. To reset the database, it is probably easiest to just re-run the setup.py script.

• Support is provided for MySQL. Setup requires the user to provide the MySQL "root" password, in order to setup to the "springpython" user and "petclinic" database. You need to have MySQL python module installed.

  • If you are running Ubuntu/Linux, type: sudo apt-get install python-mysqldb

Development Environment
You need to either have Spring Python installed on your machine, which will put the libraries in your Python path, or you can download the software and manually configure your PYTHONPATH to see the folder containing "springpython".

NOTE: 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.

Download links for the various tools needed are provided in the Developer Instructions section.

PetClinic Database
The following is an overview of the database schema used in PetClinic. Detailed field descriptions can be found in the "initDB.txt" SQL script files in the database-specific "db" sub-directories. All "id" key fields are of type int.

TABLE: owners
    PRIMARY KEY id

TABLE: types
    PRIMARY KEY id

TABLE: pets
    PRIMARY KEY id
    FOREIGN KEY type_id references the types table id field
    FOREIGN KEY owner_id references the owners table id field

TABLE: vets
    PRIMARY KEY id

TABLE: specialties
    PRIMARY KEY id

TABLE: vet_specialties- a link table for vets and their specialties
    FOREIGN KEY vet_id references the vets table id field
    FOREIGN KEY specialty_id references the specialties table id field

TABLE: visits
    PRIMARY KEY id
    FOREIGN KEY pet_id references the pets table id field


Directory Structure

• petclinic – contains the setup.py script in order to configure things (NOT install the application)

  • cherrypy

    • html – static content, including this page

    • images – static content

  • db – contains DBMS-neutral scripts to populate the database used for the PetClinic application

    • mysql – MySQL scripts to initialize the database

PetClinic Application Design

Controller Layer

The Controller Layer consists of the APIs used to contain the business logic needed by the View layer. For the PetClinic sample application, this is principally database calls. These objects are defined in the controller.py module.

Since the Spring Python 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 COMPLETELY independent of the Presentation Layer.

The Persistence Layer currently only supports MySQL.

Model Layer

The Model Layer defines the entities returned from the database by the Controller layer. These objects are defined in the model.py module.

Presentation Layer

The Presentation Layer, or View is run on the CherryPy web application framework. The objects are defined in the view.py module. It contains several functions which are mapped to URLs by the framework. For each page, there is a defined function. Each of the functions is responsible for returning HTML content. To keep presentation information decoupled from controller logic, the

Launcher

A fourth module is the petclinic.py bootstrapping script. It is responsible for loading the Application Context, which wires all the objects together. It also launches the CherryPy web server, making it ready to serve content.

A Spring Python springpython.context.ApplicationContext object provides a map of user-defined objects. These objects constitute the View and Controller layers of PetClinic. The following objects are defined in the PetClinic applicationContext.xml file:

1. connectionFactory is a object that holds the connection information and the call to connect to the database. It is DBMS specific.

2. controller is a object that defines the implementation of the Clinic interface that provides the primary Business Layer API of the application.

3. view is a object that defines all the CherryPy exposed functions that end up getting mapped to URLs.

The Application Context file makes it very easy to decouple the controller layer from being DDMS-specific. In this case, the APIs fetching content are not aware (nor are they required to) that the database they are connecting to is MySQL.

Setup/Running

Assuming you already have the necessary python packages installed, go to the petclinic folder where the setup.py script is located.

bash$ python setup.py

You will be prompted for the MySQL “root” password (not your system's root password). This is so it can create the “petclinic” database, and create a springpython/springpython account in order to connect to it. It also builds a configuration file for CherryPy in order to serve static content, including this page.

Finally, run the application.

bash$ cd cherrypy

bash$ python petclinic.py

Now you should be able to navigate a browser to http://localhost:8001 and see the web application.