|
- <!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta http-equiv="Content-Language" content="en-us">
- <title>Visual Age for Java Tasks and Plugin User Manual</title>
- </head>
- <body>
-
- <h1>Visual Age for Java Tasks and Plugin User Manual</h1>
- <a name="authors"></a>by<ul>
- <li>Wolf Siberski
- (<a href="mailto:wolf.siberski@tui.de"> wolf.siberski@tui.de</a> )</li>
- <li>Christoph Wilhelms
- (<a href="mailto:christoph.wilhelms@tui.de"> christoph.wilhelms@tui.de</a>)</li>
- </ul>
- Version 1.1 - 2001/02/14<br>
- <hr>
- <h2>Table of Contents</h2>
- <ul>
- <li><a href="#introduction">Introduction</a></li>
- <li><a href="#tasks">The Tasks</a><a href="#introduction"></a></li>
- <ul>
- <li><a href="#vajload">VAJLoad</a></li>
- <li><a href="#vajexport">VAJExport</a></li>
- <li><a href="#vajimport">VAJImport</a></li>
- </ul>
- <li><a href="#sample_buildfile">A sample build file</a><br></li>
- <li><a href="#plugin">The Plugin</a></li>
- <ul>
- <li><a href="#installation">Installation</a></li>
- <li><a href="#usage">Usage</a></li>
- </ul>
- <li><a href="#faq">Frequently Asked Questions</a></li>
- <li><a href="#va_versions">Visual Age Versions</a></li>
- <li><a href="#history">History</a><a href="#history"></a></li>
- </ul>
-
- <hr>
- <h2><a name="introduction"></a>Introduction</h2>
- 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 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).<br>
-
- <h2><a name="tasks"></a>The Tasks</h2>
- At the moment there are three tasks which help integrating the VAJ repository
- contents into an external build process:
-
- <table cellpadding="2" cellspacing="2" border="0" width="500">
- <tbody>
- <tr valign="Top">
- <td valign="Top"><a href="#vajload">VAJLoad</a><br>
- </td>
- <td valign="Top"> loads specified versions into the workspace<br>
- </td>
- </tr>
- <tr valign="Top">
- <td valign="Top"><a href="#vajexport">VAJExport</a><br>
- </td>
- <td valign="Top"> exports specified packages into the file system<br>
- </td>
- </tr>
- <tr valign="Top">
- <td valign="Top"><a href="#vajimport">VAJImport</a><br>
- </td>
- <td valign="Top"> imports specified files into the workspace<br>
- </td>
- </tr>
- </tbody>
- </table>
- These tasks are described in detail below.
-
- <hr>
- <h2><a name="vajload"></a>VAJLoad</h2>
- <h3>Description:</h3>
- <p>Loads a specified VAJ project version into the workspace.</p>
-
- <h3>Parameters</h3>
- <p>none</p>
-
- <h3>Parameters specified as nested elements</h3>
- <h4>vajproject</h4>
- <table border="1" cellpadding="2" cellspacing="0">
- <tbody>
- <tr>
- <td valign="Top"><b>Attribute</b></td>
- <td valign="Top"><b>Description</b></td>
- <td align="Center" valign="Top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="Top">name</td>
- <td valign="Top">name of the VAJ project to load into the workspace</td>
- <td valign="Top" align="Center">yes</td>
- </tr>
- <tr>
- <td valign="Top">version</td>
- <td valign="Top">name of the requested version</td>
- <td valign="Top" align="Center">yes</td>
- </tr>
-
- </tbody>
- </table>
-
- <h3>Example</h3>
- <pre>
- <vajload>
- <vajproject name="My Testcases" version="1.7beta" />
- <vajproject name="JUnit" version="3.2" />
- </vajload>
- </pre>
-
- <hr>
- <h2><a name="vajexport"></a>VAJExport</h2>
-
- <h3>Description:</h3>
- <p>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 <a href="index.html#fileset">
- FileSets</a>. </p>
-
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tbody>
- <tr>
- <td valign="Top"><b>Attribute</b></td>
- <td valign="Top"><b>Description</b></td>
- <td align="Center" valign="Top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="Top">destdir</td>
- <td valign="Top">location to store the exported files</td>
- <td valign="Top" align="Center">yes</td>
- </tr>
- <tr>
- <td valign="Top">exportSources</td>
- <td valign="Top">export source files (default: "yes")</td>
- <td valign="Top" align="Center">no</td>
- </tr>
- <tr valign="Top">
- <td valign="Top">exportResources</td>
- <td valign="Top">export resource files (default: "yes")</td>
- <td valign="Top" align="Center">no</td>
- </tr>
- <tr valign="Top">
- <td valign="Top">exportClasses</td>
- <td valign="Top">export class files (default: "no")</td>
- <td valign="Top" align="Center">no</td>
- </tr>
- <tr valign="Top">
- <td valign="Top">exportDebugInfo</td>
- <td valign="Top">include debug info in exported
- class files (default: "no")</td>
- <td valign="Top" align="Center">no</td>
- </tr>
- <tr valign="Top">
- <td valign="Top">defaultexcludes </td>
- <td valign="Top">use default excludes when exporting (default: "yes")
- <td valign="Top" align="Center">no</td>
- </tr>
- </tbody>
- </table>
-
- <h3>Parameters specified as nested elements</h3>
-
- <h4>include</h4>
- specifies the packages to include into the export
-
- <table border="1" cellpadding="2" cellspacing="0">
- <tbody>
- <tr>
- <td valign="Top"><b>Attribute</b></td>
- <td valign="Top"><b>Description</b></td>
- <td align="Center" valign="Top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="Top">name</td>
- <td valign="Top">name of the VAJ project and package to export.<br>
- The first element of the name must be the project name, <br>
- then the package name elements separated by '/'.</td>
- <td valign="Top">yes</td>
- </tr>
- </tbody>
- </table>
-
- <h4>exclude</h4>
- specifies the packages to exclude from the export<br>
-
- <table border="1" cellpadding="2" cellspacing="0">
- <tbody>
- <tr>
- <td valign="Top"><b>Attribute</b></td>
- <td valign="Top"><b>Description</b></td>
- <td align="Center" valign="Top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="Top">name</td>
- <td valign="Top">name of the VAJ project/package not to export</td>
- <td valign="Top" align="Center">yes</td>
- </tr>
- </tbody>
- </table>
-
- <h3>Example</h3>
- <pre>
- <vajexport destdir="${src.dir}" exportResources="no">
- <include name="MyProject/**"/>
- <exclude name="MyProject/test/**"/>
- </vajexport>
- </pre>
- This example exports all packages in the VAJ project 'MyProject', except
- packages starting with 'test'.
- <hr>
- <h2><a name="vajimport"></a>VAJImport</h2>
-
- <h3>Description:</h3>
- <p>Imports Java source files, class files and/or resources from the file
- system into VAJ. These imports can be specified with a fileset. </p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tbody>
- <tr>
- <td valign="Top"><b>Attribute</b></td>
- <td valign="Top"><b>Description</b></td>
- <td align="Center" valign="Top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="Top">vajProject</td>
- <td valign="Top">imported files are added to this VAJ project</td>
- <td valign="Top" align="Center">yes</td>
- </tr>
- <tr>
- <td valign="Top">importSources</td>
- <td valign="Top">export source files (default: "yes")</td>
- <td valign="Top" align="Center">no</td>
- </tr>
- <tr valign="Top">
- <td valign="Top">importResources</td>
- <td valign="Top">export resource files (default: "yes")</td>
- <td valign="Top" align="Center">no</td>
- </tr>
- <tr valign="Top">
- <td valign="Top">importClasses</td>
- <td valign="Top">export class files (default: "no")</td>
- <td valign="Top" align="Center">no</td>
- </tr>
- </tbody>
- </table>
-
- <h3>Parameters specified as nested elements</h3>
-
- <h4>fileset</h4>
- A <a href="index.html#fileset">FileSet</a> specifies the files to import.
-
- <h3>Example</h3>
- <pre>
- <vajimport project="Test" importClasses="true">
- <fileset dir="${import.dir}">
- <include name="com/sample/**/*.class"/>
- <exclude name="com/sample/test/**"/>
- </fileset>
- </vajimport>
- </pre>
- This example imports all class files in the directory ${import.dir}/com/sample
- excluding those in the subdirectory test<br>
-
- <hr>
- <h2><a name="sample_buildfile"></a>A sample build file</h2>
- This is a sample build file which builds a zip file useful for distribution
- of the VAJ plugin. The build file exports a specific version of Ant, compiles
- it, extracts necessary helper classes and zips everything together. This
- is useful as complete example as well as to deploy Ant in a team where all
- developers use VAJ. The resulting zip file must be unzipped in
- <tt><VAJInstallDir>\ide\tools\org-apache-tools-ant</tt>.
- For more information see the <a href="#installation">installation</a> section.<br>
- <br>
- <pre>
- <?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>
- </pre>
-
- <hr>
- <h2><a name="plugin"></a>The Plugin</h2>
- 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 <a href="#usage">Usage</a>).
-
- <hr>
- <h2><a name="installation"></a>Installation</h2>
- 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 <a href="#authors">authors</a>.
- We assume <font face="Courier">C:\IBMVJava</font> as VAJ install
- directory. If You have installed it elsewhere, adapt the pathes below.
- Execute following steps to get the PlugIn up and running:
- <ul>
- <li>install the Visual Age IDE Tools (via File->Quick Start->
- Add feature->'IBM IDE Utility class libraries'
- </li>
- <li>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.
- </li>
-
- <li>import the Ant sources into VAJ.</li>
- <li>Create the directory <font face="Courier">
- C:\IBMVJava\ide\tools\org-apache-tools-ant</font>.
- </li>
- <li>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.
- </li>
- <li>copy <font face="Courier">default.ini</font> (in <font face="Courier">
- jakarta-ant\src\...\taskdefs\optional\ide</font>) to <font face="Courier">
- C:\IBMVJava\ide\tools\org-apache-tools-ant\default.ini</font>.
- </li>
- <li>if you want to access this help from the Workbench, create the
- directory <font face="Courier"> C:\IBMVJava\ide\tools\org-apache-tools-ant\doc</font>
- and copy the files <font face="Courier">VAJAntTool.html</font>,
- <font face="Courier">toolmenu.gif</font> and <font face="Courier">
- anttool1.gif</font> to it.
- </li>
- <li>VAJ has to be restarted to recognize the new tool.</li>
- <li>Now if You open the context menu of a project, You should see the entry
- 'Ant Build' in the Tools submenu (see <a href="#usage">Usage</a>).
- </li>
- <li>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).
- </li>
- </ul>
-
- <hr>
- <h2><a name="usage"></a>Usage</h2>
- Beeing sure the tool is installed correctly and your Ant build
- file is configured, it is really easy to use.<br>
- Go to your Workbench, select the project you want to deploy and
- open its context menu. In the submenu <i>Tools</i> you should find
- the new entry <i>Ant Build</i>. Klick it to start the tool!
-
- <center><img src="toolmenu.gif" border="0" height="246" width="393"></center>
- After a short time this frame should pop up:
- <center><img src="anttool1.gif" border="0" height="222" width="389"></center>
- This frame contains the following elements:
- <ul>
- <li>A menubar with some options described later</li>
- <li>The name of your selected VAJ project</li>
- <li>An entry field for the Ant XML buildfile with a browse [...] button.
- The full qualified filename, including the directory is needed here.
- </li>
- <li>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 <i>Reload Project</i> 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
- <i> Execute Task</i> button.
- </li>
- <li>A pulldown box for specifying the log level.</li>
- <li>Three buttons. Two of them I have already described and the third one
- is just the <i>Close </i>button to exit our small tool!
- </li>
- </ul>
- 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
- <i>Save BuildInfo To Repository</i> from the <i>File</i> menu.
- Now your information is saved to this edition of your project and will
- be loaded automatically the next time you start <i>Ant Build</i>.<br>
- If you have closed the log window accidentally, it can be reopened
- with the <i>Log</i> item in the <i>File</i> menu, and if you want to
- know who developed this, just select <i>About</i> in the <i>Help</i> menu.
- <hr>
- <h2><a name="faq"></a>Frequently Asked Questions</h2>
-
- <p><b>Q: I want to load, export and build more then one Visual Age project
- to one jar! How to?</b><br>
- 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
- </p>
- <p><b>Q: When I load my build file, the list of targets is empty. Why?</b><br>
- 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.
- </p>
- <p><b>Q: Is there a sample build file available? </b><br>
- A: Now You can find an <a href="#sample_buildfile">example</a> in this manual
- </p>
-
- <p><b>Q: Why does it export my entire workspace when I've already implicitly
- selected a project when starting the Tool?</b><br>
- A: This selection does not carry into the buildfile you are using. Set the
- Project name at the beginning of the "includes" parameter.
- </p>
- <p><b>Q: When I import Ant into my Workspace, I get Problems reported. Can I
- ignore them?</b><br>
- A: It depends on the problems reported, and what you want to do with Ant.
- Problems you can't ignore:
- <ul>
- <li>Classes from javax.xml.parser missing - install a compatible parser
- (see <a href="#installation">installation</a>)
- </li>
- <li>Classes from com.ibm.ivj.util missing - install the Visual Age IDE
- Utility feature (see <a href="#installation">installation</a>).
- </li>
- </ul>
- </p>
-
- <p><b>Q: Why is the task name vajload when the class is called VAJLoadProjects?</b><br>
- 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.
- </p>
- <p><b>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?</b><br>
- A: The three Visual Age Tasks won't work when executing Ant from the command
- line.
- </p>
- <p><b>Q: How do I control the import/export of sourcefiles, compiled files and
- project resources explicity?</b><br>
- 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.
- </p>
- <hr>
- <h2><a name="known_problems"></a>Known Problems</h2>
- <ul>
- <li>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.
- </li>
- </ul>
- <hr>
-
- <h2><a name="va_versions"></a>VisualAge for Java Versions</h2>
- 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 build with AWT so it is
- JDK independent by now.
- <hr>
-
- <h2><a name="history"></a>History</h2>
- <table cellpadding="2" cellspacing="2" border="1" width="400">
- <tbody>
- <tr valign="Top">
- <td valign="Top">1.0</td>
- <td valign="Top">2000/09/11</td>
- <td valign="Top">Initial Version</td>
- </tr>
- <tr valign="Top">
- <td valign="Top">1.1</td>
- <td valign="Top">2001/02/14</td>
- <td valign="Top">Added Task documentation and more FAQs (thanks to
- Richard Bourke for the FAQ additions)
- </td>
- </tr>
- </tbody>
- </table>
- <hr>
- <center>Copyright © 2001 Apache Software Foundation. All rights Reserved.</center>
- </body>
- </html>
|