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