Visual Age for Java Tasks and Plugin User Manual

by Version 1.2.1 - 2003/01/16

Table of Contents


Introduction

Visual Age for Java is a great Java IDE, but it lacks decent build support; for creating deliveries. On the other hand, Ant supports the build process very good, but is (at least at the moment) command line based. So we decided to write some tasks to access the VAJ repository and a small visual Ant frontend to make running Ant from VAJ possible. We use the Tool API to integrate Ant in VisualAge for Java. In combination with the VAJ tasks (vajload, vajexport, vajimport) you can load defined versions of projects into your workspace, export the source code, compile it with an external compiler and build a jar without leaving the IDE. Of course compile messages are viewed in a logging window. Concluding: This tool provides decent deployment support VAJ has not (out of the box).

What's new

2003/01/16
  • Now works outside of VAJ.
  • Added attribute haltonerror, "*" and "**" version qualifiers.
  • Amended documentation (this file) accordingly.
2001/06/14
  • Now all tasks can access VAJ via 'Remote Access To Tool API'. Therefore builds containing VAJ tasks can also be executed from the command line (Kudos to Glenn McAllister for describing the concept and providing source code at http://www7.software.ibm.com/vad.nsf/Data/Document4366
  • It is possible to cancel a running build executed from the plugin
  • Improved error handling in the plugin. Now all errors should show up either in the log window or in the console.

The Tasks

At the moment there are three tasks which help integrating the VAJ repository contents into an external build process:
VAJLoad
loads specified versions into the workspace
VAJExport
exports specified packages into the file system
VAJImport
imports specified files into the workspace

These tasks are described in detail below.


VAJLoad

Description:

Loads a specified VAJ project version into the workspace.

Parameters

Attribute Description Required
remote

name and port of a remote tool server. (format: <servername>:<port no>).
If this attribute is set, the tasks will be executed on the specified tool server. 

no
haltonerror

Stop the build process if an error occurs, (default: "yes")

no

Parameters specified as nested elements

vajproject

Attribute Description Required
name name of the VAJ project to load into the workspace yes
version

name of the requested version, or one of the special qualifiers "*" or "**"
"*" loads the latest versioned edition of the project
"**" will load the latest version (including open editions)

yes

Example

<vajload remote="localhost:32767">
    <vajproject name="My App" version="*"/>
    <vajproject name="My Testcases" version="**"/>
    <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

Attribute Description Required
destdir location to store the exported files yes
exportSources export source files (default: "yes") no
exportResources export resource files (default: "yes") no
exportClasses export class files (default: "no") no
exportDebugInfo include debug info in exported class files (default: "no") no
defaultexcludes

use default excludes when exporting (default: "yes").
Default excludes are: IBM*/**, Java class libraries/**, Sun class libraries*/**, JSP Page Compile Generated Code/**, VisualAge*/** 

no
overwrite overwrite existing files (default: "yes") no
remote

name and port of a remote tool server. (format: <servername>:<port no>).
If this attribute is set, the tasks will be executed on the specified tool server. 

no
haltonerror

Stop the build process if an error occurs, (default: "yes")

no

Parameters specified as nested elements

include

specifies the packages to include into the export
Attribute Description Required
name name of the VAJ project and package to export.
The first element of the name must be the project name,
then the package name elements separated by '/'.
yes

exclude

specifies the packages to exclude from the export
Attribute Description Required
name name of the VAJ project/package not to export yes

Example

<vajexport destdir="${src.dir}" exportResources="no">
    <include name="MyProject/**"/>
    <exclude name="MyProject/test/**"/>
</vajexport>
This example exports all packages in the VAJ project 'MyProject', except packages starting with 'test'.

Default Excludes

The default excludes are:
   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

Attribute Description Required
project imported files are added to this VAJ project yes
importSources import source files (default: "yes") no
importResources import resource files (default: "yes") no
importClasses import class files (default: "no") no
remote

name and port of a remote tool server. (format: <servername>:<port no>).
If this attribute is set, the tasks will be executed on the specified tool server. 

no
haltonerror

Stop the build process if an error occurs, (default: "yes")

no

Parameters specified as nested elements

fileset

A FileSet specifies the files to import.

Example

<vajimport project="Test" importClasses="true">
    <fileset dir="${import.dir}">
        <include name="com/sample/**/*.class"/>
        <exclude name="com/sample/test/**"/>
    </fileset>
</vajimport>
This example imports all class files in the directory ${import.dir}/com/sample excluding those in the subdirectory test

The Plugin

The tasks are usable within VAJ by running the org.apache.tools.ant.Main class, but this is quite inconvenient. Therefore a small GUI is provided which allows selecting a build file and executing its targets. This Plugin is accessible from the VAJ Tools menu (see Usage).

Installation

We assume C:\IBMVJava as VAJ install directory. If You have installed it elsewhere, adapt the pathes below.

Plugin

Servlets for Remote Tool Access

Now you should be able to execute VAJ Tasks from the command line.


Usage

Plugin

When the tool is installed correctly and your Ant build file is configured, it is really easy to use.
Go to your Workbench, select the project you want to deploy and open its context menu. In the submenu Tools you should find the new entry Ant Build. Klick it to start the tool!

After a short time this frame should pop up:
This frame contains the following elements:

After you have set up your buildprocess you might find it useful to save the data you've just entered, so we implemented an option to save it to the repository into your selected project. Make sure that you have an open edition of your project before selecting Save BuildInfo To Repository from the File menu. Now your information is saved to this edition of your project and will be loaded automatically the next time you start Ant Build.
If you have closed the log window accidentally, it can be reopened with the Log item in the File menu, and if you want to know who developed this, just select About in the Help menu.

Servlets for Remote Tool Access

With the servlets installed and the remote access running you can use Ant from the command line without any restrictions. Just make sure the remote attribute in your build file is set correctly.


Frequently Asked Questions

Q: If I try to load a build file, I get the error "Can't load default task list". Why?
A: Ant not only contains class files, but also resource files. This messsage appears if the file
.../org/apache/tools/ant/taskdefs/defaults.properties is missing. Make sure that you import/export not only java/class files, but also all resource files when importing/exporting Ant.

Q: If I try to re-load a build file, I get the error "XML parser factory has not been configured correctly". Why?
A: Make sure the META-INF/services directory of the xercesImpl.jar has also been expanded into the C:\IBMVJava\ide\tools\org-apache-tools-ant directory.

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:


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: You have to specifie a remote server via the 'remote' attribute. Otherwise the three Visual Age tasks won't work when executing Ant from the command line.

Q: I can export packages from project 'ABC', but not from project 'XYZ'! Why?
A: Common reasons are:

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. VAJ doesn't export resources correctly if a package contains only resources (see below).


Known Problems


VisualAge for Java Versions

This tool integration has been tested with versions 3.02 and 3.5 of VisualAge for Java. It should run with the 2.x Versions, too, but we didn't try. The graphical user interface is built with AWT so it is JDK independent by now.

History

1.0 2000/09/11 Initial Version
1.1 2001/02/14 Added Task documentation and more FAQs (thanks to Richard Bourke for the FAQ additions)
1.2 2001/07/02

Added documentation of new remote feature.
Minor corrections.

1.2.1 2003/01/16

Added documentation for haltonerror, "*" and "**" version qualifiers.


Copyright © 2001-2004 The Apache Software Foundation. All rights Reserved.