youys
/
ant

<!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>Christoph Wilhelms
      (<A href="mailto:christoph.wilhelms@tui.de"> 
  christoph.wilhelms@tui.de</A>)</LI></UL>
Version 1.2 - 2001/06/14<br>
<hr>
<h2>Table of Contents</H2>
<ul>
  <li><A href="#introduction">Introduction</A>
  <li><A href="#tasks">The Tasks</A><A href="#introduction"></A>
  <ul>
    <li><A href="#vajload">VAJLoad</A>&gt; 
    <li><A href="#vajexport">VAJExport</A>&gt; 
    <li><A href="#vajimport">VAJImport</A>&gt;</LI></UL>
  <li><A href="#sample_buildfile">A sample build file</A><br>
  <li><A href="#plugin">The Plugin</A>
  <ul>
    <li><A href="#installation">Installation</A>&gt; 
    <li><A href="#usage">Usage</A> </LI></UL>
  <li><A href="#faq">Frequently Asked Questions</A>&gt; 
  <li><A href="#va_versions">Visual Age Versions</A>&gt; 
  <li><A href="#history">History</A><A href="#history"></A> </LI></UL>

<hr>
<h2><a name="introduction"></A>Introduction</H2>
<P>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&nbsp;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).</P>
<H3>What's new</H3>
<table cellpadding="2" cellspacing="2" border="0" width="500">
     <tr valign="top">
       <td valign="top">2001/06/14</TD>
       <td valign="top">
      <UL>
        <LI>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
		<A href="http://www7.software.ibm.com/vad.nsf/Data/Document4366">
		http://www7.software.ibm.com/vad.nsf/Data/Document4366</A>.&nbsp; 

        <LI>It is possible to cancel a running&nbsp;build 
        executed from the plugin 
        <LI>Improved error handling in the plugin. Now all 
        errors should show up either in the log window or in the 
    console.</LI></UL></TD></TR></TABLE>

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

     <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></TABLE>
<P>These tasks are described in detail below.</P>


<hr>

<P></P>
<h2><a name="vajload"></A>VAJLoad</H2>
<h3>Description:</H3>
<p>Loads a specified VAJ project version into the 
workspace.</P>

<h3>Parameters</H3>

<table border="1" cellpadding="2" cellspacing="0">
     <tr>
       <td valign="top"><b>Attribute</B></TD>
       <td valign="top"><b>Description</B></TD>
       <td align="middle" valign="top"><b>Required</B></TD></TR>
     <tr>
       <td valign="top">remote</TD>
       <td valign="top">
      <P>name and port of a remote tool server. (format:
      &lt;servername&gt;:&lt;port no&gt;).<BR>If this 
      attribute is set, the tasks will&nbsp;be executed on the specified tool 
      server.&nbsp;</P></TD>
       <td valign="top" align="middle">no</TD></TR></TABLE>

<h3>Parameters specified as nested elements</H3>
<h4>vajproject</H4>
<table border="1" cellpadding="2" cellspacing="0">

     <tr>
       <td valign="top"><b>Attribute</B></TD>
       <td valign="top"><b>Description</B></TD>
       <td align="middle" 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="middle">yes</TD></TR>
     <tr>
       <td valign="top">version</TD>
       <td valign="top">name of the requested version</TD>
       <td valign="top" align="middle">yes</TD></TR>
     <tr>
       <td valign="top">remote</TD>
       <td valign="top">
      <P>name and port of a remote tool server. (format:
      &lt;servername&gt;:&lt;port no&gt;).<BR>If this 
      attribute is set, the tasks will&nbsp;be executed on the specified tool 
      server.&nbsp;</P></TD>
       <td valign="top" align="middle">no</TD></TR></TABLE>

<h3>Example</H3>
<pre>&lt;vajload remote="localhost:32767"&gt;
    &lt;vajproject name="My Testcases" version="1.7beta"/&gt;
    &lt;vajproject name="JUnit" version="3.2" /&gt;
&lt;/vajload&gt;
</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">

     <tr>
       <td valign="top"><b>Attribute</B></TD>
       <td valign="top"><b>Description</B></TD>
       <td align="middle" 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="middle">yes</TD></TR>
     <tr>
       <td valign="top">exportSources</TD>
       <td valign="top">export source files (default: 
"yes")</TD>
       <td valign="top" align="middle">no</TD></TR>
     <tr valign="top">
       <td valign="top">exportResources</TD>
       <td valign="top">export resource files (default: 
    "yes")</TD>
       <td valign="top" align="middle">no</TD></TR>
     <tr valign="top">
       <td valign="top">exportClasses</TD>
       <td valign="top">export class files (default: "no")</TD>
       <td valign="top" align="middle">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="middle">no</TD></TR>
  <TR>
    <TD vAlign=top>defaultexcludes</TD>
    <TD vAlign=top>
      <P>use default excludes when exporting (default: "yes").<BR>Default excludes are:&nbsp;IBM*/**, Java 
      class libraries/**, Sun class libraries*/**, JSP Page Compile Generated 
      Code/**, VisualAge*/**&nbsp;</P></TD>
    <TD vAlign=top align="middle">no</TD></TR>
     <tr valign="top">
       <td valign="top">overwrite</TD>
       <td valign="top">  overwrite existing files (default: 
      "yes")</TD>
       <td valign="top" align="middle">no</TD></TR>
     <tr>
       <td valign="top">remote</TD>
       <td valign="top">
      <P>name and port of a remote tool server. (format:
      &lt;servername&gt;:&lt;port no&gt;).<BR>If this 
      attribute is set, the tasks will&nbsp;be executed on the specified tool 
      server.&nbsp;</P></TD>
       <td valign="top" align="middle">no</TD></TR></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">

     <tr>
       <td valign="top"><b>Attribute</B></TD>
       <td valign="top"><b>Description</B></TD>
       <td align="middle" 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></TABLE>

<h4>exclude</H4>
specifies the packages to exclude from the export<br>

<table border="1" cellpadding="2" cellspacing="0">

     <tr>
       <td valign="top"><b>Attribute</B></TD>
       <td valign="top"><b>Description</B></TD>
       <td align="middle" 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="middle">yes</TD></TR></TABLE>

<h3>Example</H3>
<pre>&lt;vajexport destdir="${src.dir}" exportResources="no"&gt;
    &lt;include name="MyProject/**"/&gt;
    &lt;exclude name="MyProject/test/**"/&gt;
&lt;/vajexport&gt;
</PRE>
This example exports all packages in the VAJ project 'MyProject', except
packages starting with 'test'.
<h3>Default Excludes</H3>
The default excludes are:<br>
<pre>	IBM*/**
	Java class libraries/**
	Sun class libraries*/**
	JSP Page Compile Generated Code/**
	VisualAge*/**
</PRE>
<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">

     <tr>
       <td valign="top"><b>Attribute</B></TD>
       <td valign="top"><b>Description</B></TD>
       <td align="middle" 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="middle">yes</TD></TR>
     <tr>
       <td valign="top">importSources</TD>
       <td valign="top">export source files (default: 
"yes")</TD>
       <td valign="top" align="middle">no</TD></TR>
     <tr valign="top">
       <td valign="top">importResources</TD>
       <td valign="top">export resource files (default: 
    "yes")</TD>
       <td valign="top" align="middle">no</TD></TR>
     <tr valign="top">
       <td valign="top">importClasses</TD>
       <td valign="top">export class files (default: "no")</TD>
       <td valign="top" align="middle">no</TD></TR>
     <tr>
       <td valign="top">remote</TD>
       <td valign="top">
      <P>name and port of a remote tool server. (format:
      &lt;servername&gt;:&lt;port no&gt;).<BR>If this 
      attribute is set, the tasks will&nbsp;be executed on the specified tool 
      server.&nbsp;</P></TD>
       <td valign="top" align="middle">no</TD></TR></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>&lt;vajimport project="Test" importClasses="true"&gt;
    &lt;fileset dir="${import.dir}"&gt;
        &lt;include name="com/sample/**/*.class"/&gt;
        &lt;exclude name="com/sample/test/**"/&gt;
    &lt;/fileset&gt;
&lt;/vajimport&gt;
</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>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>
<p>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>.</P>
<p>We assume <CODE>C:\IBMVJava</CODE> as VAJ
install directory. If You have installed it elsewhere, adapt the pathes below.
<h3>Plugin</H3>
<ul>
  <li>install the Visual Age IDE Tools (via File-&gt;Quick 
  Start-&gt; Add feature-&gt;'IBM IDE Utility class libraries' 
  <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>import the Ant sources <STRONG>and </STRONG>   resources into VAJ. 
  <li>Create the directory <CODE>
      C:\IBMVJava\ide\tools\org-apache-tools-ant</CODE>.
  <li>export the Ant and XML parser class and resource files 
  into this directory. Be sure to select class files <STRONG>and</STRONG>          
          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>copy <CODE>default.ini</CODE> (in <CODE>
      jakarta-ant\src\...\taskdefs\optional\ide</CODE>)     to <CODE>
      C:\IBMVJava\ide\tools\org-apache-tools-ant\default.ini</CODE>. 

  <li>if you want to access this help from the Workbench, create the
      directory <CODE> C:\IBMVJava\ide\tools\org-apache-tools-ant\doc</CODE>
      and copy the files     <CODE>VAJAntTool.html</CODE>,
      <CODE>toolmenu.gif</CODE> and     <CODE>
      anttool1.gif</CODE> to it. 
  <li>VAJ has to be restarted to recognize the new tool. 
  <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>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>
  <h3>Servlets for Remote Tool Access</H3>
<UL>
  <LI>        
                   For
        a good introduction into the VAJ Remote Tool Access see the
        great introduction from Glenn McAllister at
		<A href="http://www7.software.ibm.com/vad.nsf/Data/Document4366">
		http://www7.software.ibm.com/vad.nsf/Data/Document4366</A>.&nbsp;It 
  is highly recommended to read this article before doing the installation (to 
  understand what you do :-) ).
  <LI>insert the following lines into
  <code>C:\IBMVJava\ide\tools\com-ibm-ivj-toolserver\servlets\servlet.properties</CODE>.
  Typically this file is empty. If not, be careful not to delete the other lines.
  <table cellpadding="0" cellspacing="0" border="0" width="500">
     <tr valign="top">
       <td valign="top">
<PRE>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<PRE>  </PRE></PRE></TD></TR></TABLE>
  <LI>export the following classes from the package
  <CODE>org.apache.tools.ant</CODE>
  to <CODE>C:\IBMVJava\ide\tools\com-ibm-ivj-toolserver\servlets\</CODE>:<BR>
  <CODE>BuildException<BR>
  DirectoryScanner<BR>
  FileScanner<BR>
  Location</CODE>
  <LI>export the following classes from the package
  <CODE>org.apache.tools.ant.taksdefs.optional.ide</CODE>
  to <CODE>C:\IBMVJava\ide\tools\com-ibm-ivj-toolserver\servlets\</CODE>:<BR>
  <CODE>VAJUtil<BR>
  VAJExportServlet<BR>
  VAJImportServlet<BR>
  VAJLoadServlet<BR>
  VAJLocalUtil<BR>
  VAJProjectDescription<BR>
  VAJToolsServlet<BR>
  VAJWorkspaceScanner</CODE>
  <LI>configure the Remote Access (via 
  Window-&gt;Options..., then choose 'Remote Access To Tool API') as shown in 
  the following picture:</LI></UL>
  <P align=center><IMG height=645 alt="" src="remacc.gif"
 width=587 border=0 ></P>
<P>Now you should be able to execute VAJ Tasks from the 
command line.</P>

<hr>
<h2><a name="usage"></A>Usage</H2>
<H3>Plugin</H3>
<P>
 When 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! </P>      

<center><IMG height=246 src="toolmenu.gif" width=393 border=0></CENTER>
           After a short time this frame should pop up:
<center><IMG height=241 alt=""
 src="file://D:\javaext\jakarta-ant-1.4alpha\docs\manual\Integration\anttool1.gif" 
 width=389 border=0></CENTER>
           This frame contains the following elements:
<ul>
  <li>A menubar with some options described later 
  <li>The name of your selected VAJ project 
  <li>An entry field for the Ant XML buildfile with a browse 
  [...] button. The full qualified filename, including the directory is needed 
  here. 
  <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 ( <EM>Re)Load&nbsp;</EM> 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
      <EM>Execute&nbsp;</EM> button. 
  <li>A pulldown box for specifying the log level. 
  <li>Four buttons. Two of them I have already
  described. The other are the <EM>Stop</EM> button to cancel a running build
  and the third one is just the <EM>Close</EM> button to exit our small tool! 
  <li>Note that the build is canceled on the next console
  output after pressing the <EM>Stop</EM> button, not 
  directly after pressing it.</LI></UL>
<P>
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. </P>
<H3>Servlets for Remote Tool Access</H3>
<P>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.</P> 
<hr>
<h2><a name="faq"></A>Frequently Asked 
Questions</H2>
<P><STRONG>Q: If I try to load a build 
file, I get the error "Can't load default task list". Why?</STRONG><br>
A: Ant not only contains class files, but also resource 
files. This messsage appears if the file 
<BR>.../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.</P>
<P><STRONG>Q: I want to load, export 
and build more then one Visual Age project to one jar! How to?</STRONG><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><STRONG>Q: When I load my build 
file, the list of targets is empty. Why?</STRONG><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><STRONG>Q: Is there a sample build 
file available? </STRONG><br>
A: Now you can find an <A href="#sample_buildfile">example</A> in this manual </P>
<p><STRONG>Q: Why does it export my 
entire workspace when I've already implicitly selected a project when starting 
the Tool?</STRONG><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><STRONG>Q: When I import Ant into 
my Workspace, I get Problems reported. Can I ignore them?</STRONG><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>Classes from com.ibm.ivj.util missing - install the Visual Age IDE
      Utility feature  (see <A href="#installation">installation</A>).
  <li>Errors in optional tasks you use within your build 
  file</LI></UL>
<br>

<p><STRONG>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?</STRONG><br>
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. </P>

<p><STRONG>Q: I can export packages 
from project 'ABC', but not from project 'XYZ'! Why?</STRONG><br>
A: Common reasons are:</P>
<UL>
<li>The project is excluded by the default excludes (see 
  attribute 'defaultexcludes' of VAJExport) 
<li>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.</LI></UL>
<p><STRONG>Q: How do I control the 
import/export of sourcefiles, compiled files and project resources 
explicity?</STRONG><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. VAJ doesn't export resources correctly if a package 
contains only resources (see below).</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 built 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">
     <tr valign="top">
       <td valign="top">1.0</TD>
       <td valign="top">2000/09/11</TD>
       <td valign="top">Initial Version</TD></TR>
  <TR>
    <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>
     <tr valign="top">
       <td valign="top">1.2</TD>
       <td valign="top">2001/07/02</TD>
       <td valign="top">
      <P>Added documentation of new remote feature.<BR>Minor corrections.</P></TD></TR></TABLE>
<hr>
<center>Copyright &amp;#copy 2001 Apache Software 
Foundation. All rights Reserved.</CENTER>
</body>
</html>