PTAGIS Web-App Build Process Using Ant and Subversion Version 1.3, 29 Aug 2005 Doug Clough, SYNERGETICS We have a lot of great open-source tools at our disposal. Many of them come with good tutorials and usage examples. This document pulls together ideas from Ant and Subversion (abbreviated SVN) on-line documentation, the O’Reilly book on Ant, Pragmatic Version Control Using Subversion, the SpringFramework MVC Step-By-Step tutorial by Thomas Risberg, and the on-line manual for Log4J. The objective is to establish a practical, standardized approach to web-application development and deployment that incorporates recommended practices of the Extreme Programming community - e.g. Java Tools for Extreme Programming, Wiley, 2004 - while addressing specific features of the PTAGIS environment. But before diving in, a few words about the tools: SpringFramework – General purpose Java application development framework – Compared to Struts, SpringMVC substantially simplifies the development of Java-based web applications. Using the process described herein, applications constructed with SpringMVC and incorporating Log4j will be configured and provisioned by Ant, archived in SVN, tested with JUnit, and packaged by Ant as war-files for deployment to WORKstation, BETA-test, and PRODuction environments. SVN – ‘Subversion’ Version Control System – Files imported into an SVN repository may be checked out and edited concurrently by any number of remote users. When users commit their work, SVN inspects the changes and notifies users of any conflicts it has detected. According to the Subversion web-site: “The goal of the Subversion project is to build a version control system that is a compelling replacement for CVS in the open source community.” As this document is being written, we’re experimenting with SVN as an alternative to CVS. SVN offers some significant advantages over CVS – for example, truly atomic ‘commits’. The build process described herein will be pretty much the same whichever version control system is adopted. If you happen to spot a left-over ‘CVS’ in any of the slides, mentally replace it with ‘SVN’. Ant – “Another Neat Tool” – Flexible Java program, driven by an XML configuration file, performing the full range of operations required to build and deploy Java applications. Fulfills the same role as “make”, but is much more intuitive and easier to use. Log4j – “Logging Utility For Java” – Modular, configurable logging utility for incorporation into Java programs. Logging verbosity can be adjusted by editing a configuration file, without re-compiling the code. JUnit – “Java Unit Test Utility” – Framework for easy development of unit tests. Although not covered in this document, JUnit is an integral part of the PTAGIS Web-App Build Process (and will be covered in another document). 1 Challenges Tackled by Automated Build Process sebastes Multiple concurrent Multiple deployment blueback developers environments - Third-party ‘jar’ files pitblade - Re-usable locally-developed classes sockeye - Avoid conflicts with other web-apps What features of the PTAGIS environment need to be addressed? How can Ant and SVN help? SVN provides the means for reconciling the work of multiple concurrent developers. Before “development” work on a new project begins, Ant enables automated creation of the project directory tree, and ‘provisioning’ the application with required third-party jar-files. At build-time, Ant can automatically tailor the build process to the deployment environment; for example, setting log-file path names, JDBC connection parameters, and other things that vary between a developer’s workstation, the beta- test environment on ‘pitblade’, and the production environment on ‘sebastes’. Much of what follows is a detailed examination of the means by which this customization will be achieved for PTAGIS web applications. 2 New Project Setup • Automatically create project directory tree • Establish properties that vary by environment • Provide copies of required 3rd-party JAR-files • Import project into SVN • Check project out of SVN, build, and deploy to verify setup Let’s walk through the process, as if we were setting up a new project. The first step is to create a scratch directory to contain temporary copies of the various files and sub-directories required by a typical SpringMVC web application. The scratch directory and its content will be deleted as soon as the new project has been imported to the SVN repository. NOTE: Not all of this has been implemented yet – I’m “thinking out loud” here … As ‘ptagdev’ on ‘sockeye’ … > web_proj_temp Å Unix ‘alias’ that cd’s to appropriate directory > UTIL_ProjSetup.pl Å Runs Ant using specially constructed build.xml, to create the directory tree shown in the next slide 3 Automatically Create Project Directory Tree What are these? In addition to creating the directory tree in our temporary work area, Ant copies basic versions of files required by SpringMVC web-apps into the war/WEB-INF directory It also populates the top-level directory with build.xml Parameterized Ant build script for the new project build.template Generic template for creating build.properties; contains placeholder “tokens” for parameter values that vary by environment log4j.template Generic template for creating log4j.properties; contains placeholder “tokens” for parameter values that vary by environment Examples of these files are shown in the following slides. Don’t worry about every detail – just note the tokens – e.g. @JDBC_URL@ – in the template files. These are the values that must be set differently, depending on where the app is to be deployed. Appropriate values for BETA-test (‘pitblade’) and PRODuction (‘sebastes’) and the mechanism for replacing the tokens with suitable values are detailed in later slides. 4 build.template Æ build.properties # # Source : Generic build.template file with replaceable tokens. # For Deployment To: @DEPLOYMENT@ environment # # These are the same for all environments ... lib.root=/home/ptagdev/ptagis3/java_lib lib.spring=spring-framework-1.2.2 lib.db=ca_jdbc_type_2 lib.log4j=log4j-1.2.9 lib.commons-logging=commons-logging-1.0.4 lib.tags_jstl=jstl-1.0.3 lib.tags_standard=jstl-1.0.6 lib.servlet=servlet-2.4/weblogic-8.1 db.driver=ca.edbc.jdbc.EdbcDriver # These differ between deployment environments ... db.url=@JDBC_URL@ db.user=@JDBC_USER@ db.pw=@JDBC_PW@ Here’s the template that produces the build.properties file used by Ant. 5 log4j.template Æ log4j.properties # # Source : Generic log4j.template file with replaceable tokens. # For Deployment To: @DEPLOYMENT@ environment # # This establishes the logging level and varies by deployment environment ... log4j.rootLogger=@ROOT_LOGGER@ log4j.appender.stdout=org.apache.log4j.ConsoleAppender log4j.appender.stdout.layout=org.apache.log4j.PatternLayout log4j.appender.stdout.layout.ConversionPattern=%d %p [%c] - <%m>%n log4j.appender.logfile=org.apache.log4j.RollingFileAppender log4j.appender.logfile.MaxFileSize=512KB # This establishes the log-file location and varies by deployment environment ... log4j.appender.logfile.File=@LOG4J_LOG_PATH@ # Keep three backup files. log4j.appender.logfile.MaxBackupIndex=3 # Pattern to output: date priority [category] - message log4j.appender.logfile.layout=org.apache.log4j.PatternLayout log4j.appender.logfile.layout.ConversionPattern=%d %p [%c] - %m%n This template produces the Log4j.properties file, that controls logging behavior of the deployed application. 6 New Project Setup • Automatically create project directory tree • Establish properties that vary by environment • Provide copies of required 3rd-party JAR-files • Import project into SVN • Check project out of SVN, build, and deploy to verify setup Now that we’ve had a look at the template files and their replaceable tokens, let’s see where the corresponding values are established. 7 Establish Properties That Vary by Environment Manually edit template.properties files Created by developer (later on) to suit workstation environment Created at project initiation to suit PRODuction and BETA-test environments As shown in this slide, Ant has created BETA and PROD directories in the project directory tree. These are used to store files that pertain specifically to the BETA-test and PRODuction environments. At the time of initial project setup, each of these directories contains one file – template.properties – defining environment-specific replacement values for the tokens mentioned in the previous slides. Initial versions of these files provided by the Ant procedure will probably be suitable for most projects. Once a project has been imported to SVN, changes to these files will be tracked along with everything else in the repository. Note, however, that the slide shows an additional copy of template.properties, in the top-level project directory. The purpose of this file is to establish values for use by a developer on an individual WORKstation. Its values will most probably differ from developer to developer. Accordingly, this file is not placed into the project directory during the initial setup procedure – neither is it registered with SVN when the project is imported into the repository. Further, developers must not add their individual template.properties files to the project’s SVN repository – since their individual changes would be incompatible – rather, they should archive the files locally by any convenient means. Typical WORKstation, BETA-test, and PRODuction versions of template.properties are shown in the next slide. 8 template.properties – For