Using ANT for Upgrades

After installing Application Designer, the web application "cis" will be available inside a servlet engine. The servlet engine either comes with the Application Designer installation (when using the installation wizard) or is your own servlet engine (when using the .war distribution).

When starting to develop with Application Designer, we recommend the following procedure:

Make a copy of the standard "cis" web application into a new, parallel running web application. You can use a name of your choice; in this document we will use the name "ciscopy".
Use the "cis" web application as an "untouched" Application Designer reference and make all of your development inside "ciscopy".

Reason: when installing new or patched versions of Application Designer, you are sure that changes will not immediately have an effect on your web application. There is one buffer between what comes from Software AG and your development.

The take over from the reference "cis" web application to your copy "ciscopy" should be automated in order to reduce the effort when applying new Application Designer versions. We recommend to do this automation using an ANT script definition.

This document gives an example of an ANT script definition. The ANT script can be used for both the first, initial copying from the reference and for continuous copying from the reference.

You are not yet familiar with ANT? No problem - just download ANT from http://ant.apache.org/, extract it into a directory of your choice, that's it.

This document covers the following topics:

ANT File for Take Over
Step by Step
Running the ANT Script

ANT File for Take Over

Let us have a look at the XML file that defines the ANT job:

<?xml version="1.0"?>
<project name="Copy Into Parallel Project" default="generatehtml">

      <description>Copy Default Application Designer Environment (cis) to an existing Web Project (ciscopy)</description>

    <!--
        The following three properties need to be updated according to your
        situation.
    -->
    <property name="from.dir" value="C:/TEMP/lllll/tomcat/webapps/cis"/> 
    <property name="to.dir" value="C:/TEMP/lllll/tomcat/webapps/ciscopy"/>
    <property name="project" value="yourproject"/>
    
    <path id="generate.classpath">
        <pathelement location="${to.dir}/WEB-INF/lib/cis.jar"/>
    </path>
    
      
    <target name="copyfiles" description="Copy Files">
        
        <!-- Copy cis configuration directory-->
        <copy file="${to.dir}/cis/config/cisconfig.xml" 
              tofile="${to.dir}/cis/config/cisconfig_customer.xml" failonerror="false"/>
        <copy file="${to.dir}/cis/config/startapps.xml" 
              tofile="${to.dir}/cis/config/startapps_customer.xml" failonerror="false"/>
        <copy file="${to.dir}/cis/config/controllibraries.xml" 
              tofile="${to.dir}/cis/config/controllibraries_customer.xml" failonerror="false"/>
        <copy file="${to.dir}/cis/config/editortemplates.xml" 
              tofile="${to.dir}/cis/config/editortemplates_customer.xml" failonerror="false"/>
        <copy file="${to.dir}/cis/config/adapterTemplate.java" 
              tofile="${to.dir}/cis/config/adapterTemplate_customer.java" failonerror="false"/>
        <copy file="${to.dir}/cis/config/adapterTemplate.java" 
              tofile="${to.dir}/cis/config/adapterTemplate_customer.java" failonerror="false"/>
        <copy file="${to.dir}/cis/config/fopClassTemplate.java" 
              tofile="${to.dir}/cis/config/fopClassTemplate_customer.java" failonerror="false"/>
    
        <copy todir="${to.dir}/cis">
            <fileset dir="${from.dir}/cis">
            </fileset>
        </copy>
        
        <copy file="${from.dir}/cis/config/cisconfig.xml" 
              tofile="${to.dir}/cis/config/cisconfig_sagreference.xml"/>
        <copy file="${from.dir}/cis/config/startapps.xml" 
              tofile="${to.dir}/cis/config/startapps_sagreference.xml"/>
        <copy file="${from.dir}/cis/config/controllibraries.xml" 
              tofile="${to.dir}/cis/config/controllibraries_sagreference.xml"/>
        <copy file="${from.dir}/cis/config/editortemplates.xml" 
              tofile="${to.dir}/cis/config/editortemplates_sagreference.xml"/>
        <copy file="${from.dir}/cis/config/adapterTemplate.java" 
              tofile="${to.dir}/cis/config/adapterTemplate_sagreference.java"/>
        <copy file="${from.dir}/cis/config/fopClassTemplate.java" 
              tofile="${to.dir}/cis/config/fopClassTemplate_sagreference.java"/>
        
        <copy file="${to.dir}/cis/config/cisconfig_customer.xml" 
              tofile="${to.dir}/cis/config/cisconfig.xml" failonerror="false"/>
        <copy file="${to.dir}/cis/config/startapps_customer.xml" 
              tofile="${to.dir}/cis/config/startapps.xml" failonerror="false"/>
        <copy file="${to.dir}/cis/config/controllibraries_customer.xml" 
              tofile="${to.dir}/cis/config/controllibraries.xml" failonerror="false"/>
        <copy file="${to.dir}/cis/config/editortemplates_customer.xml" 
              tofile="${to.dir}/cis/config/editortemplates.xml" failonerror="false"/>
        <copy file="${to.dir}/cis/config/adapterTemplate_customer.java" 
              tofile="${to.dir}/cis/config/adapterTemplate.java" failonerror="false"/>
        <copy file="${to.dir}/cis/config/fopClassTemplate_customer.java" 
              tofile="${to.dir}/cis/config/fopClassTemplate.java" failonerror="false"/>
        
        <delete file="${to.dir}/cis/config/cisconfig_customer.xml"/>
        <delete file="${to.dir}/cis/config/startapps_customer.xml"/>
        <delete file="${to.dir}/cis/config/controllibraries_customer.xml"/>
        <delete file="${to.dir}/cis/config/editortemplates_customer.xml"/>
        <delete file="${to.dir}/cis/config/adapterTemplate_customer.java"/>
        <delete file="${to.dir}/cis/config/fopClassTemplate_customer.java"/>
        
        <!-- Copy HTMLBasedGUI directory -->
        <copy todir="${to.dir}/HTMLBasedGUI">
            <fileset dir="${from.dir}/HTMLBasedGUI">
            </fileset>
        </copy>
        
        <!-- Copy WEB-INF directory -->
        <copy file="${to.dir}/WEB-INF/web.xml" 
              tofile="${to.dir}/WEB-INF/web_customer.xml" failonerror="false"/>
        <copy todir="${to.dir}/WEB-INF">
            <fileset dir="${from.dir}/WEB-INF">
            </fileset>
        </copy>
        <copy file="${from.dir}/WEB-INF/web.xml" 
              tofile="${to.dir}/WEB-INF/web_sagreference.xml"/>
        <copy file="${to.dir}/WEB-INF/web_customer.xml" 
              tofile="${to.dir}/WEB-INF/web.xml" failonerror="false"/>
        <delete file="${to.dir}/WEB-INF/web_customer.xml"/>
        
        <!-- Copy all Application Designer demo projects that should be available in the copy -->
        <!--
          <copy todir="${to.dir}/cisdemos"><fileset dir="${from.dir}/cisdemos"/></copy>
          -->
        
    </target>    
    
    <!-- Regenerate HTML files in core projects -->
    <target name="generatehtml" depends="copyfiles" description="Regenerate HTML files of project">
        <mkdir dir="${to.dir}/${project}/log"/>
        <java classname="com.softwareag.cis.gui.generate.HTMLGeneratorWholeDirectory" 
              classpathref="generate.classpath">
            <sysproperty key="cis.home" value="${to.dir}/"/>
            <arg value="${to.dir}/${project}/xml"/>
            <arg value="${to.dir}/${project}"/>
            <arg value="${to.dir}/${project}/log"/>
            <arg value="${to.dir}/${project}/accesspath"/>
        </java>
    </target>
    
    
</project>

Step by Step

The ANT file contains three major sections:

Declaration of properties.
Target name "copyfiles" - the copying from this "cis" reference into the "ciscopy" copy is defined in this section.
Target name "generatehtml" - the regeneration of XML layouts into HTML files is defined in this section.

Declaration of Properties

There are three properties:

The name of the directory of the "cis" reference web application.
The name of the directory of the "ciscopy" web application.
The name of your application project within the "ciscopy" web application.

Define the properties according to your configuration.

Target Name "copyfiles"

The copying is done in three steps:

Copying the directory cis.
Copying the directory HTMLBasedGUI.
Copying the directory WEB-INF.

For certain files that you may have changed during development (for example, cis/cisconfig.xml), the ANT file will create corresponding copies of the original files coming from Software AG - and will leave your version untouched.

Only the core directories of your "cis" reference will be copied. The demo application will not be copied (directory cisdemos). In the ANT script, you see a commented section that you can uncomment in order to also copy this directory.

Target Name "generatehtml"

In this step, the XML files of your project will be regenerated.

Caution:
If you have created your own controls - with your own control classes (ITagHandler, IMacroTagHandler implementations) - you have to adapt the classpath that is used for generation to also contain your control handler classes.

Running the ANT Script

The following batch file for Windows shows how to start the ANT script, assuming the name of the file is copy_reference.xml:

set JAVA_HOME=C:\Java\jdk142
C:\ ant\bin\ant.bat -buildfile copy_reference.xml

Adapt the file to your directory configuration.