Red Hat Web Application Framework 6.1: WAF Developer Guide
PrevChapter 8. WAF Application Development TutorialNext

8.11. Creating Upgrade Scripts

Upgrading to new versions of WAF applications may require you to also migrate your data. WAF supports two complementary approaches to data migration: Java upgrade programs and SQL scripts.

Java upgrade programs have full access to the WAF and application APIs. These programs are typically used to do more complex migrations where executing business logic is required to correctly migrate existing data.

SQL upgrade scripts rely on SQL and the embedded database procedural language (e.g., PL/SQL) to migrate data. SQL scripts are typically used to change database schemas. They also may provide superior performance in migrating large amounts of data.

The purpose of this section is to assist you in creating and hooking up your Java upgrade script to take advantage of WAF APIs. The process for performing the actual application upgrade from the installation/administration side using the ccm upgrade tool is covered in the WAF Installation Guide.

Creating A ccm Tool Upgrade Script in Java

  1. Create arbitrary Java code that is accessible via a static main() method. 

    ## file called com/arsdigita/cms/AnUpgrade.java
  package com.arsdigita.cms;

  public class AnUpgrade {
      public static void main(String[] args) {
          System.out.println("Sample upgrade running");
      }
  }

  2. Create or edit the upgrade spec file at ${package_name}.upgrade on the classpath. The file described looks like this: 

    ## file called ccm-cms.upgrade
<upgrade>
  <version from="6.0" to="6.1">
    <script class="com.arsdigita.cms.RickshawPublishAPIUpgrade"/>
  </version>
  <version from="6.0" to="7.0">
    <script class="com.arsdigita.cms.AnUpgrade"/>
    <script sql="ccm-cms/upgrade/::database::-6.0-7.0.sql"/>
  </version>
</upgrade>

Creating a SQL Upgrade Script

  1. Create arbitrary SQL code to update the schema or data, and place the code in a file with the .sql suffix. Group all related functional changes in a single file and assign the file a descriptive functional name e.g., update-host-unique-index.sql.

  2. Update the appropriate parent upgrade script to reference the created SQL script. Parent scripts are stored in sql/ccm-core/upgrade. Each database has its own set of versioned upgrade scripts, e.g., oracle-se-6.0.1-6.1.0.sql.

For Java upgrade scripts, the class for the given version-version pair will be invoked (via its main() method) when the user runs, e.g., ccm upgrade ccm-cms --from-version 6.0 --to-version 7.0. For SQL scripts, the given SQL file will be loaded as a resource from the classpath and run. The "::database::" placeholder will be substituted with a short string identifying the current database, oracle-se or postgres, before the resource is loaded.

NoteNote
 

Only exact matches on both the from and the to versions will trigger script execution.

>
PrevHomeNext
Integrating Your Package With CCM ToolsUpPersistence Tutorial