Perequisite software

1. The Upgrader is a Java application. You will need to install JRE 1.5, JDK 1.5 or higher. Please download and install the software from http://www.java.com as per the instructions provide in the web site. Note that you may need to bundle the JRE with your application if your application does not use Java.
2. By default, the Upgrader uses a database to persist patch information. If your application does not use a database, you have two options: (a) extend the tool to use a custom patch engine (see Extending the Upgrader tool for details), (b) bundle a small embedded database like HSQLDB.

Download and installation

1. Download the latest stable version of the Upgrader from here . The binary version of the software is packaged as a zip archive.
2. Using a zip tool, unpack the distribution. All modern operating systems already provides tool for extracting a zip archive. You can also use the jar tool provided by the JDK for this as well as other commercial tools. When unpacked, a directory called the "upgrade-tool" will be created which contains the content of the binary distribution.
3. Copy the jar files in the distributions as per instructions given below.

Setting up the project during the development phase

To use the tool, you will need to add to your existing software/installation project that you may be using for your application.

1. Copy one or more of the jar files from the distribution that you extracted into your project. At a minimum, you will need the jar - upgrade-tool-X.X>X.jar. If you are using MySQL for you application and if your application does not include a JDBC driver, you can copy the bundled mysql-connector-X.X.X.jar to your project. If your application uses some other database, make sure that the JDBC driver is included in your project. if you envision that the patch scripts your developers are going to create uses Ant, you can copy the ant jar files bundled with the distribution. To run the tool, you will need all of these jars including the JDBC jars in your classpath.
2. You may optionally need additional jars that the upgrade scripts may require. For example, if your upgrade scripts need a Python interpreter, you may have to add the jython.jar and other associated jars. Also, note that the ant jars we have bundled only contains the core Ant tasks. So, if you are using optional tasks (example svn tasks), you will need to include them as well.
3. Finally, create a directory under your project called "upgrades" or you can call it anything else you like. Add a file called "migration.properties" to this directory. The distribution includes a sample_migration.properties file. You can copy it and rename the file if you like. Edit the file to specify the database connection properties that the Upgrader is going to use to persist patch information. As you can see the property values are coded as per the JDBC conventions. You can override the properties specified in this file using properties as discussed below.
4. Ask the developers to create patches in the "upgrades" directory and add them to the code repository whenever a developer determines that a patch script is needed. The patch scripts file names must follow the convention explained below.

Patch file naming convention

As explained above patch files must be named using a naming convention and placed in the patch directory. If proper naming convention is not followed, the Upgrader may not install a patch script, or worse, try to run them in wrong order causing upgrade failures.

Each patch file must be name as follows:

patchXXX_anything_you_like.extension
where:
XXX is a numeric patch number. The tool sequences the patches based on this number. So, it is important that developers get the number right. Note that there may be gaps between the numbers.
After the underscore (_) following the patch number and before the extension, you can add text you like. For example, you may add a release number.
The extensions supported out of the box are: ant and sql indicating the type of the script. Note that it is possible for an application to add other types of scripts as well. See Extending the Upgrader tool for details.

Here are some examples of patch file names:

• patch00001_r1.0.0_20091011.sql
• patch20009_r10.2.1_20450101.ant

Packaging the Upgrader and the patches

1. Bundle the "upgrades" directory and all the jars described in the above section during packaging of the application.
2. If you are using an installer like RPM or InstallAnywhere, program the installer configuration to invoke the Upgrader during the post-installation phase. Alternatively, document the information for the Upgrader to be invoked manually as explained in the next section.

Running the Upgrader during install/upgrade

The Upgrader tool can be invoked in three ways:

1. From the DOS or Unix/Linux command line: The syntax is:

   > java -cp $CLASSPATH org.cafesip.upgrade.Upgrader $PATCHDIR
   Replace $CLASSPATH with the classpath in Java format. The classpath must contain all the jar files that the Upgrader needs as discussed in the previous sections. Replace the $PATCHDIR with the full path name of the directory where the patch files and the migration.properties file is located. Note that the java executable must be present in the PATH environment variable.

2. From a Java program:

   import org.cafesip.upgrade.Upgrader;
   ...
   String propertyFile = "/full/pathname/of/the/migration.properties";
   String patchDir = "/full/pathname/of/the/patch/dir";
   Upgrader upgrader = new Upgrader(propertyFile, patchDir);
   upgrader.upgrade(); // throws exception on errors

3. From an Ant script:

   <path id="upgrader.classpath">
   < !-- Add the classpath you need -->
   < /path>
   < taskdef name="upgrader" classname="org.cafesip.upgrade.UpgraderTask" classpathref="upgrader.classpath" />
   <upgrader patchDir="DIRNAME" />