Symlink (Apache Ant API)
Date: 2016-04-09

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:
    java.lang.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`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Symlink()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addFileset(FileSet set)` Add a fileset to this task.
    `void` | `delete()` Delete a symlink.
    `static void` | `deleteSymlink(java.io.File linkfil)` Deprecated. use org.apache.tools.ant.util.SymbolicLinkUtils#deleteSymbolicLink instead
    `static void` | `deleteSymlink(java.lang.String path)` Deprecated. use org.apache.tools.ant.util.SymbolicLinkUtils#deleteSymbolicLink 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(java.lang.String action)` Set the action to be performed.
    `void` | `setFailOnError(boolean foe)` Set failonerror mode.
    `void` | `setLink(java.lang.String lnk)` Set the name of the link.
    `void` | `setLinkfilename(java.lang.String lf)` Set the name of the file to which links will be written.
    `void` | `setOverwrite(boolean owrite)` Set overwrite mode.
    `void` | `setResource(java.lang.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 Detail

    - #### Symlink

          public Symlink()

  - ### Method Detail

    - #### 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(java.lang.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(java.lang.String lnk)

      Set the name of the link. Used when action = "single".
      Parameters:
        `lnk` - The name for the link.

    - #### setResource

          public void setResource(java.lang.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(java.lang.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(java.lang.String path)
                                    throws java.io.IOException,
                                           java.io.FileNotFoundException

      Deprecated. use org.apache.tools.ant.util.SymbolicLinkUtils#deleteSymbolicLink instead
      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.
      Throws:
        `java.io.FileNotFoundException` - When the path results in a `File` that doesn't exist.
        `java.io.IOException` - If calls to `File.rename` or `File.delete` fail.

    - #### deleteSymlink

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

      Deprecated. use org.apache.tools.ant.util.SymbolicLinkUtils#deleteSymbolicLink instead
      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.

      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.

      Since Ant 1.8.0 this method will try to delete the File object if it reports it wouldn't exist (as symlinks pointing nowhere usually do). Prior version would throw a FileNotFoundException in that case.

      Parameters:
        `linkfil` - A `File` object of the symlink to delete.
      Throws:
        `java.io.IOException` - If calls to `File.rename`, `File.delete` or `File.getCanonicalPath` fail.