Headless Ant

This function is deprecated and has been replaced by the
instantiations.audit Ant Task in CodePro AnalytiX Server.

"Headless" Ant refers to executing Ant scripts without any user interface other than a command line.  There are several CodePro Ant task types that can be executed in a headless environment. Below are some headless Ant examples. Each example assumes that you have already downloaded and installed

  • JDK 1.3 or better
  • Eclipse 2.1 or better.

Rational Application Developer 6.0:

Several of the headless examples below refer to

<property name="jreDir" location="C:/Programs/jdk1.5.0_05/jre"/>

and

<classpath>
<pathelement location="${jreDir}/lib/rt.jar"/>
</classpath>

If you are using RAD 6.0, then the JRE directory is something like

C:\Program Files\IBM\Rational\SDP\6.0\eclipse\jre

and the "rt.jar" has been renamed to "core.jar" and is found at

${jreDir}\lib\core.jar

WebSphere Application Developer 5.1:

See the section at the bottom of this page if you are using Eclipse 2.1 or Application Developer 5.1.

WebSphere Application Developer 5.0:

See the section at the bottom of this page if you are using Eclipse 2.0 or Application Developer 5.0.


Example - headless_arbitrary_src_1

This example demonstrates generating audit and metric results using a headless Ant script on some arbitrary java source files located in an arbitrary source folder. Given this situation, this example generates a new temporary workspace, a new temporary project linking to the arbitrary source tree, compiles the source and generates the audit and metric reports. To run this example:

Once you get this example working, modify the headless.xml file to try different codepro.audit and codepro.metrics Ant task attributes so that you get a feel for the various possibilities.


Example - headless_arbitrary_src_metric_set

This example demonstrates generating metric results using a headless Ant script on some arbitrary java source files located in an arbitrary source folder. In addition, the headless.xml Ant script specifies a specific metric set to be used. Given this situation, this example generates a new temporary workspace, a new temporary project linking to the arbitrary source tree, compiles the source and generates the metric report. To run this example:

  • modify the Local Environment Variables section of the run_headless.bat script to specify
    • The JRE java.exe to be used
    • The Eclipse startup.jar
    • The location of your workspace (does not need to exist)
  • modify the jreDir property in the headless.xml file to specify
    • The location of the JRE directory
  • execute the run_headless.bat script

Notice that the metric report generated only contains the metrics specified in the specified metric set and not all of the metrics specified in the default metric set. Once you get this example working, modify the headless.xml file to try different codepro.metrics Ant task attributes so that you get a feel for the various possibilities.


Example - headless_arbitrary_src_callgraph

This example demonstrates generating a call graph using a headless Ant script on some arbitrary java source files located in an arbitrary source folder. Given this situation, this example generates a new temporary workspace, a new temporary project linking to the arbitrary source tree, compiles the source and generates the callgraph report. To run this example:

  • modify the Local Environment Variables section of the run_headless.bat script to specify
    • The JRE java.exe to be used
    • The Eclipse startup.jar
    • The location of your workspace (does not need to exist)
  • modify the jreDir property in the headless.xml file to specify
    • The location of the JRE directory
  • execute the run_headless.bat script

Once you get this example working, modify the headless.xml file to try different codepro.callgraph Ant task attributes so that you get a feel for the various possibilities.


Example - headless_arbitrary_src_multi_audit

This example demonstrates generating a multiple audit results using a headless Ant script on some arbitrary java source files located in an arbitrary source folder. In the Ant script, the first audit specifies a classpath and the deleteTempProject attribute. This generates a new temporary project linking to the arbitrary source tree, compiles the source, generates the first audit report, and does not delete the temporary project. The second audit specifies the same source path as the first audit, but does not specify a classpath causing the second audit to reuse the existing temporary project generated by the first audit. To run this example:

  • modify the Local Environment Variables section of the run_headless.bat script to specify
    • The JRE java.exe to be used
    • The Eclipse startup.jar
    • The location of your workspace (does not need to exist)
  • modify the jreDir property in the headless.xml file to specify
    • The location of the JRE directory
  • execute the run_headless.bat script

Once you get this example working, modify the headless.xml file to try different codepro.audit Ant task attributes so that you get a feel for the various possibilities.


Example - headless_existing_workspace

This example demonstrates generating audit and metric results using a headless Ant script on a workspace and project that already exist. All of the java files in the project are audited using the default audit rule set of the existing workspace. To run this example:

  • download and unzip the appropriate example file into a clean directory
  • launch Eclipse specifying the existing-workspace directory that is part of this example
  • import the Test project directory located in the existing-workspace directory
    • select File > Import...
    • select Existing Project into Workspace
    • click the Browse button and locate the Test project directory in the existing-workspace directory
    • click Finish
  • wait until Eclipse has finished building the workspace
  • exit Eclipse
  • modify the Local Environment Variables section of the run_headless.bat script to specify
    • The JRE java.exe to be used
    • The Eclipse startup.jar
    • The location of the existing-workspace directory that is part of this example
  • execute the run_headless.bat script

Once you get this example working, modify the headless.xml file to try different codepro.audit and codepro.metrics Ant task attributes so that you get a feel for the various possibilities.


Example - headless_existing_workspace_with_audit_file

This example demonstrates generating audit and metric results using a headless Ant script on a workspace and project that already exist. In addition, the existing project contains a .audit file that specifies which files are to be included and excluded and which audit rule set should be applied. To run this example:

  • download and unzip the appropriate example file into a clean directory
  • launch Eclipse specifying the existing-workspace directory that is part of this example
  • import the Test project directory located in the existing-workspace directory
    • select File > Import...
    • select Existing Project into Workspace
    • click the Browse button and locate the Test project directory in the existing-workspace directory
    • click Finish
  • wait until Eclipse has finished building the workspace
  • exit Eclipse
  • modify the Local Environment Variables section of the run_headless.bat script to specify
    • The JRE java.exe to be used
    • The Eclipse startup.jar
    • The location of the existing-workspace directory that is part of this example
  • execute the run_headless.bat script

The audit report generated only includes violations for audit rules specified in the SimpleAuditRuleSet.xml file (as opposed to the default audit rule set) and violations for one file (the other was excluded by the filter specified in the .audit file). Once you get this example working, modify the headless.xml file to try different codepro.audit and codepro.metrics Ant task attributes so that you get a feel for the various possibilities.


Example - headless_existing_workspace_with_complex_audit_file

This example demonstrates generating audit and metric results using a headless Ant script on a workspace and project that already exist. In addition, the existing project contains a .audit file that references two different audit rule sets and specifies which files are subject to which audit rule sets. To run this example:

  • launch Eclipse specifying the existing-workspace directory that is part of this example
  • import the Test project directory located in the existing-workspace directory
    • select File > Import...
    • select Existing Project into Workspace
    • click the Browse button and locate the Test project directory in the existing-workspace directory
    • click Finish
  • wait until Eclipse has finished building the workspace
  • exit Eclipse
  • modify the Local Environment Variables section of the run_headless.bat script to specify
    • The JRE java.exe to be used
    • The Eclipse startup.jar
    • The location of the existing-workspace directory that is part of this example
  • execute the run_headless.bat script

The audit report generated only includes violations for audit rules specified in the SimpleAuditRuleSet.xml file (for one set of files) and the OtherAuditRuleSet.xml file (for another set of files). Once you get this example working, modify the headless.xml file to try different codepro.audit and codepro.metrics Ant task attributes so that you get a feel for the various possibilities.


Eclipse 2.1 / WebSphere Application Developer v5.1

The "-clean" option that appears in the various run_headless.bat scripts does not apply to Eclipse 2.1 and WebSphere Application Developer v5.1 and should be removed.

For WebSphere Application Developer v5.1, if you encounter problems running headlessly and it works within the IDE environment, in your Ant script make sure to use the JRE within the WSAD itself located in your  [WSAD_HOME]\Application Developer\v5.1.2\_jvm\ directory instead of the JRE within the eclipse directory. If  you have to use the eclipse JRE, please specify -Xj9 switch to tell the VM *not* to run in Classic Mode.

If you encounter the following error:

BUILD FAILED
file:c:/Documents and Settings/username/Desktop/headless_for_Eclipse_2.0/headless.xml:9: Could not create task or type of type: codepro.audit.

1. Download and unzip this "clean-workspace.zip" file (it contains an empty workspace that has the linked resources option enabled).

2. Change the value of the "WORKSPACE" variable in the "run_headless.bat" file to point to the clean workspace you just unzipped.

3. Remove the -clean option from the "run_headless.bat" file.


Eclipse 2.0 / WebSphere Application Developer 5.0

Some of the new CodePro Ant task types build upon functionality that is not available in Eclipse 2.0.  Specifically, the classpath attribute of the codepro.audit and codepro.metrics ant tasks require functionality provided in Eclipse 2.1 or better, or any WebSphere Studio IDE based upon it (such as WSAD 5.1.2).

Also, the "-clean" option that appears in the various run_headless.bat scripts does not apply to Eclipse 2.0 and WebSphere Application Developer v5.0 and should be removed.

Problem with Eclipse "headless" Ant environment
    in Eclipse 2.0 / Application Developer 5.0

The Eclipse "headless" Ant environment aggressively loads all Ant tasks and the plug-ins that define them regardless of whether or not that task is referenced in the Ant script being executed.  This means whenever the Eclipse internal "headless" Ant runner encounters an Ant task designed to run inside the IDE but not in a "headless" environment, the Eclipse internal "headless" Ant runner will fail rather than degrading gracefully.  This is covered fully in the Eclipse bugzilla report

    http://bugs.eclipse.org/bugs/show_bug.cgi?id=29572

This Eclipse bug is fixed as part of Eclipse 2.1, but not in Eclipse 2.0.  To workaround this problem, we have introduced a new cpsws-enable-headless.bat script to disable all CodePro plugins except those that can be utilized in a headless Ant environment.  Simply execute this script before executing a headless Ant script, and then execute cpsws-enable.bat afterward to re-enable all of the CodePro plugins so that CodePro can be used normally within the Eclipse / Application Developer IDE.  Both of these scripts are located in the <CODEPRO>\eclipse directory in a Application Developer installation or the root directory of an Eclipse installation.

Example for Eclipse 2.0:     (Eclipse 2.0 or 2.1)
    The example/headless_for_Eclipse_2.0.zip file contains a simple example of Ant script that can be run in "headless" mode on resources existing inside an Eclipse workspace. This example will work in Eclipse 2.0 and 2.1.

  • create a new java project in your workspace with java sources placed in a folder with the name "src"
  • unzip the files in example/headless_for_Eclipse_2.0.zip file into your new project
  • modify the Local Environment Variables section of the run_headless.bat script to specify
    • The JRE java.exe to be used
    • The Eclipse startup.jar
    • The location of your workspace (does not need to exist)
  • exit the Eclipse / Application Developer IDE
  • if you are using Application Developer 5.0 or Eclpse 2.0,
            then execute the cpsws-enable-headless.bat script
  • execute the run_headless.bat script
  • check the headless_out.txt file generated by the run_headless.bat script
            to see if the script executed correctly
  • if you are using Application Developer 5.0 or Eclpse 2.0,
            then execute the cpsws-enable.bat script to re-enable CodePro