Pathconvert

Description

Converts a nested path, path reference, or fileset reference to the form usable on a specified platform and stores the result in a given property. This operation is useful when script files (batch files or shell scripts) must be generated my the build system and they contain path information that must be properly formatted for the target architecture, not the architecture on which the build is running, or when you need to create a list of files separated by a given character, like a comma or a space.

Prefix maps can be specified to map Windows drive letters to Unix paths and vice versa.

Parameters

Attribute Description Required
targetos The target architecture. Must be one of 'unix' or 'windows'.
This is a shorthand mechanism for specifying both pathsep and dirsep according to the specified target architecture. 		Must specify one of targetos, pathsep,or dirsep.
dirsep The character to use as the directory separator in the generated paths. No, defaults to current JVM File.separator
pathsep The character to use as the path element separator in the generated paths. No, defaults to current JVM File.pathSeparator
property The name of the property in which to place the converted path Yes
refid What to convert, given as a reference to a PATH or FILESET defined elsewhere No, if omitted a nested <path> element must be supplied.

Parameters specified as nested elements

map

Specifies the mapping of path prefixes between Unix and Windows.

Attribute Description Required
from The prefix to match. Note that this value is case insensitive when the build is running on a windows platform and case sensitive when running on a Unix platform. Yes
to The replacement text to use when from is matched. Yes

Each map element specifies a single replacement map to be applied to the elements of the path being processed. If no map entries are specified, then no path prefix mapping is performed.

Note that the map elements are applied in the order specified and the only the first matching map element is applied. So, the ordering of your map elements can be important if any from values are prefixes of other from values.

path

If a path reference is not supplied using the refid attribute, then a nested path element must be supplied. See Path-like Structures for details.

Examples

In the examples below, assume that the property wl.home has the value d:\weblogic on Windows and /weblogic on Unix.

Example 1

    <path id="wl.path">
      <pathelement location="${wl.home}/lib/weblogicaux.jar" />
      <pathelement location="${wl.home}/classes" />
      <pathelement location="${wl.home}/mssqlserver4/classes" />
      <pathelement location="c:\winnt\System32" />
    </path>
    
    <pathconvert targetos="unix" property="newpath" refid="wl.path"/>

Assuming wl.property has the value "d:\weblogic", will generate the path shown below and store it in the property named newpath 

/weblogic/lib/weblogicaux.jar:/weblogic/classes:/weblogic/mssqlserver4/classes:/WINNT/SYSTEM32
Note that the drive letters have been removed. This is the default behavior when no map elements have been specified.

Example 2

    
    <pathconvert targetos="unix" property="newpath" >
      <path id="wl.path">
        <pathelement location="${wl.home}/lib/weblogicaux.jar" />
        <pathelement location="${wl.home}/classes" />
        <pathelement location="${wl.home}/mssqlserver4/classes" />
        <pathelement location="c:\winnt\System32" />
      </path>
    </pathconvert>
This generates the exact same path as the previous example. It demonstrates the use of a nested path element.

Example 3

    <pathconvert targetos="unix" property="newpath" refid="wl.path">
      <map from="d:" to="/foo"/>
      <map from="c:" to="/bar"/>
    </pathconvert>

This example specifies two map entries that will convert path elements that start with c: to /dos and d: to /. The resulting path is shown below.

/weblogic/lib/weblogicaux.jar:/weblogic/classes:/weblogic/mssqlserver4/classes:/dos/WINNT/SYSTEM32

Example 4

    <pathconvert targetos="windows" property="newpath" >
      <path id="wl.path">
        <pathelement location="${wl.home}/lib/weblogicaux.jar" />
        <pathelement location="${wl.home}/classes" />
        <pathelement location="${wl.home}/mssqlserver4/classes" />
        <pathelement location="/dos/winnt/System32" />
      </path>
      <map from="/dos" to="c:\"/>
      <map from="/" to="d:\"/>
    </pathconvert>

This example, similar to the one above but targetting windows, specifies two map entries that will convert path elements that start with /dos to c:\ and / to d:\. Note that the order of the map elements was important here since / is a prefix of /dos. The resulting path is shown below.

d:\weblogic\lib\weblogicaux.jar;d:\weblogic\classes;d:\weblogic\mssqlserver4\classes;c:\WINNT\SYSTEM32

Example 5

    <fileset dir="${src.dir}" id="src.files">
      <include name="**/*.java"/>
    </fileset>
  
    <pathconvert pathsep="," property="javafiles" refid="src.files"/>

This example takes the set of files determined by the fileset (all files ending in .java), joins them together separated by commas, and places the resulting list into the property javafiles. The directory separator is not specified, so it defaults to the appropriate character for the current platform. Such a list could then be used in another task, like javadoc, that requires a comma separated list of files.