Symlink (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.taskdefs.optional.unix, class: Symlink

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