com.i3sp.ant
Class ProjectDependencies

java.lang.Object
  |
  +--org.apache.tools.ant.ProjectComponent
        |
        +--org.apache.tools.ant.Task
              |
              +--com.i3sp.ant.ProjectDependencies
All Implemented Interfaces:
Project

public class ProjectDependencies
extends org.apache.tools.ant.Task
implements Project

Ant task for specifying other products and projects to depend on.

This task allows the programmer to specify projects/products that this project requires in order to build itself. Rather than specifying paths to other products etc. This allows you to specify the product and its version to use and locates it from globally held settings.

Each depended project/product can specify its' own fileset of files to include in the final classpath, manpath, path or libpath or they can be specified within the build.xml file. See the section on PatternSets, on how the inclusion/exclusion of files works, and how to write patterns.

When the task is run, it adds the elements it finds to the classpath of the ant process and builds a system property CLASSPATH, which contains ONLY the elements it found (i.e., not the classpath required to run ant), modifies the java.library.path property and sets the MANPATH and PATH properties to the path elements it found for the corresponding classpath, libpath, manpath and path elements.

As a result, it also generates a dependencies.xml file which lists the versions and products/projects the build was run against. If a dependencies.xml file is found in a depended project/product, it is read and a recursive check is made that the product/project uses the same versions of other depended projects/products and a warning is issued if a depended project/product uses some other project/product that the current project does not directly depend on.

Other files are also generated to record the classpath, man, lib and path. Supported are files that can be sourced from UNIX shell, perl and emacs to set the variables to the values used during the build. It is trivial to add other file generators. The file generators are specified in the Formatters property in the com.i3sp.ant.SiteDefault resource.

The behaviour of this task can be modified by setting the dependencies.release property to yes. This will cause it to fail when it detects anomolies (such as a depended project having no matching classpath elements, extraneous CLASSPATH elements on startup, clashing dependency versions etc.) rather than give a warning.

As a side-effect of depending on another project/product, this task sets the location and verions of the depended project/product in a property. These properties are called dependencies.PROJECTNAME.location and dependencies.PROJECTNAME.version. These can be used to locate files from a depended project, for example.

Using this task

First you will need to tell ant about this task. When included in the com.i3sp.ant.jar file, it can be done like this:
    <taskdef classpath="${i3sp-build-home}/jar/com.i3sp.ant.jar"
             resource="com/i3sp/ant/Taskdefs.properties"/>
 
This will define all the tasks contained in the jar file. Otherwise, it can be done like this:
    <taskdef classpath="${i3sp-build-home}/jar/com.i3sp.ant.jar"
             name="projectdependencies"
             classname="com.i3sp.ant.ProjectDependencies"/>
 

Parameters

The Task has the following attributes:
Attribute Description Required
name Name of the application. stored in the build record, if given. No
version Version of the application being built. Stored in the build record and later used by projects depending on this one to verify the correct project/version is being accessed. No
destdir The directory to generate the dependencies.xml (and other files produced by the Formatters) in. By default, they will be generated into basedir. No
workspace The directory relative to basedir where other local builds of projects can be located. If an unversioned copy of a project is located here then it is used for the build as well as any released version of the project in the standard location. This supports having local versions of projects being worked on that can be used to build other projects without first having to complete a release cycle. This only works in non-release mode (when dependencies.release is not set to yes). No
release override the dependencies.release property. No
propertyprefix Set the prefix used for the names of the properties this task sets. This prefix, if set, is used for the names of the CLASSPATH, MANPATH, LIBPATH and PATH properties. If not set, they have no prefix, but if set to PREFIX they will be, eg. PREFIX.CLASSPATH. No
setglobals Set whether this task should set the global system variables. True by default. This controls whether the properties java.class.path and java.library.path are modified. No

The nested elements projectdir and productdir are supported, which can be used to override where to find projects/products. They are path-like structures, and can be set according to the ant doco.

The task supports the nested elements project and product. They are identical except that:

Both are specified as follows:
Attribute Description Required
name The name of the project/product we are depending on Yes
version The version of the project/product to depend on. This assumes the project/product is located in a tree that looks like: ProjectPath/projectName/versionX/.... If the version is not given it should look like ProjectPath/projectName/....
Note that if ProjectPath/projectName/versionX is a file, then it is opened and it's contents read to find the actual version to use. The translated version is reported in the dependencies.xml file. This allows a provider to provide a default version over which the provider has control for rapidly changing projects.
No
depfile Override where to locate the dependency file for the project. By default, this task checks for a dependency file in depended projects in a file called dependencies.xml in the root of the project. If it is located in a different spot and you wish to enable recursive dependency checking (i.e. that the depended project depends on the same versions of other projects/products as you do), this task must be able to locate the dependency file. It will only give a warning if it can't locate a dependency file if you override this value. No
envfile If the project/product provides a environment file (see Environment Files) then the name of this file can be overridden here. By default, this task checks for a environment file in depended projects in a file called environment.xml in the root of the project. As with the dependency file, a warning is given only if this value is overridden. No
options The options to be included from the environment file No

Each project/product tag can have the nested elements classpath, path, libpath and manpath, which are PatternSets. All files within the project/product that match the given pattern set are appended to the classpath/path/manpath/libpath.

Example

    <projectdependencies workspace=".."
                         destdir="${basedir}/deps"
                         name="i3sp-sso"
                         version="i3sp-ss0-1.3">
      <productdir path="/usr/local/java:/opt/java">
      <product name="Jetty" version="Jetty-3.1.RC5">
        <classpath includes="lib/*.jar" />
      </product>
      <product name="jakarta-oro" version="jakarta-oro-2.0.1">
        <classpath includes="jakarta-oro-2.0.1.jar" />
      </product>
      <project name="i3sp-util"
               version="i3sp-util-1.0.4"
               options="syslog"
               depfile="deps/dependencies.xml" />
    </projectdependencies>
 
Environment File The Environment file allows a project to define what path elements a project that depends on it will recieve. This allows a developer to specify that they depend on a project, but not to have to specify what classpath elements they need, leaving this up to the project/product they depend on to define. This is useful when the elements required are standard for all dependant projects.

In addition, a project can define optional path elements, that can be included with the options attribute in the project/product tag.

The environment can also define properties that will be set in the dependant project for use within its' build.xml file. These are specified by a property tag with a name and value attribute. The names of these properties should be suitably prefixed so as to not clash with the names of other properties (e.g. with the project name). Properties within the dependant project can be used within the name and value attribute, but the only properties guaranteed to be set are the standard ant properties and the properties environment.project.name, environment.project.verion and environment.project.location, which are the name, version and location of the project of the environment file.

Example environment file:

 <Environment>
   <classpath includes="jar/com.i3sp.util.jar"/>
   <property name="i3spUtilServletConfigSchema"
             value="${environment.project.location}/etc/i3sp-wwwserverConfig.schema"/>
   <property name="i3spUtilJboss.jar"
             value="${environment.project.location}/jar/com.i3sp.jboss.jar"/>
   <option name="syslog">
     <libpath includes="lib/${os.name}-${os.arch}" />
     <property name="i3spUtilSyslogLib" value="Syslog" />
   </option>
   <option name="path">
     <path includes="bin" />
   </option>
 </Environment>
 

Notes

Checking for externally defined elements in the CLASSPATH is only carried out if the CLASSPATH property is set when running ant to the value of the CLASSPATH environment variable. This should be done to guard against having CLASSPATH elements not specified within the build.xml being used during the build.

Version:
$Revision: 1.2 $ $Date: 2002/04/16 22:32:51 $
Author:
Matthew Watson

Inner Class Summary
static class ProjectDependencies.EnvValues
           
static class ProjectDependencies.Settings
           
static class ProjectDependencies.Values
           
static interface ProjectDependencies.ValuesFormatter
           
 
Constructor Summary
ProjectDependencies()
           
 
Method Summary
 Dependency createProduct()
           
 org.apache.tools.ant.types.Path.PathElement createProductdir()
          Add a productdirs sub-node.
 Dependency createProject()
           
 org.apache.tools.ant.types.Path.PathElement createProjectdir()
          Add a projectdirs sub-node.
 void execute()
           
 java.lang.String getDepPath()
           
 java.lang.String getName()
           
 java.lang.String getPropertyPrefix()
           
 java.lang.String getVersion()
           
 void init()
           
 boolean isSetGlobals()
           
 boolean isUseClasspath()
           
 void setDestdir(java.io.File dest)
          Set the destination directory for generating dependency files in.
 void setName(java.lang.String name)
          Set the name of the project we are building.
 void setPropertyPrefix(java.lang.String propPrefix_)
          Set the prefix used for the names of the properties this task sets.
 void setRelease(boolean rel)
           
 void setSetGlobals(boolean setGlobals_)
          Set whether this task should set the global system variables.
 void setUseClasspath(boolean useClasspath_)
          set whether the CLASSPATH property will be used as the initial CLASSPATH value and if it will be checked on startup
 void setVersion(java.lang.String version)
          Set the version of the project we are building.
 void setWorkspace(java.io.File workspace_)
          Set where the other projects would be locally.
 void validateDependencies(Dependency[] deps, java.util.ArrayList alldepsal)
           
 
Methods inherited from class org.apache.tools.ant.Task
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setTaskName
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject, setProject
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ProjectDependencies

public ProjectDependencies()
Method Detail

init

public void init()
          throws org.apache.tools.ant.BuildException
Overrides:
init in class org.apache.tools.ant.Task

setWorkspace

public void setWorkspace(java.io.File workspace_)
Set where the other projects would be locally. should be a path relative to where the build.xml file is.

setVersion

public void setVersion(java.lang.String version)
Set the version of the project we are building.

getVersion

public java.lang.String getVersion()
Specified by:
getVersion in interface Project

setName

public void setName(java.lang.String name)
Set the name of the project we are building.

getName

public java.lang.String getName()
Specified by:
getName in interface Project

isSetGlobals

public boolean isSetGlobals()

setSetGlobals

public void setSetGlobals(boolean setGlobals_)
Set whether this task should set the global system variables. True by default. This controls whether the properties java.class.path and java.library.path are modified.

isUseClasspath

public boolean isUseClasspath()

setUseClasspath

public void setUseClasspath(boolean useClasspath_)
set whether the CLASSPATH property will be used as the initial CLASSPATH value and if it will be checked on startup

getPropertyPrefix

public java.lang.String getPropertyPrefix()

setPropertyPrefix

public void setPropertyPrefix(java.lang.String propPrefix_)
Set the prefix used for the names of the properties this task sets. This prefix, if set, is used for the names of the CLASSPATH, MANPATH, LIBPATH and PATH variables. If not set, they have no prefix, but if set to PREFIX they will be, eg. PREFIX.CLASSPATH

getDepPath

public java.lang.String getDepPath()
Specified by:
getDepPath in interface Project

createProjectdir

public org.apache.tools.ant.types.Path.PathElement createProjectdir()
Add a projectdirs sub-node. Where to look for released projects

createProductdir

public org.apache.tools.ant.types.Path.PathElement createProductdir()
Add a productdirs sub-node. Where to look for external products

setDestdir

public void setDestdir(java.io.File dest)
Set the destination directory for generating dependency files in.

createProject

public Dependency createProject()

createProduct

public Dependency createProduct()

setRelease

public void setRelease(boolean rel)

execute

public void execute()
             throws org.apache.tools.ant.BuildException
Overrides:
execute in class org.apache.tools.ant.Task

validateDependencies

public void validateDependencies(Dependency[] deps,
                                 java.util.ArrayList alldepsal)
                          throws org.apache.tools.ant.BuildException


Copyright 2001 i3SP Pty. Ltd. All Rights Reserved.