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:
-
-
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)
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
-
-
-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")
-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
-
-
Create the directory
- C:\IBMVJava\ide\tools\org-apache-tools-ant.
-
Expand in that directory all the jars contained in the lib
- directory of your Ant installation.
-
copy default.ini (in
- org\apache\tools\ant\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.
-
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.
-
Expand the Ant libraries (ant.jar and optional.jar
- contained in the lib directory of your Ant installation) to the directory
- C:\IBMVJava\ide\tools\com-ibm-ivj-toolserver\servlets\.
-
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!
-
-
- After a short time this frame should pop up:
-
- This frame contains the following elements:
-
-
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: 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:
-
-
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).
-
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
-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.
-Instruments Java classes with iContract
- DBC preprocessor.
- The task can generate a properties file for iControl,
- a graphical user interface that lets you turn on/off assertions. iControl generates a control file that you can refer to
- from this task using the controlfile attribute.
-
-
-
Parameters
-
-
-
Attribute
-
Description
-
Required
-
-
-
srcdir
-
Location of the java files.
-
Yes
-
-
-
instrumentdir
-
Indicates where the instrumented source files should go.
-
Yes
-
-
-
repositorydir
-
Indicates where the repository source files should go.
-
Yes
-
-
-
builddir
-
Indicates where the compiled instrumented classes should go.
- Defaults to the value of instrumentdir.
- NOTE: Don't use the same directory for compiled instrumented classes
- and uninstrumented classes. It will break the dependency checking. (Classes will
- not be reinstrumented if you change them).
-
No
-
-
-
repbuilddir
-
Indicates where the compiled repository classes should go.
- Defaults to the value of repositorydir.
-
No
-
-
-
pre
-
Indicates whether or not to instrument for preconditions.
- Defaults to true unless controlfile is specified, in which case it
- defaults to false.
-
No
-
-
-
post
-
Indicates whether or not to instrument for postconditions.
- Defaults to true unless controlfile is specified, in which case it
- defaults to false.
-
No
-
-
-
invariant
-
Indicates whether or not to instrument for invariants.
- Defaults to true unless controlfile is specified, in which case it
- defaults to false.
-
No
-
-
-
failthrowable
-
The full name of the Throwable (Exception) that should be
- thrown when an assertion is violated. Defaults to java.lang.Error
-
No
-
-
-
verbosity
-
Indicates the verbosity level of iContract. Any combination
- of error*,warning*,note*,info*,progress*,debug* (comma separated) can be
- used. Defaults to error*
-
No
-
-
-
quiet
-
Indicates if iContract should be quiet. Turn it off if many your classes extend uninstrumented classes
- and you don't want warnings about this. Defaults to false
-
No
-
-
-
updateicontrol
-
If set to true, it indicates that the properties file for
- iControl in the current directory should be updated (or created if it doesn't exist).
- Defaults to false.
-
No
-
-
-
controlfile
-
The name of the control file to pass to iContract. Consider using iControl to generate the file.
- Default is not to pass a file.
-
Only if updateicontrol=true
-
-
-
classdir
-
Indicates where compiled (uninstrumented) classes are located.
- This is required in order to properly update the icontrol.properties file, not
- for instrumentation.
-
Only if updateicontrol=true
-
-
-
targets
-
Name of the file that will be generated by this task, which lists all the
- classes that iContract will instrument. If specified, the file will not be deleted after execution.
- If not specified, a file will still be created, but it will be deleted after execution.
-
No
-
-
-
-
- Note: iContract will use the java compiler indicated by the project's
- build.compiler property. See documentation of the Javac task for
- more information. Nested includes and excludes are also supported.
-
-
Example:
-
-
- Note: iContract will use the java compiler indicated by the project's
- build.compiler property. See documentation of the Javac task for
- more information.
-
- Nested includes and excludes can be done very much the same way as any subclass
- of MatchingTask.
This is a primitive task to execute a unit test in the org.apache.testlet framework.
-
This task is deprecated as the Testlet framework has been
-abandoned in favor of JUnit by the Avalon community.
-
Note: This task depends on external libraries not included
-in the Ant distribution. See
-Library Dependencies for more information.
-
-
-
Parameters
-
-
-
Attribute
-
Description
-
Required
-
-
-
showSuccess
-
a boolean value indicating whether tests should display a
- message on success
-
-
No
-
-
-
showBanner
-
a boolean value indicating whether a banner should be displayed
- when starting testlet engine
-
-
No
-
-
-
forceShowTrace
-
a boolean indicating that a stack trace is displayed on any failure
-
-
No
-
-
-
showTrace
-
a boolean indicating that a stack trace is displayed on
- error (but not normal failure)
-
-
No
-
-
-
-The user can also specify the nested <classpath> element which defines classpath
-in which the task is executed. The user also specifies a subelement per testlet executed
-which has content that specifies tasklet classname.