Creates, 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 file or directory it points
to.
Examples of use:
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
.
addFileset
public void addFileset(FileSet set)
Add a fileset to this task.
set
- The fileset to add.
deleteSymlink
public static void deleteSymlink(File linkfil)
throws IOException,
FileNotFoundException
Deletes a symlink without deleting the resource it points to.
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, but an exception
will be thrown when the deletion is attempted. 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.
linkfil
- A File
object of the symlink to delete.
deleteSymlink
public static void deleteSymlink(String path)
throws IOException,
FileNotFoundException
Deletes a symlink without deleting the resource it points to.
This is a convenience method that simply invokes
deleteSymlink(java.io.File)
.
path
- A string containing the path of the symlink to delete.
setAction
public void setAction(String typ)
Set the action to be performed. May be
"single", "multi" or "record".
typ
- The action to perform.
setFailOnError
public void setFailOnError(boolean foe)
The setter for the failonerror attribute. If set to true (default)
the entire build fails upon error. If set to false, the error is
logged and the build will continue.
foe
- If true throw BuildException on error else log it.
setLink
public void setLink(String lnk)
Set the same of the link.
Only used when action = "single".
lnk
- The name for the link.
setLinkfilename
public void setLinkfilename(String lf)
Set the name of the file to which links will be written.
Only used when action = "record".
lf
- The name of the file to write links to.
setOverwrite
public void setOverwrite(boolean owrite)
The setter for the overwrite attribute. 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.
owrite
- If true overwrite existing links.
setResource
public void setResource(String src)
Set the name of the resource to which a link should be created.
Only used when action = "single".
src
- The resource to be linked.