Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Integrating TopLink Workbench With Apache Ant

If you use the Apache Ant Java-based build tool, you can use the Ant task and type definitions that TopLink provides to invoke certain TopLink Workbench functions from an Ant build file. Using these tasks, you can integrate TopLink Workbench into your automated build process.

This section describes the following:

- Configuring Ant to Use TopLink Workbench Tasks

- Understanding TopLink Workbench Ant Task API

- Creating TopLink Workbench Ant Tasks

For more information about Ant, see `http://ant.apache.org/manual/`.

## Configuring Ant to Use TopLink Workbench Tasks

Before you can use TopLink Workbench tasks in your Ant build files, you must consider their library dependencies (see "Library Dependencies").

To declare TopLink Workbench tasks in your Ant `build.xml` file, declare them directly (see "Declaring TopLink Workbench Tasks").

### Library Dependencies

In addition to the Ant library dependencies (see `http://ant.apache.org/manual/install.html#librarydependencies`), Table 5-4 lists the TopLink-specific JAR files that must be in your Ant classpath.

Table 5-4 TopLink Workbench Ant Task Library Dependencies

JAR Name | Needed For ... | Available At ...
--- | --- | ---
`toplinkmw.jar` | TopLink Workbench Ant task and type definitions. | `<``TOPLINK_HOME``>/jlib`

### Declaring TopLink Workbench Tasks

After you declare the TopLink Workbench task definitions (see Table 5-6) and data definitions (see Table 5-4) in the `toplink-ant-lib.xml` file as Example 5-5 shows, you can use a TopLink Workbench task in a `build.xml` file as shows:

Example 5-5 Declaring TopLink Workbench Ant Task and Data Types in a toplink-ant-lib.xml File

    <?xml version="1.0"?>
    <antlib>
        <taskdef name="mappings.export"
            classname="oracle.toplink.workbench.ant.taskdefs.ExportDeploymentXMLTask" />

        <taskdef name="mappings.validate"
            classname="oracle.toplink.workbench.ant.taskdefs.MappingsValidateTask" />

        <taskdef name="session.validate"
            classname="oracle.toplink.workbench.ant.taskdefs.SessionValidateTask" />

        <typedef name="ignoreerror"
            classname="oracle.toplink.workbench.ant.typedefs.IgnoreError" />

        <typedef name="ignoreerrorset"
            classname="oracle.toplink.workbench.ant.typedefs.IgnoreErrorSet" />

        <typedef name="loginspec"
            classname="oracle.toplink.workbench.ant.typedefs.LoginSpec" />
    </antlib>

Example 5-6 Specifying the toplink-ant-lib.xml File in the build.xml File

    <project name="MyBuild" default="validate.session" basedir="." xmlns:toplink="toplinklib">    <typedef file = "toplink-ant-lib.xml" classpathref = "mw.classpath" uri = "toplinklib" />...</project>

## Understanding TopLink Workbench Ant Task API

Table 5-5 lists the TopLink Workbench Ant task definitions that TopLink provides.

Table 5-5 TopLink Workbench Ant Task Definitions

Task Name | TopLink Class
--- | ---
mappings.validate | `oracle.toplink.workbench.ant.taskdefs.MappingsValidateTask`
session.validate | `oracle.toplink.workbench.ant.taskdefs.SessionValidateTask`
mappings.export | `oracle.toplink.workbench.ant.taskdefs.ExportDeploymentXMLTask`

Table 5-6 lists the TopLink Workbench Ant type definitions that TopLink provides.

Table 5-6 TopLink Workbench Ant Type Definitions

Type Name | TopLink Class
--- | ---
ignoreerror | `oracle.toplink.workbench.ant.typedefs.IgnoreError`
ignoreerrorset | `oracle.toplink.workbench.ant.typedefs.IgnoreErrorSet`
loginspec | `oracle.toplink.workbench.ant.typedefs.LoginSpec`

## Creating TopLink Workbench Ant Tasks

Example 5-7 shows a typical Ant `build.`xml file that declares and uses the TopLink Workbench Ant task and type definitions.

Example 5-7 Example Ant Build File with TopLink Workbench Ant Tasks

    <project name="MyBuild" default="validate.session" basedir="." xmlns:toplink="toplinklib">
        <!-- ===================================================== -->
        <!--  Properties                                           -->
        <!-- ===================================================== -->
        <target name="init">
            <property file="build.properties"/>

            <property name = "toplink.mwp.dir" value = "${basedir}/mw"/>
            <property name = "toplink.sessions.dir" value = "${basedir}/config"/>
            <property name = " myProject.classes" value = "${basedir}/classes "/>

            <path id = "database.classpath">
                <pathelement path = "${toplink.home}/jlib /dms.jar"/>
                <pathelement path = "${toplink.home}/jlib /OracleThinJDBC.jar"/>
            </path>
            <path id = "toplink.classpath">
                <pathelement path = "${toplink.home}/jlib /toplink.jar"/>
                <pathelement path = "${toplink.home}/jlib /ejb.jar"/>
                <pathelement path = "${toplink.home}/jlib /xmlparserv2.jar"/>
                <pathelement path = "${toplink.home}/jlib /antlr.jar"/>
            </path>
            <path id = "mw.classpath">
                <pathelement path = "${toplink.home}/jlib /tlmwcore.jar"/>
                <pathelement path = "${toplink.home}/jlib /toplinkmw.jar"/>
            </path>
            <path id = "mwplatforms.classpath">
                <pathelement path = "${toplink.home}/config"/>
            </path>

            <typedef file = "toplink-ant-lib.xml"

                     classpathref = "mw.classpath"
                     uri = "toplinklib" />
        </target>
        <!-- ===================================================== -->
        <!--  Define task parameter                                -->
        <!-- ===================================================== -->
        <target name="parameter.definition" depends="init">
            <toplink:ignoreerrorset id = "ignoreErrors">
            <toplink:ignoreerror code = "0233" />
            </toplink:ignoreerrorset>

            <toplink:loginspec id = "loginSpec"
            url = "jdbc:cloudscape:stagedb;create=true"
            driverclass = "COM.cloudscape.core.JDBCDriver"
            user = "scott"
            password="tiger" />
        </target>
         <!-- ==================================================== -->
        <!--  Validate the MW Project                              -->
        <!-- ===================================================== -->
        <target name="validate.project" depends="parameter.definition">

            <toplink:mappings.validate
                projectfile = "${toplink.mwp.dir}/myProject.mwp"
                reportfile = "${toplink.mwp.dir}/problem-report.html"
                reportformat = "html"
                property = "mw-valid"
                classpathref = "mwplatforms.classpath" >

                <toplink:classpath refid = "mw.classpath" />
                <toplink:classpath refid = "toplink.classpath" />

                <toplink:ignoreerrorset refid = "ignoreErrors"/>

            </toplink:mappings.validate>
        </target>
        <!-- ===================================================== -->
        <!--  TopLink deployment descriptor XML generation         -->
        <!-- ===================================================== -->
        <target name="export.deployment" depends="validate.project"  if="mw-valid">

            <toplink:mappings.export
                projectfile = "${toplink.mwp.dir}/myProject.mwp"
                deploymentfile = "${toplink.sessions.dir}/sessions.xml"
                property = "export-completed"
                failonerror = "true"
                classpathref = "toplink.classpath">

                <toplink:classpath refid = "mw.classpath" />
                <toplink:classpath refid = "mwplatforms.classpath" />

                <toplink:ignoreerrorset refid = "ignoreErrors"/>
                <toplink:loginspec refid = "loginSpec" />
            </toplink:mappings.export>
        </target>
        <!-- ===================================================== -->
        <!--  TopLink Session Validate                             -->
        <!-- ===================================================== -->
        <target name="validate.session"  depends="export.deployment" if="export-completed">

            <toplink:session.validate
                sessionsfile = "${toplink.sessions.dir}/sessions.xml"
                sessionname = "ThreeTierEmployee"
                property = "session-valid"
                classpathref = "toplink.classpath"
                classpath = "${ myProject.classes}" >

                <toplink:classpath refid = "mw.classpath" />
                <toplink:classpath refid = " database.classpath" />

                <toplink:loginspec refid = "loginSpec" />
            </toplink:session.validate>
        </target>
    <project>

## mappings.validate

The `mapings.validate` task is a testing task that you use to list of all the problems in a TopLink Workbench project (`.mwp`) file.

This task provides the ability to:

- log all the problems to a file in text or HTML format

- set an Ant property to indicate that the TopLink Workbench project is valid (has no errors)

### Parameters

Table 5-7 mappings.validate Task Parameters

Attribute | Description | Required
--- | --- | ---
projectfile | Fully qualified TopLink Workbench projects file name (.mwp). | Yes
reportfile | Fully qualified file name to which to write the output. | No
reportformat | The format of the generated output. Must be `html` or `text`. | No–default to `text`.
classpath | Project classpath. | No
classpathref | Reference to a path defined elsewhere. | No
property | The name of the property to set (true if there is no problem). | No

### Parameters Specified as Nested Elements

You can specify the following parameters as nested elements of this task:

- classpath

- "ignoreerror"

- "ignoreerrorset"

### Examples

shows a typical `mappings.validate` task.

Example 5-8 A mappings.validate Task

    <toplink:mappings.validate
        projectfile = "${toplink.mwp.dir}/myProject.mwp"
        reportfile = "${toplink.mwp.dir}/problem-report.html"
        reportformat = "html"
        property = "mw-valid"
        classpath = "${mwplatforms.classpath}" >

        <toplink:classpath refid = "mw.classpath" />
        <toplink:classpath refid = "toplink.classpath" />

        <toplink:ignoreerrorset refid = "ignoreErrors"/>
        <toplink:ignoreerror code = "0555" />
    </toplink:mappings.validate>

## session.validate

The `session.validate` task is a testing task that you use to test your TopLink deployment XML by running TopLink.

This task provides the ability to:

- specify the test type using a nested element

- set an Ant property to indicate that the TopLink Workbench project is valid (has no errors)

### Parameters

Table 5-8 session.validate Task Parameters

Attribute | Description | Required
--- | --- | ---
sessionsfile | Fully qualified `sessions.xml` file. | No–default to `sessions.xml` and to classpath.
sessionname | Name of the session to test. | Yes
classpath | Project classpath. | No
classpathref | Reference to a path defined elsewhere. | No
property | The name of the property to set (true if valid). | No

### Parameters Specified as Nested Elements

You can specify the following parameters as nested elements of this task:

- classpath

- "loginspec"

### Examples

shows a typical `session.validate` task.

Example 5-9 A session.validate Task

    <toplink:session.validate
        sessionsfile = "${toplink.sessions.dir}/sessions.xml"
        sessionname = "ThreeTierEmployee"
        property = "session-valid"
        classpathref = "toplink.classpath"
        classpath = "${ myProject.classes}" >

        <toplink:classpath refid = "mw.classpath" />
        <toplink:classpath refid = " database.classpath" />

        <toplink:loginspec refid = "loginSpec" />
    </toplink:session.validate>

## mappings.export

The `mappings.export` task is a generation task that you use to generate a TopLink deployment XML file for a given TopLink Workbench project (`.mwp`). The `mappings.export` task executes a `mappings.validate` (see "mappings.validate") before executing. A `BuildException` is thrown if validation fails.

This task provides the ability to override the TopLink Workbench project database login information.

### Parameters

Table 5-9 mappings.export Task Parameters

Attribute | Description | Required
--- | --- | ---
projectfile | Fully qualified TopLink Workbench projects file name (`.mwp`). | Yes
deploymentfile | Fully qualified TopLink project deployment file name (`.xml`). | No–default to the name specified in the TopLink Workbench project (`.mwp`).
ejbjarxmldir | The directory that contains the `ejb-jar.xml` file (only applicable to J2EE project). | No–default to the directory specified in the TopLink Workbench project (`.mwp`).
classpath | Project classpath. | No
classpathref | Reference to a path defined elsewhere. | No
failonerror | Indicates whether the build will continue even if there are export errors; defaults to `true`. | No
property | The name of the property to set (`true` if export completed successfully). | No

### Parameters Specified as Nested Elements

You can specify the following parameters as nested elements of this task:

- classpath

- "loginspec"

- "ignoreerror"

- "ignoreerrorset"

### Examples

shows a typical `mappings.export` task.

Example 5-10 A mappings.export Task

    <toplink:mappings.export
        projectfile = "${toplink.mwp.dir}/myProject.mwp"
        deploymentfile = "${toplink.sessions.dir}/sessions.xml"
        property = "export-completed"
        failonerror = "true"
        classpathref = "toplink.classpath">

        <toplink:classpath refid = "mw.classpath" />
        <toplink:classpath refid = "mwplatforms.classpath" />

        <toplink:ignoreerrorset refid = "ignoreErrors"/>
        <toplink:ignoreerror code = "0545" />
        <toplink:loginspec
                url = "jdbc:cloudscape:stagedb;create=true"
                driverclass = "COM.cloudscape.core.JDBCDriver"
                user = "scott"
                password="tiger" />
    </toplink:mappings.export>

## classpath

Use the classpath element to define the Java classpath necessary to run a task. For more information, see `http://ant.apache.org/manual/using.html#path`.

### Parameters

Table 5-10 classpath Element Parameters

Attribute | Description | Required
--- | --- | ---
location | Specifies a single file or directory relative to the project's base directory (or an absolute filename). | No
path | Specifies one or multiple files or directories separated by a colon or semicolon. | No
refid | Reference to a path defined elsewhere. | No

### Parameters Specified as Nested Elements

You can specify the following parameters as nested elements of this task:

- pathelement

- fileset

- dirset

- filelist

### Examples

shows a typical `classpath` element.

Example 5-11 A classpath Element

    <classpath>    <pathelement path="${classpath}"/>        <fileset dir="lib">            <include name="**/*.jar"/>        </fileset>    <pathelement location="classes"/>        <dirset dir="${build.dir}">            <include name="apps/**/classes"/>            <exclude name="apps/**/*Test*"/>        </dirset>    <filelist refid="third-party_jars"/></classpath>

## ignoreerror

Use the `ignoreerror` element to instruct a TopLink Ant task to ignore a specific TopLink Foundation Library (see "TopLink Exception Reference") or TopLink Workbench (see "TopLink Workbench Error Reference") run-time error code.

To instruct a TopLink Ant task to ignore multiple error codes, consider using an `ignoreerrorset` element (see "ignoreerrorset").

### Parameters

Table 5-11 ignoreerror Element Parameters

Attribute | Description | Required
--- | --- | ---
code | Error code of the problem to ignore. | Yes

### Parameters Specified as Nested Elements

You cannot specify parameters as nested elements of this element.

### Examples

shows a typical `ignoreerror` element. This element instructs a `mappings.export` task to ignore TopLink Workbench error code 0545.

Example 5-12 An ignoreerror Element

    <toplink:mappings.export     projectfile = "${toplink.mwp.dir}/myProject.mwp"    deploymentfile = "${toplink.sessions.dir}/sessions.xml"    classpathref = "toplink.classpath">    <toplink:classpath refid = "mw.classpath" />    <toplink:classpath refid = "mwplatforms.classpath" />    <toplink:ignoreerror code = "0545" /></toplink:mappings.export>

## ignoreerrorset

Use the `ignoreerrorset` element to instruct a TopLink Ant task to ignore any of multiple TopLink Foundation Library (see "TopLink Exception Reference") or TopLink Workbench (see "TopLink Workbench Error Reference") run-time error codes.

### Parameters

Table 5-12 ignoreerrorset Element Parameters

Attribute | Description | Required
--- | --- | ---
id | Unique identifier for this type instance, can be used to reference this type in scripts. | No
refid | Reference to a ignoreerrorset defined elsewhere. | No

### Parameters Specified as Nested Elements

You can specify the following parameters as nested elements of this element:

- "ignoreerror"

### Examples

Example 5-13 shows a typical `ignoreerrorset` element. This element instructs a `mappings.export` task to ignore all of TopLink Workbench error codes 0402 and 0570. Note that the `mappings.export` task also uses an explicitly `ignoreerror` element: this means that the `mappings.export` task will ignore all of error codes 0402, 0570, and 0545.

Example 5-13 An ignoreerrorset Element

    <toplink:ignoreerrorset id = "ignoreErrors">    <toplink:ignoreerror code = "0402" />    <toplink:ignoreerror code = "0570" /></toplink:ignoreerrorset>...<toplink:mappings.export     projectfile = "${toplink.mwp.dir}/myProject.mwp"    deploymentfile = "${toplink.sessions.dir}/sessions.xml"    classpathref = "toplink.classpath">    <toplink:classpath refid = "mw.classpath" />    <toplink:classpath refid = "mwplatforms.classpath" />    <toplink:ignoreerrorset refid = "ignoreErrors"/>    <toplink:ignoreerror code = "0545" /></toplink:mappings.export>

## loginspec

Use the `loginspec` element to instruct a TopLink Ant task to override the project database login information in a TopLink Workbench project. For more information, see "Understanding Data Access".

Note: You can only use this element with a relational project (see "Relational Projects"). You cannot use this element with a J2EE project.

### Parameters

Table 5-13 loginspec Element Parameters

Attribute | Description | Required
--- | --- | ---
id | Unique identifier for this type instance, can be used to reference this type in scripts. | No
refid | Reference to a loginspec defined elsewhere. | No
driverclass | Fully qualified class of the data source driver (see "Configuring Database Login Connection Options"). | No — default to the class that the TopLink Workbench project specifies.
url | URL of the driver see "Configuring Database Login Connection Options"). | Yes
user | Login user name (see "Configuring User Name and Password"). | No–default to the value that the TopLink Workbench project specifies
password | Login password (see "Configuring User Name and Password"). | No–default to the value that the TopLink Workbench project specifies

### Parameters Specified as Nested Elements

You cannot specify parameters as nested elements of this element.

### Examples

Example 5-14 shows a typical `loginspec` element.

Example 5-14 A loginspec Element

    <toplink:mappings.export
        projectfile = "${toplink.mwp.dir}/myProject.mwp"
        deploymentfile = "${toplink.sessions.dir}/sessions.xml"
        classpathref = "toplink.classpath">

        <toplink:classpath refid = "mw.classpath" />
        <toplink:classpath refid = "mwplatforms.classpath" />

        <toplink:loginspec
            url = "jdbc:cloudscape:stagedb;create=true"
            driverclass = "COM.cloudscape.core.JDBCDriver"
            user = "scott"
            password="tiger" />
    </toplink:mappings.export>