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

Class Symlink

java.lang.Object

org.apache.tools.ant.ProjectComponent

org.apache.tools.ant.Task

org.apache.tools.ant.dispatch.DispatchTask

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

All 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"/>
 

Note: Starting Ant version 1.10.2, this task relies on the symbolic link support introduced in Java 7 through the Files APIs.

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

Constructor Summary

Constructors

Constructor	Description
Symlink()

Method Summary

Modifier and Type	Method	Description
void	addFileset(FileSet set)	Add a fileset to this task.
void	delete()	Delete a symlink.
static void	deleteSymlink(File linkfil)	Deprecated. use Files.delete(Path) instead
static void	deleteSymlink(String path)	Deprecated. use Files.delete(Path) instead
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 link)	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

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

bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, 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, setDescription, setLocation, setProject

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Symlink

public Symlink()

Method Details

init

public void init()
          throws BuildException

Initialize the task.

Overrides:

init in class Task

Throws:

BuildException - on error.

execute

public void execute()
             throws BuildException

The standard method for executing any task.

Overrides:

execute in class Task

Throws:

BuildException - on error.

single

public void single()
            throws BuildException

Create a symlink.

Throws:

BuildException - on error.

Since:

Ant 1.7

delete

public void delete()
            throws BuildException

Delete a symlink.

Throws:

BuildException - on error.

Since:

Ant 1.7

recreate

public void recreate()
              throws BuildException

Restore symlinks.

Throws:

BuildException - on error.

Since:

Ant 1.7

record

public void record()
            throws BuildException

Record symlinks.

Throws:

BuildException - on error.

Since:

Ant 1.7

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.

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.

setAction

public void setAction(String action)

Set the action to be performed. May be "single", "delete", "recreate" or "record".

Overrides:

setAction in class DispatchTask

Parameters:

action - The action to perform.

setLink

public void setLink(String link)

Set the name of the link. Used when action = "single".

Parameters:

link - The name for the link.

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.

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.

addFileset

public void addFileset(FileSet set)

Add a fileset to this task.

Parameters:

set - The fileset to add.

deleteSymlink

@Deprecated
public static void deleteSymlink(String path)
                          throws IOException

Deprecated.

use Files.delete(Path) instead

Delete a symlink (without deleting the associated resource).

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

Parameters:

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

Throws:

IOException - If the deletion attempt fails

deleteSymlink

@Deprecated
public static void deleteSymlink(File linkfil)
                          throws IOException

Deprecated.

use Files.delete(Path) instead

Delete a symlink (without deleting the associated resource).

This is a utility method that removes a 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 and instead this method returns silently.

Since Ant 1.10.2 this method relies on the Files.isSymbolicLink(Path) and Files.delete(Path) to check and delete the symlink

Parameters:

linkfil - A File object of the symlink to delete. Cannot be null.

Throws:

IOException - If the attempt to delete runs into exception