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>