Development practices and guidelines for Simple Cart
Copyright (c) 2005, Daniel Watrous All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Simple Cart nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Abstract
The purpose of this Cookbook is to help in coordinating and documenting the development of Simple Cart.
Table of Contents
- 1. Change Log
- 1. Introduction
- 2. Download and Build from Source
- 3. Simple Cart Design: Overview
- 4. Model Design
- 5. View Design
- 6. Controller Design
- 7. Testing Procedures
- 8. Extending Simple Cart
- 9. Issue Management
- A. Tools needed to develop with Simple Cart
Table 1. Changes done
| When | What | Who |
|---|---|---|
| 2006-09-06 | Update ALL URLs to new Subversion repository and forum as hosted at SourceForge. | Daniel Watrous |
| 2006-02-22 | Update ALL URLs to correct Subversion repository. | Daniel Watrous |
| 2006-01-03 | Add in additional chapter place holders. Update URL to Subversion repository. | Daniel Watrous |
| 2005-04-01 | Complete first draft of Chapter Two, Build from source. | Daniel Watrous |
| 2005-03-30 | Introduce Cookbook | Daniel Watrous |
Simple Cart is a shopcart application written in Java(TM) and implemented using various popular open source tools, viz. Hibernate (http://www.hibernate.org) and Struts (http://struts.apache.org). Simple Cart aims to be simple to use and maintain while providing a robust platform on which to build an enterprise level shopcart solution.
Simple Cart is an open source project, and so it depends on volunteers. This includes people that want to help develop it and people that want to use it to work on it. This Cookbook is designed to help interested developers quickly get up to speed with the Simple Cart software. Please feel free to visit the forum with questions and/or answers Simple Cart forum! If you are interested in using simplecart for your own site look here [TODO] for documentation.
Simple Cart is growing and provides many opportunities for involvement. The following list includes some of the ways in which you can get involved. Keep in mind that this list is not ordered and so you may choose to help in one area and not another.
Download and use Simple Cart
Report Bugs and request Features and Enhancements
Subscribe to the forum and participate in the discussions there. Here you can ask questions and keep up to date with Simple Cart developments.
Get familiar with the source code. This will require understanding in Java and familiarity with Hibernate and Struts. If you have questions along the way you can find answers in the forums. A good place to start might be to fix issues and persuade a developer to commit them. With each useful patch the developer community will come to know you better, which is preparatory to becoming a developer.
Apply for a developer role in the project. This will enable you to commit your changes directly into the repository. The Lead Developer will be the one to decide who is granted a developer role.
Choose a particular area and make it shine. We recognize that each developer will have strengths. When you focus your strengths on one area and make that area perfect, the overall stability of the entire project improves.
The intended audience for this cookbook is the developer. Other people that may find useful information would be decision makers evaluating whether Simple Cart is the right fit for their organization.
Information about compiling Simple Cart
Information about how features are implemented and covers basic API related information.
Information that a developer needs to know in order to make contributions to the code and project.
Simple Cart offers a public forum to facilitate communication among developers. The forum can be found here. All developers MUST join the forum and stay up to date on the progress of Simple Cart.
For the impatient:
$ svn co https://svn.sourceforge.net/svnroot/simplecart/trunk . $ ant
That should get the source, compile it and package it into a WAR distribution file for deployment inside a servlet container. If that didn't work, or you're not sure what you just did then read on through the rest of this chapter.
Simple Cart is written in Java and so can compile with a standard JDK on any platform computer. The download will require around 30 Mb and another 30 Mb or so to compile. A standard computer (e.g. a Pentium III at 500Mhz or more) should be enough to do the job
Other tools required include the following:
- Java Development Kit (JDK), 1.4 or later.
- Apache Ant to run the automated build script which includes targets (or build files) for the main source tree, tests and documentation.
- A Subversion client. Subversion is a revision control system and is the tool used to maintain the source code for the Simple Cart project.
For additional information about the tools required and where to download them please see Appendix A, Tools needed to develop with Simple Cart
The libraries listed below are included in with the source code and must be available when deploying the software.
Hibernate is used for all database persistence within the Simple Cart application. Hibernate permits the use of Plain Old Java Objects in code without hard coding the details of database access and JDBC. Visit the Hibernate web site to learn more about this great technology!
Struts is a widely used Model View Controller (MVC) framework. This framework enables a clean separation between business functions and presentation which makes it straight forward to adapt Simple Cart to your company's particular style. More information about Struts can be found at their web site.
log4j is used for logging.
The subversion repository is hosted at https://svn.sourceforge.net/svnroot/simplecart/. Any subversion client will do, but the explanation below applies to the command line client. Anonymous checkout is allowed and requires no username or password.
The process of checking out the code is really quite simple. All you really need to do is issue a checkout command and provide the location of the repository. From the command line this looks as follows:
$ svn checkout https://svn.sourceforge.net/svnroot/simplecart/trunk simplecart
In the command issued above the dollar sign ($) represents your system prompt. The command svn calls the subversion executable and expects a <subcommand> to follow. The subcommand shown above is checkout and can also be issued using its aliases co. Then follows the URL indicating the location of the repository to checkout (more to come about the structure of the repository). Finally there is a simplecart, which in this case indicates that the contents should be placed inside a folder called simplecart relative to your current path. Note that if the folder simplecart doesn't exist then the above command will attempt to create it.
The process for checking out the source using another Subversion client is very similar. Just remember that the important part is the URL.
Simple Cart is designed to compile with ANT. This is important, since it means that the build will always happen in the same way and that all requirements are met. Additionally this enables the developer to frequently test his changes against existing Unit Tests to ensure that his changes don't break something else. If you choose to use the automated build tools included with your IDE, be sure that your code also compiles with the standard ANT build script.
At present Ant does not come bundled with Simple Cart. This means that you are responsible for downloading and installing Ant. Some IDEs (such as Eclipse) include ANT. The Tools Appendix contains information about where to find Ant and ant tutorials. Once this is complete you can use Ant to build Simple Cart
Ant uses XML to define build targets. A target represents a particular task that relates to the build and may include items such as gather pre-requisites, compile source code and package compiled code for deployment or execution. The XML file is traditionally called build.xml and in the case of Simple Cart is located in the root directory of the checkout. To run the script simply navigate to this directory and call the ant executable.
Identified in the build script (build.xml) is a default target. This
is the target that is called if you do not identify a particular
target. The default target for Simple Cart is the
dist target, which in turn calls other targets
to create build directories, compile source code, copy related files
and package a WAR file for deployment. You may call ant to run a
single target. For example, if you wanted to simply create the build
directories you could call ant init.
This will execute the init target in the build script.
The documentation for Simple Cart also uses an ant script. The default target for building the documentation is defaulthtml. This will generate multiple HTML pages for each of the different sets of documentation. If you are generating all documentation call Ant with the docs target. This will generate the defaulthtml as explained, but will additionally generate PDF and printablehtml output.
All documentation for Simple Cart was written in XML using the docbook DTD. The full documentation is included when you download the source code as outlined above. For more information about docbook visit their web site. Many tools and tutorials are available.
If for some reason the build process fails it might be easy to fix.
There is a possibility that another developer has introduced a bug or that he missed some files for a change he was committing. The first place to check will be the forum, since the discussion will likely occur there for the resolution.
After checking the forum issue the ant clean
command and update your checkout of the repository through
Subversion. Once you are confident that your source code
is up to date try the build again.
If you still can't get the code to compile post your errors to the forum. You'll be sure to find a solution there!
JUnit is a testing program which focuses on Java Units, which are in this case Java Classes. The test cases test the functionality of classes to ensure that for a given input the expected output is obtained. In the event that a change is made which affects the functional nature of a Class such that the desired output is no longer obtained, then the Unit Test will fail.
Unit tests are organized in the test folder, located at the same level as the src folder in the checkout. From there down the tests attempt to mirror the package structure of the classes that they will be used to test. When new tests are added they should be added according to this pattern; they should be added in a parallel folder of the test directory.
Since Simple Cart addresses several concerns through its various layers, these concerns should be tested separately. For more information about the layers that make up Simple Cart see ???. These concerns and their relation to tests are briefly discussed below.
Simple Cart is based on the Model View Controller (MVC) pattern and the Business Logic addresses the Model Component. Business Logic includes everything calculates, decides and is governed by business rules. Examples might be calculation of tax or shipping, rules defining how promotions are handled and how passwords are set, stored and reset.
Since Business Logic addresses business rules, the tests should be designed to prove that under all circumstances the business rules are enforced. In general all business objects will be written as interfaces, and the tests should be written to test the interface, not the particulars of the implementation. This way the test might be applied to future or alternative implementations with very little effort.
While persistence falls within its own layer, and is not mentioned in the MVC pattern, it is essential to the functionality of Simple Cart. Persistence concerns itself with the translation of an in memory object to a disk based representation. In some cases this may be Relational Database Management System (RDBMS), while in others it may be XML or some other data source.
Persistence related testing should ensure that a particular object in memory can be saved to a data source and later retrieved in the same state. Particular attention should be given to objects that represent monetary units (i.e. Dollars, Yen, Pounds, etc.), or monetary values. Where necessary tests should also ensure that all permitted characters are stored and retrieved correctly, such as may be related to internationalization.
Struts serves the role of Controller in the MVC pattern. As such Struts should never implement any Business Logic and should not contain any presentation specific code. The idea with the controller is to ensure the following: “
Receives the data it needs from the request or session
Handles cases properly where required input validation is missing or invalid
Calls the model passing the correct data
Marshals and transforms as needed the data from the model
Stores the data in the appropriate context or scope
Returns the correct action response
The project StrutsTestCase extends JUnit and provides mock objects that allow controllers to be tested outside a servlet container. The project is hosted at SourceForge and can be found here.
While unit tests are important, it is equally important to test the application in its end environment, the servlet container. These types of tests are often referred to as Integration Tests and are usually a manual process, whereas the Unit tests can be automated. Possible problems may include class loading issues, database connection pooling and management and file permissions.
The process of making a release includes testing to ensure that the project will compile and then creating a tag and branch in Subversion. Version numbers are explained as they pertain to Simple Cart. This section discusses the structure of the repository, the goals of a release and how to create the tag and branch.
From the root of the Simple Cart repository there are three principle folders, namely trunk, tags, and branches. The trunk contains the source code for the entire project, which includes web related files and configuration sources. The tags folder contains copies only, and the branches are considered active copies. By active copy it is meant that changes can be committed against the copy. Changes should never be committed against a tag, even though Subversion would permit it.
When a release is made there are two copies of the trunk made. One is a copy into the tags folder and represents a snapshot of exactly what the project looked like at the time of release. This copy is never modified. The next copy is into the branches folder. This copy into the branches folder is modified (committed against) only when bugs are found in the release. When the bug(s) have been fixed and tested another tag is made with a Release number incremented (version numbers are explained below).
Simple Cart follows a standard convention regarding its version number. Each version number has three (3) parts in the form x.y.z. The following table explains:
Table 2.1. Version Number Definition
| Version Number Position | Position Definition |
|---|---|
| x | This is a Major Version Number. It is expected that every release for this major version number will be backward compatible with every previous release under the same major version number. |
| y | This is the Minor Version Number. When this number is odd it indicates a development release and should probably not be used in a production environment. Even numbers represent stable releases and can be trusted for use in production. |
| z | This is a Release Version Number. Every time a formal release takes place, either in development or on a stable branch, this number is incremented. This number alone tells nothing about whether this release is table or not. |
A release should be triggered by a milestone. Milestones may relate to new features that have been requested, or they may be in response to a bug. In either case the use of issue tracking software will aid in determining what milestones are of importance, and when those milestones are released.
All Automated tests should be run successfully before preparing a release. If in the process of making a release it is found that a test fails, the process should be stopped and the problem addressed. Once all tests are running successfully the release can be made.
Every branch and tag name should not the version number. The format for the name is as follows: BRANCH_X_Y_Z_YYYY_MM_DD. In this format the X, Y and Z correspond to the x, y and z in the version number respectively, as explained in the previous section. The underscores are literal. YYYY indicates a four number year (e.g. 2005), with MM and DD indicating the two digit month and day respectively.
![[Note]](images/note.png) | Note |
|---|---|
| Branches should only ever have a value of zero for Z in the above format. This is a consequence that a branch is only made for stable (even minor number) release. Tags may, however, have a non zero value for Z. |
A tag name is derived in the same manner except that the literal occurrence of BRANCH is replaced with TAG as in the following example: TAG_X_Y_Z_YYYY_MM_DD.
Every Even numbered minor release (this corresponds to the y in x.y.z) requires a branch. The purpose of a branch is to move work and commits away from the main development trunk. This is important for two reasons. First, this ensures that no new development will affect the released branch, thus introducing new bugs in an official release. Second it facilitates the process of applying fixes to software that may be in production use, so that only the affected code will be updated with the fix.
Branches are not required for releases with a minor odd numbered. This is due to the fact that no one should be using the release in production and so all changes and bug fixes should be included in the trunk.
To create a branch do the following:
Checkout a clean copy of the source code and run all tests. No commits against the trunk should be permitted during the process of making a branch.
From within the checked out code use the copy command as follows:
svn copy trunk branches/new-branch-name.The copy must now be committed as follows:
svn commit -m "Notes about new branch"
The same copy can be accomplished with a single command as below:
svn copy https://svn.sourceforge.net/svnroot/simplecart/trunk \
https://svn.sourceforge.net/svnroot/simplecart/branches/new-branch-name \
-m "Notes about new branch"
Which method you choose is a matter of preference.
| Note |
|---|---|
| The second method requires no commit and is final once it is issued. If you plan to review the copy before committing use the first method instead. |
Every release, both for Major and Minor versions, both Odd and Even, should be tagged. Since a tag is never changed these become very useful snapshots of the state of code at a particular point in time and help in debugging. The process for creating a tag is the same as creating a branch.
To create a tag do the following:
Checkout a clean copy of the source code and run all tests. No commits against the trunk should be permitted during the process of making a tag.
From within the checked out code use the copy command as follows:
svn copy trunk branches/new-tag-name.The copy must now be committed as follows:
svn commit -m "Notes about new tag"
The same copy can be accomplished with a single command as below:
svn copy https://svn.sourceforge.net/svnroot/simplecart/trunk \
https://svn.sourceforge.net/svnroot/simplecart/branches/new-tag-name \
-m "Notes about new tag"
Which method you choose is a matter of preference.
| Note |
|---|---|
| The second method requires no commit and is final once it is issued. If you plan to review the copy before committing use the first method instead. |
Tags are intended to be a snapshot of exactly what the code looked like a a given point in time. A tag cannot accept commits (or at least it should not), while a branch can. For this reason, each release with an even minor number which is intended for production use should be placed in a branch that can accept bug fix commits. This will ensure that no new changes creep in from new development.
Various tools are required before you can begin developing with Simple Cart. This appendix provides basic information about these tools and links to helpful sites if further information is required.
Subversion is a revision control system, much like CVS. The source code for Simple Cart is maintained in a Subversion code repository from which many developers can checkout the entire code base. This one repository enables concurrent contributions from as many developers as are granted the developer role
Various clients are available to facilitate communication with Subversion, including a full command line client. Others include TortoiseSVN which integrates directly with Windows(TM) Explorer and is IDE independent. RapidSVN is another GUI that is cross platform and provides the entire user interface needed for file management and diffs.
Other clients can be full documentation can be found at the Subversion web site along with free downloads.
“ Apache Ant is a Java-based build tool. In theory, it is kind of like Make, but without Make's wrinkles. ”
Ant is used in Simple Cart to automate the build process, automate testing and generate documentation. Each of these targets ensures that the each build of the software functions properly and that building is consistent.