Symlink (Apache Ant API)

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

  Since Ant 1.10.16 `<delete link=...>` can be used as an alterantive to the "delete" action.

  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

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | 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 `Files.delete(Path)` instead
    `static void` | `deleteSymlink​(java.lang.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​(java.lang.String action)` | Set the action to be performed.
    `void` | `setFailOnError​(boolean foe)` | Set failonerror mode.
    `void` | `setLink​(java.lang.String link)` | 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 link)

      Set the name of the link. Used when action = "single".
      Parameters:
        `link` - 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

      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:
        `java.io.IOException` - If the deletion attempt fails

    - #### deleteSymlink

          @Deprecated
          public static void deleteSymlink​(java.io.File linkfil)
                                    throws java.io.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:
        `java.io.IOException` - If the attempt to delete runs into exception