org.apache.tools.ant.taskdefs.optional.unix

Class Symlink

Implemented Interfaces:
Cloneable, Dispatchable

public class Symlink
extends DispatchTask

Creates, Deletes, Records and Restores Symlinks.

This task performs several related operations. In the most trivial and default usage, it creates a link specified in the link attribute to a resource specified in the resource attribute. The second usage of this task is to traverse a directory structure specified by a fileset, and write a properties file in each included directory describing the links found in that directory. The third usage is to traverse a directory structure specified by a fileset, looking for properties files (also specified as included in the fileset) and recreate the links that have been previously recorded for each directory. Finally, it can be used to remove a symlink without deleting the associated resource.

Usage examples:

Make a link named "foo" to a resource named "bar.foo" in subdir:

 <symlink link="${dir.top}/foo" resource="${dir.top}/subdir/bar.foo"/>
 

Record all links in subdir and its descendants in files named "dir.links":

 <symlink action="record" linkfilename="dir.links">
    <fileset dir="${dir.top}" includes="subdir/**" />
 </symlink>
 

Recreate the links recorded in the previous example:

 <symlink action="recreate">
    <fileset dir="${dir.top}" includes="subdir/**/dir.links" />
 </symlink>
 

Delete a link named "foo" to a resource named "bar.foo" in subdir:

 <symlink action="delete" link="${dir.top}/foo"/>
 

LIMITATIONS: Because Java has no direct support for handling symlinks this task divines them by comparing canonical and absolute paths. On non-unix systems this may cause false positives. Furthermore, any operating system on which the command ln -s link resource is not a valid command on the command line will not be able to use action="delete", action="single" or action="recreate", but action="record" should still work. Finally, the lack of support for symlinks in Java means that all links are recorded as links to the canonical resource name. Therefore the link: link --> subdir/dir/../foo.bar will be recorded as link=subdir/foo.bar and restored as link --> subdir/foo.bar.

Field Summary

Fields inherited from class org.apache.tools.ant.Task

target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

description, location, project

Method Summary

void
addFileset(FileSet set)
Add a fileset to this task.
void
delete()
Delete a symlink.
static void
deleteSymlink(File linkfil)
Delete a symlink (without deleting the associated resource).
static void
deleteSymlink(String path)
Delete a symlink (without deleting the associated resource).
void
execute()
The standard method for executing any task.
void
init()
Initialize the task.
void
record()
Record symlinks.
void
recreate()
Restore symlinks.
void
setAction(String action)
Set the action to be performed.
void
setFailOnError(boolean foe)
Set failonerror mode.
void
setLink(String lnk)
Set the name of the link.
void
setLinkfilename(String lf)
Set the name of the file to which links will be written.
void
setOverwrite(boolean owrite)
Set overwrite mode.
void
setResource(String src)
Set the name of the resource to which a link should be created.
void
single()
Create a symlink.

Methods inherited from class org.apache.tools.ant.dispatch.DispatchTask

getAction, getActionParameterName, setAction

Methods inherited from class org.apache.tools.ant.Task

bindToOwner, execute, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

clone, getDescription, getLocation, getProject, log, log, setDescription, setLocation, setProject

Method Details

addFileset

public void addFileset(FileSet set)
Add a fileset to this task.
Parameters:
set - The fileset to add.

delete

public void delete()
            throws BuildException
Delete a symlink.
Throws:
BuildException - on error.
Since:
Ant 1.7

deleteSymlink

public static void deleteSymlink(File linkfil)
            throws IOException,
                   FileNotFoundException
Delete a symlink (without deleting the associated resource).

This is a utility method that removes a unix symlink without removing the resource that the symlink points to. If it is accidentally invoked on a real file, the real file will not be harmed, but an exception will be thrown when the deletion is attempted. This method works by getting the canonical path of the link, using the canonical path to rename the resource (breaking the link) and then deleting the link. The resource is then returned to its original name inside a finally block to ensure that the resource is unharmed even in the event of an exception.

Parameters:
linkfil - A File object of the symlink to delete.

deleteSymlink

public static void deleteSymlink(String path)
            throws IOException,
                   FileNotFoundException
Delete a symlink (without deleting the associated resource).

This is a convenience method that simply invokes deleteSymlink(java.io.File).

Parameters:
path - A string containing the path of the symlink to delete.

execute

public void execute()
            throws BuildException
The standard method for executing any task.
Overrides:
execute in interface Task
Throws:
BuildException - on error.

init

public void init()
            throws BuildException
Initialize the task.
Overrides:
init in interface Task
Throws:
BuildException - on error.

record

public void record()
            throws BuildException
Record symlinks.
Throws:
BuildException - on error.
Since:
Ant 1.7

recreate

public void recreate()
            throws BuildException
Restore symlinks.
Throws:
BuildException - on error.
Since:
Ant 1.7

setAction

public void setAction(String action)
Set the action to be performed. May be "single", "delete", "recreate" or "record".
Overrides:
setAction in interface DispatchTask
Parameters:
action - The action to perform.

setFailOnError

public void setFailOnError(boolean foe)
Set failonerror mode. If set to true (default) the entire build fails upon error; otherwise the error is logged and the build will continue.
Parameters:
foe - If true throw BuildException on error, else log it.

setLink

public void setLink(String lnk)
Set the name of the link. Used when action = "single".
Parameters:
lnk - The name for the link.

setLinkfilename

public void setLinkfilename(String lf)
Set the name of the file to which links will be written. Used when action = "record".
Parameters:
lf - The name of the file to write links to.

setOverwrite

public void setOverwrite(boolean owrite)
Set overwrite mode. If set to false (default) the task will not overwrite existing links, and may stop the build if a link already exists depending on the setting of failonerror.
Parameters:
owrite - If true overwrite existing links.

setResource

public void setResource(String src)
Set the name of the resource to which a link should be created. Used when action = "single".
Parameters:
src - The resource to be linked.

single

public void single()
            throws BuildException
Create a symlink.
Throws:
BuildException - on error.
Since:
Ant 1.7