JDT Projects

If you're working in Eclipse with Java projects, you work with JDT (Java Development Tools) projects. A project that is a JDT project has the org.eclipse.jdt.core.javanature nature and contains usualy at least a org.eclipse.jdt.core.javabuilder builder, that is responsible for (incrementally) building the project. Ant4Eclipse JDT-related tasks gives you access to all those JDT-specific settings.

JDT classpathes

Each JDT project declares a single classpath, that both works as a classpath when compiling your project ("compile-time classpath") and when you run it ("runtime classpath"). Both, compile and runtime classpath, are resolved from the same classpath definition that is stored in your projects .classpath file. A JDT classpath definition contains a set of classpath entries. There are several kinds of entries that all can be used in a single classpath:

Directories and JAR files: You can add Jar-files and directories to your project classpath. Those elements can be part of your project or reside outside of your project. This kind of classpath entry is very similar to a classpath entry that you can specify when using the -classpath argument with java or javac.
Project references:When specifying a reference to another Eclipse project (that must reside in your workspace) you add this project's classpath to your own classpath. This works recursive for all entries of the referenced project, as long as a runtime classpath should be resolved. If the classpath is resolved for compiling only those entries from a referenced project are added to your classpath, that are explizitly "exported" (Project properties -> Java Build Path -> Order and Export)
Classpath Variables: Classpath Variables are placeholders that point to a single path (directory or file). Variables can be contributed by Plug-ins (for example ECLIPSE_HOME). It's also possible to specify own variables (Preferences -> Java -> Build path -> Classpath Variable).
Libraries: Libraries can be used to add a set of additional entries to your classpath. Libraries can be contributed by Plug-ins (for example the "JRE System library" or the "Plug-in dependencies" library contributed by the PDE), but you can define your own libraries as well ("User libraries" defined via Preferences -> Java -> Build path -> User libraries). In opposite to Classpath Variables Libraries can be either static (as Classpath Variables) or dynamic. In case they are dynamic the actual entries they contribute are determined each time Eclipse (resp. ant4eclipse) needs to resolve the classpath. Imagine the "Plug-in dependencies" library as an example. You can add this library to all of your projects. But the entries the library adds to your project differ (not only from project to project, but even in the lifetime of a single project: each time you add a dependencie to your plug-in the added entries change)

Resolving a classpath

An important ant4eclipse feature is to correctly resolve a classpath that has been defined in Eclipse. This way ant4eclipse is able to calculate the correct build order of a set of projects according to their dependencies.
When ant4eclipse resolves a classpath for you, it takes all configurations that are stored directly in your projects into account. But there are some configurations that are not part of your project. JRE definitions for example are stored in the .metadata folder of your workspace, thus they are not available (for ant4eclipse) when you check your projects from your source code repository to a "clean" place where you want to start your build. The workspace settings have to be redefined in your build scripts. In the following sections we’ll show you how to do that. You will see that it’s quite easy.

Resolving JREs

Each Eclipse JDT-project usually contains an entry specifying the JRE or Execution Environment that should be used when compiling the project. This classpath entry is a "library" entry with a path starting with org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType followed by the name of your JRE or Execution Environment. The name is specified in Eclipse when you register a JRE via Window -> Preferences -> Java -> Installed JREs or an Execution Environment (via Window -> Preferences -> Java -> Installed JREs -> Execution Environments):

If you have a JRE with the name "jdk_15" configured (as in the screenshot above) and have added it to your build path, the appropriate classpath entry would look like this:

<classpath>
 ...
  <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/jdk_15"/>
 ...
</classpath>

Unfortunatly the JRE definitions are not stored in your project, so ant4eclipse cannot access them. To make sure ant4eclipse can correctly resolve your JREs you must set them up in your build file using the installedJREs type. This type contains a number of jre sub-elements that take two attributes: an id, that must match the name you have specified in Eclipse for a JRE. The second attribute, location must point to the root directory of the matching JRE installation. To configure the "jdk_15" that is shown in the screenshot above, you have to add the following lines to your build file:

<ant4eclipse:installedJREs>
 <jre id="jdk_15" location="r:/jdk_15" />
</ant4eclipse:installedJREs>

Execution environments

If you have specified in your build an Execution Environment instead of a concrete JRE, ant4eclipse automatically discovers the best matching JRE out of all JREs you have specified with installedJREs. If you want to force ant4eclipse to use a specific JRE for an Execution Environment, use the name of Execution Environment as the id attribute in the jre attribute.
Example:
If you're using the "J2SE-1.5" Execution Environment in your project, you're classpath contains the following entry:

<classpath>
 <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/J2SE-1.5"/>
</classpath>

To make sure that ant4eclipse will use the "jdk_15" JRE when resolving your classpath, use the following jre definition:

<ant4eclipse:installedJREs>
 <jre id="J2SE-1.5" location="r:/jdk_15" />
</ant4eclipse:installedJREs>

Resolving Classpath Libraries

As mentioned before, Eclipse allows you to add Classpath Libraries to your classpath. A Classpath Library is a set of files and directories that gets added to the classpath. There are two kind of libraries:

Static libraries: They simply contribute a fixed set of entries to the classpath. Everywhere you use such a container the same entries are contributed to your classpath. Some of those libraries are contributed by Eclipse plug-ins but you can define your own "User Libraries" via Preferences -> Java -> Build path -> User libraries.
Dynamic libraries: Such libraries are resolved each time Eclipse resolves a project classpath. The actual entries the libary contributes to a classpath vary depending on its context. The "Plug-in dependencies" library for example automatically adds all Plug-ins to your classpath, that your (Plug-in)project depent on, according to its Manifest- and plugin.xml-files.

A classpath entry for a Classpath Library has set its kind attribute to con ("Container"). Its path attribute consists of the library type (a "User Library" for example is of type "org.eclipse.jdt.USER_LIBRARY") and it's name (last part of the path). If you use the JUnit library for JUnit4, in your project the classpath entry for this library would look like this:

<classpath>
 ...
 <classpathentry kind="con" path="org.eclipse.jdt.junit.JUNIT_CONTAINER/4"/>
</classpath>

While ant4eclipse has currently built-in support for the "Plug-in dependencies" library, all other kinds of libraries must be declared in ant4eclipse (Note that the JRE library is treated special, see Resolving JREs). You can define a library in two ways:

You can use the jdtClasspathLibrary Ant type, that takes a set of resources that will be added to your classpath wherever you reference the library.
You can import the User Libraries XML definition file that has been exported from Eclipse

Using the `jdtClasspathLibrary`

The jdtClasspathLibrary allows you to define a classpath library. The type expects the name of the library (that is the whole path attribute of the classpath entry). To define the resources, that you want to add to your classpath whereever you use the library, use one or more resource collections. Please see Resource Collections in the Ant documentation for more informations on resource collections.

The following example declares the JUnit4 library with all jar-files that are located beneath c:\libs\junit4:

<ant4eclipse:jdtClassPathLibrary name="org.eclipse.jdt.junit.JUNIT_CONTAINER/4">
 <!-- Define that resources that should be added to the classpath.
      Note that you can specify more than one resource collection element
  -->
 <fileset dir="c:/libs/junit4" includes="**/*.jar"/>
</ant4eclipse:jdtClasspathLibrary>

Importing a User Library

Eclipse allows you to export (and import) your User Library definitions to an XML file. Ant4Eclipse is able to read this file and setup up the User Libraries for your build acordingly. In Eclipse you can export the library definitions via the User Libraries preference page (Preferences -> Java -> Build path -> User libraries -> Export...). The exported file can be read by the userLibraries Ant type. The usage of this type is straightforward, simply pass in the path to your exported file. If you have exported your libraries to "c:\ant4eclipse\all.userlibraries" you would use the userLibraries type this way:

<ant4eclipse:userLibraries userLibraries="c:/ant4eclipse/all.userlibraries"/>

Drawbacks

While it's quite handy to use Classpath Libraries in Eclipse, it has some drawbacks when you implement a build, that propably run (automatically) outside of Eclipse:

Libraries have to be-redifined in your build file as seen above. That leads to duplicate configuration.
Libraries usually point to resources that exists outside of your projects. If you check out your projects from your version control system, this resources might be missing. You have to make sure manually that all needed resources are available (with correct pathed!) whereever you start your build (on different machines, maybe different operating systems).

Resolving Classpath Variables

Classpath Variables are similar to Classpath Libraries. A Classpath Variable is a single file or directory that will be added to your classpath. When the variable points to an external directory outside of your workspace, you must "extend" it when you add it to your classpath by adding a file from that directory to the classpath.

A classpath entry for a Classpath Variable has set its kind attribute to var ("Variable"). Its path attribute consists of the variable name (eg ANT4ECLIPSE_HOME) and optionally the file that has been specified when adding it to the concrete classpath. For example:

<?xml version="1.0" encoding="UTF-8"?>
<classpath>
 ...
 <classpathentry kind="var" path="ANT4ECLIPSE_HOME/libs/ant4eclipse.jar"/>
 ...
</classpath>

To define the value of Classpath Variable in your build file you have to use the jdtClassPathVariable type. The types expects two attributes: a name, that must match the name of your Classpath Variable and a path that must point to the path (file or directory) the variable should point to. To set the ANT4ECLIPSE_HOME Classpath Variable to c:\ant4eclipse, use the following code in your build file:

 <ant4eclipse:jdtClassPathVariable name="ANT4ECLIPSE_HOME" path="c:/ant4eclipse"/>

Note that you can use any number of jdtClasspathVariables in your build file. The declared variables are visible accross your whole build file.

Using the ejc compiler adapter