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

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

The Tasks

These tasks are described in detail below.

VAJLoad

Description:

Loads a specified VAJ project version into the workspace.

Parameters

Parameters specified as nested elements

vajproject

Example

<vajload remote="localhost:32767">

    <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>

The Plugin

Installation

At the moment the installation has it's rough edges. If something described below doesn't work for You, it's probably not Your fault but incomplete/wrong instructions. In this case, please contact one of the authors.

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

Plugin

• 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 and resources into VAJ.
• Create the directory C:\IBMVJava\ide\tools\org-apache-tools-ant.
• export the Ant and XML parser class and resource 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).

Servlets for Remote Tool Access

• For a good introduction into the VAJ Remote Tool Access see the great introduction from Glenn McAllister at http://www7.software.ibm.com/vad.nsf/Data/Document4366. It is highly recommended to read this article before doing the installation (to understand what you do :-) ).
• insert the following lines into C:\IBMVJava\ide\tools\com-ibm-ivj-toolserver\servlets\servlet.properties. Typically this file is empty. If not, be careful not to delete the other lines.

  servlet.vajload.code=org.apache.tools.ant.taskdefs.optional.ide.VAJLoadServlet servlet.vajexport.code=org.apache.tools.ant.taskdefs.optional.ide.VAJExportServlet servlet.vajimport.code=org.apache.tools.ant.taskdefs.optional.ide.VAJImportServletName

• export the following classes from the package org.apache.tools.ant to C:\IBMVJava\ide\tools\com-ibm-ivj-toolserver\servlets\:
  BuildException
DirectoryScanner
FileScanner
Location
• export the following classes from the package org.apache.tools.ant.taksdefs.optional.ide to C:\IBMVJava\ide\tools\com-ibm-ivj-toolserver\servlets\:
  VAJUtil
VAJExportServlet
VAJImportServlet
VAJLoadServlet
VAJLocalUtil
VAJProjectDescription
VAJToolsServlet
VAJWorkspaceScanner
• configure the Remote Access (via Window->Options..., then choose 'Remote Access To Tool API') as shown in the following picture:

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!

• 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 ( Re)Load  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  button.
• A pulldown box for specifying the log level.
• Four buttons. Two of them I have already described. The other are the Stop button to cancel a running build and the third one is just the Close button to exit our small tool!
• Note that the build is canceled on the next console output after pressing the Stop button, not directly after pressing it.

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: 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:

(see installation)
• Classes from com.ibm.ivj.util missing - install the Visual Age IDE Utility feature (see installation).
• Errors in optional tasks you use within your build file

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:

• The project is excluded by the default excludes (see attribute 'defaultexcludes' of VAJExport)
• When looking at the project in the workspace, it is often difficult to distinguish between project name and version name (e.g. as in 'My GUI Components Java 2 3.5'). Check if you have the right project name by switching off the version name display temporarilly.

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

• 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