Top Description Fields Constructors Methods
org.apache.tools.ant.taskdefs.optional.unix

public Class Symlink

extends DispatchTask
Class Inheritance
Imports
java.io.BufferedInputStream, .BufferedOutputStream, .File, .FileNotFoundException, .IOException, .InputStream, .PrintStream, java.nio.file.Files, .LinkOption, .Path, .Paths, java.util.ArrayList, .HashMap, .HashSet, .List, .Map, .Properties, .Set, java.util.stream.Stream, org.apache.tools.ant.BuildException, .DirectoryScanner, .Project, org.apache.tools.ant.dispatch.DispatchTask, .DispatchUtils, org.apache.tools.ant.taskdefs.LogOutputStream, org.apache.tools.ant.types.FileSet
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

Modifier and TypeField and Description
private boolean
executing

private boolean
failonerror

private List<FileSet>
fileSets

private String
link

private String
linkFileName

private boolean
overwrite

private String
resource

Constructor Summary

AccessConstructor and Description

Method Summary

Modifier and TypeMethod and Description
public void
addFileset(FileSet
The fileset to add.
set)

Add a fileset to this task.

public void
delete()

Delete a symlink.

public synchronized void
execute()

Overrides org.apache.tools.ant.Task.execute.

The standard method for executing any task.
private void
handleError(String
The message to log, or include in the BuildException.
msg)

Handle errors based on the setting of failonerror.

public void
init()

Overrides org.apache.tools.ant.Task.init.

Initialize the task.
public void
record()

Record symlinks.

public void
recreate()

Restore symlinks.

public void
setAction(String
The action to perform.
action)

Overrides org.apache.tools.ant.dispatch.DispatchTask.setAction.

Set the action to be performed.
private void
setDefaults()

Return all variables to their default state for the next invocation.

public void
setFailOnError(boolean
If true throw BuildException on error, else log it.
foe)

Set failonerror mode.

public void
setLinkfilename(String
The name of the file to write links to.
lf)

Set the name of the file to which links will be written.

public void
setOverwrite(boolean
If true overwrite existing links.
owrite)

Set overwrite mode.

public void
setResource(String
The resource to be linked.
src)

Set the name of the resource to which a link should be created.

public void
single()

Create a symlink.

private void
writePropertyFile(Properties
The properties object to be written.
properties, File
The directory for which we are writing the links.
dir)

Write a properties file.

Inherited from org.apache.tools.ant.dispatch.DispatchTask:
getActiongetActionParameterName

Field Detail

executingback to summary
private boolean executing
failonerrorback to summary
private boolean failonerror
fileSetsback to summary
private List<FileSet> fileSets
linkFileNameback to summary
private String linkFileName
overwriteback to summary
private boolean overwrite
resourceback to summary
private String resource

Constructor Detail

Symlinkback to summary
public Symlink()

Method Detail

addFilesetback to summary
public void addFileset(FileSet set)

Add a fileset to this task.

Parameters
set:FileSet

The fileset to add.

deleteback to summary
public void delete() throws BuildException

Delete a symlink.

Exceptions
BuildException:
on error.
Since
Ant 1.7
deleteSymlinkback to summary
public static void deleteSymlink(final 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:String

A string containing the path of the symlink to delete.

Annotations
@Deprecated
Exceptions
IOException:
If the deletion attempt fails
deleteSymlinkback to summary
public static void deleteSymlink(final 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:File

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

Annotations
@Deprecated
Exceptions
IOException:
If the attempt to delete runs into exception
deleteSymLinkback to summary
private static void deleteSymLink(final Path path) throws IOException
doLinkback to summary
private void doLink(String resource, String link) throws BuildException

Conduct the actual construction of a link.

Parameters
resource:String

The path of the resource we are linking to.

link:String

The name of the link we wish to make.

Exceptions
BuildException:
when things go wrong
executeback to summary
public synchronized void execute() throws BuildException

Overrides org.apache.tools.ant.Task.execute.

The standard method for executing any task.

Annotations
@Override
Exceptions
BuildException:
on error.
findLinksback to summary
private Set<File> findLinks(List<FileSet> fileSets)

Find all the links in all supplied filesets.

This method is invoked when the action attribute is "record". This means that filesets are interpreted as the directories in which links may be found.

Parameters
fileSets:List<FileSet>

The filesets specified by the user.

Returns:Set<File>

A Set of File objects containing the links (with canonical parent directories).

handleErrorback to summary
private void handleError(String msg)

Handle errors based on the setting of failonerror.

Parameters
msg:String

The message to log, or include in the BuildException.

Exceptions
BuildException:
with the message if failonerror=true
initback to summary
public void init() throws BuildException

Overrides org.apache.tools.ant.Task.init.

Initialize the task.

Annotations
@Override
Exceptions
BuildException:
on error.
loadLinksback to summary
private Properties loadLinks(List<FileSet> fileSets)

Load links from properties files included in one or more FileSets.

This method is only invoked when the action attribute is set to "recreate". The filesets passed in are assumed to specify the names of the property files with the link information and the subdirectories in which to look for them.

Parameters
fileSets:List<FileSet>

The FileSets for this task.

Returns:Properties

The links to be made.

recordback to summary
public void record() throws BuildException

Record symlinks.

Exceptions
BuildException:
on error.
Since
Ant 1.7
recreateback to summary
public void recreate() throws BuildException

Restore symlinks.

Exceptions
BuildException:
on error.
Since
Ant 1.7
setActionback to summary
public void setAction(String action)

Overrides org.apache.tools.ant.dispatch.DispatchTask.setAction.

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

Parameters
action:String

The action to perform.

Annotations
@Override
setDefaultsback to summary
private void setDefaults()

Return all variables to their default state for the next invocation.

Since
Ant 1.7
setFailOnErrorback to summary
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:boolean

If true throw BuildException on error, else log it.

setLinkback to summary
public void setLink(String link)

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

Parameters
link:String

The name for the link.

setLinkfilenameback to summary
public void setLinkfilename(String lf)

Set the name of the file to which links will be written. Used when action = "record".

Parameters
lf:String

The name of the file to write links to.

setOverwriteback to summary
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:boolean

If true overwrite existing links.

setResourceback to summary
public void setResource(String src)

Set the name of the resource to which a link should be created. Used when action = "single".

Parameters
src:String

The resource to be linked.

singleback to summary
public void single() throws BuildException

Create a symlink.

Exceptions
BuildException:
on error.
Since
Ant 1.7
writePropertyFileback to summary
private void writePropertyFile(Properties properties, File dir) throws BuildException

Write a properties file. This method uses Properties.store and thus may throw exceptions that occur while writing the file.

Parameters
properties:Properties

The properties object to be written.

dir:File

The directory for which we are writing the links.

Exceptions
BuildException:
if the property file could not be written