Visual Age for Java Tasks and Plugin User Manual

• Wolf Siberski ( wolf.siberski@tui.de )
• Christoph Wilhelms ( christoph.wilhelms@tui.de)

Table of Contents

• Introduction
• The Tasks
  • VAJLoad
  • VAJExport
  • VAJImport
• A sample build file
  
• The Plugin
  • Installation
  • Usage
• Frequently Asked Questions
• Visual Age Versions
• History

Introduction

The Tasks

VAJLoad

Description:

Loads a specified VAJ project version into the workspace.

Parameters

none

Parameters specified as nested elements

vajproject

Example

<vajload>
    <vajproject name="My Testcases" version="1.7beta" />
    <vajproject name="JUnit" version="3.2" />
</vajload>

VAJExport

Description:

Exports Java source files, class files and/or resources from the workspace to the file system. Exports can be specified by giving the VAJ project name and package name(s). This works very similar to FileSets.

Parameters

Parameters specified as nested elements

include

exclude

Example

<vajexport destdir="${src.dir}" exportResources="no">
    <include name="MyProject/**"/>
    <exclude name="MyProject/test/**"/>
</vajexport>

Default Excludes

	IBM*/**
	Java class libraries/**
	Sun class libraries*/**
	JSP Page Compile Generated Code/**
	VisualAge*/** 

VAJImport

Description:

Imports Java source files, class files and/or resources from the file system into VAJ. These imports can be specified with a fileset.

Parameters

Parameters specified as nested elements

fileset

Example

<vajimport project="Test" importClasses="true">
    <fileset dir="${import.dir}">
        <include name="com/sample/**/*.class"/>
        <exclude name="com/sample/test/**"/>
    </fileset>
</vajimport>

A sample build file

<?xml version="1.0"?>
<!-- ======================================================================= -->
<!-- Builds a binary distribution of the VAJ Ant Plugin                      -->
<!-- ======================================================================= -->
<project name="anttool" default="buildall" basedir="c:\temp\anttool">

  <property name="src.dir" value="${basedir}/src"/>
  <property name="zip.dir" value="${basedir}/dist"/>
  <property name="build.classes" value="${basedir}/classes"/>

  <!-- location of the unzipped Ant source distribution  -->
  <property name="antdistribution.dir" value="u:\ant-1.3beta1"/>

  <!-- VAJ install dir -->
  <property name="vaj.dir" value="C:\IBMVJava2"/>

  <path id="classpath">
      <pathelement location="${src.dir}"/>
      <pathelement location="${vaj.dir}\IDE\project_resources\IBM IDE Utility class libraries" />
      <pathelement location="${build.classes}"/>
  </path>


  <!-- =================================================================== -->
  <!-- Load Projects into Workspace                                        -->
  <!-- =================================================================== -->
  <target name="load" description="load projects">
    <vajload>
      <project name="Ant" version="1.3"/>
      <project name="Apache Oro RegExp" version="2.0.1"/>
    </vajload>
  </target>


  <!-- =================================================================== -->
  <!-- Creates the build dirs                                              -->
  <!-- =================================================================== -->
  <target name="preparedirs">
    <mkdir dir="${basedir}"/>
    <mkdir dir="${src.dir}"/>
    <mkdir dir="${zip.dir}"/>
    <mkdir dir="${build.classes}"/>
  </target>


  <!-- =================================================================== -->
  <!-- Export from VA                                                      -->
  <!-- =================================================================== -->
  <target name="export" depends="preparedirs" description="export projects">
    <mkdir dir="${src.dir}"/>
    <!-- Export all Ant sources except optional tasks and the Oro sources -->
    <vajexport destdir="${src.dir}">
      <include name="Ant/**"/>
      <exclude name="Ant/**/optional/**"/>
      <exclude name="Ant/org/apache/tools/ant/gui/**"/>
      <include name="Apache Oro*/**"/>
    </vajexport>
    <!-- Export selected optional tasks -->
    <vajexport destdir="${src.dir}">
      <include name="Ant/org/apache/tools/ant/taskdefs/optional/ide/**"/>
    </vajexport>
  </target>

  <!-- =================================================================== -->
  <!-- Unzip necessary libraries                                           -->
  <!-- =================================================================== -->
  <target name="expand">
    <mkdir dir="${build.classes}"/>
    <unzip src="${antdistribution.dir}\lib\crimson.jar"
           dest="${build.classes}"
    />
    <unzip src="${antdistribution.dir}\lib\jaxp.jar"
           dest="${build.classes}"
    />
    <delete dir="${build.classes}\META-INF" />
  </target>

  <!-- =================================================================== -->
  <!-- Compile the source code                                            -->
  <!-- =================================================================== -->
  <target name="compile" depends="expand" description="compile java sources">
    <mkdir dir="${build.classes}"/>
    <javac srcdir="${src.dir}"
           destdir="${build.classes}"
           debug="on"
           deprecation="off"
           optimize="on" >
      <classpath refid="classpath" />
      <include name="org/apache/**"/>
      <exclude name="**/JakartaRegexpMatcher.java"/>
    </javac>
  </target>

  <!-- =================================================================== -->
  <!-- Copy resources and zip everything together                           -->
  <!-- =================================================================== -->
  <target name="zip" depends="compile" description="creates zip distribution">
    <copy todir="${build.classes}">
      <fileset dir="${src.dir}">
          <include name="org/apache/**"/>
          <exclude name="**/*.java"/>
      </fileset>
    </copy>
    <mkdir dir="${build.classes}/doc"/>
    <copy todir="${build.classes}/doc" overwrite="yes">
      <fileset dir="${antdistribution.dir}/docs">
          <include name="VAJAnttool.html, toolmenu.gif, anttool1.gif"/>
      </fileset>
    </copy>
    <copy file="${antdistribution.dir}/src/main/org/apache/tools/ant/taskdefs/optional/ide/default.ini" todir="${build.classes}" overwrite="yes"/>
    <mkdir dir="${zip.dir}"/>
    <zip basedir="${build.classes}" zipfile="${zip.dir}/anttool.zip" />
  </target>

  <!-- =================================================================== -->
  <!-- Cleans source and class dirs                                        -->
  <!-- =================================================================== -->
  <target name="clean" depends="preparedirs" description="removes all files from src and build tree">
    <delete>
      <fileset dir="${src.dir}"/>
    </delete>
    <delete>
      <fileset dir="${build.classes}"/>
    </delete>
    <delete>
      <fileset dir="${zip.dir}"/>
    </delete>
  </target>

  <!-- =================================================================== -->
  <!-- Cleans the build dir, loads required project versions, exports,     -->
  <!-- compiles and zips the Plugin                                        -->
  <!-- =================================================================== -->
  <target name="buildall" depends="clean, load, export, zip" description="build all">
  </target>
</project>

The Plugin

Installation

• install the Visual Age IDE Tools (via File->Quick Start-> Add feature->'IBM IDE Utility class libraries'
• import an appropriate XML parser to VAJ (we use Xerces 1.2.0 and are happy with it). Unfortunately the XML parser delivered with VAJ (in the project 'IBM XML Parser for Java') doesn't work with Ant. You have to remove that project (temporarily) from the workspace before importing another XML implementation.
• import the Ant sources into VAJ.
• Create the directory C:\IBMVJava\ide\tools\org-apache-tools-ant.
• export the Ant and XML parser class files into this directory. Be sure to select class files and resources. Sources don't have to be exported. Some optional tasks have errors and can't be exported when You don't have the necessary packages in Your workspace (e.g. junit task, ejbc task). If You need this tasks either import these packages into VAJ, too, or copy the .class files directly from the binary distribution.
• copy default.ini (in jakarta-ant\src\...\taskdefs\optional\ide) to C:\IBMVJava\ide\tools\org-apache-tools-ant\default.ini.
• if you want to access this help from the Workbench, create the directory C:\IBMVJava\ide\tools\org-apache-tools-ant\doc and copy the files VAJAntTool.html, toolmenu.gif and anttool1.gif to it.
• VAJ has to be restarted to recognize the new tool.
• Now if You open the context menu of a project, You should see the entry 'Ant Build' in the Tools submenu (see Usage).
• Make sure the tool works as expected. Now You can remove Ant and the imported XML parser from Your workspace (and optionally add the IBM parser again).

Usage

• A menubar with some options described later
• The name of your selected VAJ project
• An entry field for the Ant XML buildfile with a browse [...] button. The full qualified filename, including the directory is needed here.
• A list with tasks specified in the buildfile. Until your first save of the build info (described later), this list will be empty. When loading a build file by the Reload Project button, this list is filled with all tasks which have a description attribute. The task you select in this list will be executed when pressing the Execute Task button.
• A pulldown box for specifying the log level.
• Three buttons. Two of them I have already described and the third one is just the Close button to exit our small tool!

Frequently Asked Questions

Q: I want to load, export and build more then one Visual Age project to one jar! How to?
A: The VA tasks are able to load and export several Projects all at once. You can choose whatever project you like for storing the tool information, it doesn't really matter

Q: When I load my build file, the list of targets is empty. Why?
A: You need to add the optional "description" parameter to the targets You want to come up in the list. Then reload the build file in the "ant build" tool. We chose to display only targets with description to allow the build file developer to distinguish between targets for end users and helper targets.

Q: Is there a sample build file available?
A: Now You can find an example in this manual

Q: Why does it export my entire workspace when I've already implicitly selected a project when starting the Tool?
A: This selection does not carry into the buildfile you are using. Set the Project name at the beginning of the "includes" parameter.

Q: When I import Ant into my Workspace, I get Problems reported. Can I ignore them?
A: It depends on the problems reported, and what you want to do with Ant. Problems you can't ignore:

• Classes from javax.xml.parser missing - install a compatible parser (see installation)
• Classes from com.ibm.ivj.util missing - install the Visual Age IDE Utility feature (see installation).

Q: Why is the task name vajload when the class is called VAJLoadProjects?
A: At the moment this task can load only project versions. This is reflected by the class name. It may be extended to load package and class versions, too, and we didn't want to let these extensions affect the build files. Therefore we chose the more general name vajload as task name.

Q: I want to use the same buildfile both within Visual Age and from the command line using my regular Ant environment. What do I need to be aware of?
A: The three Visual Age Tasks won't work when executing Ant from the command line.

Q: How do I control the import/export of sourcefiles, compiled files and project resources explicity?
A: Via the Boolean values exportClasses (default false) exportSources (default true) and exportResources (default true). In some situations, Resources are not exported correctly without this being explicity set.

Known Problems

• Exporting a package containing just resources doesn't work. This is a VAJ Tool API bug. Workaround: create a dummy class and set 'exportSources' to false.

VisualAge for Java Versions

History