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.taskdefs.optional.unix.Symlink

public class Symlink
extends Task

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 atribute to a resource specified in the resource atribute. The second usage of this task is to traverses 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 it's 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 canoniacal 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 comandline 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

Version:
$Revision: 1.12.2.6 $

Field Summary
 
Fields inherited from class org.apache.tools.ant.Task
description, location, target, taskName, taskType, wrapper
 
Fields inherited from class org.apache.tools.ant.ProjectComponent
project
 
Constructor Summary
Symlink()
           
 
Method Summary
 void addFileset(FileSet set)
          Adds a fileset to this task.
static void deleteSymlink(java.io.File linkfil)
          Deletes a symlink without deleteing the resource it points to.
static void deleteSymlink(java.lang.String path)
          Deletes a symlink without deleteing the resource it points to.
 void execute()
          The standard method for executing any task.
 void init()
          Initialize the task.
 void setAction(java.lang.String typ)
          The setter for the "action" attribute.
 void setFailOnError(boolean foe)
          The setter for the failonerror atribute.
 void setLink(java.lang.String lnk)
          The setter for the "link" attribute.
 void setLinkfilename(java.lang.String lf)
          The setter for the "linkfilename" attribute.
 void setOverwrite(boolean owrite)
          The setter for the overwrite atribute.
 void setResource(java.lang.String src)
          The setter for the "resource" attribute.
 
Methods inherited from class org.apache.tools.ant.Task
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject, setProject
 
Methods inherited from class java.lang.Object
clone, 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 - if something goes wrong with the build

execute

public void execute()
             throws BuildException
The standard method for executing any task.

Overrides:
execute in class Task
Throws:
BuildException - if something goes wrong with the build

setOverwrite

public void setOverwrite(boolean owrite)
The setter for the overwrite atribute. 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)
The setter for the failonerror atribute. If set to true (default) the entire build fails upon error. If set to false, the error is logged and the build will continue.

Parameters:
foe - If true throw build exception on error else log it.

setAction

public void setAction(java.lang.String typ)
The setter for the "action" attribute. May be "single" "multi" or "record"

Parameters:
typ - The action of action to perform

setLink

public void setLink(java.lang.String lnk)
The setter for the "link" attribute. Only used for action = single.

Parameters:
lnk - The name for the link

setResource

public void setResource(java.lang.String src)
The setter for the "resource" attribute. Only used for action = single.

Parameters:
src - The source of the resource to be linked.

setLinkfilename

public void setLinkfilename(java.lang.String lf)
The setter for the "linkfilename" attribute. Only used for action=record.

Parameters:
lf - The name of the file to write links to.

addFileset

public void addFileset(FileSet set)
Adds a fileset to this task.

Parameters:
set - The fileset to add.

deleteSymlink

public static void deleteSymlink(java.lang.String path)
                          throws java.io.IOException,
                                 java.io.FileNotFoundException
Deletes a symlink without deleteing the resource it points to.

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

public static void deleteSymlink(java.io.File linkfil)
                          throws java.io.IOException,
                                 java.io.FileNotFoundException
Deletes a symlink without deleteing 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 it's original name inside a finally block to ensure that the resource is unharmed even in the event of an exception.

Parameters:
linkfil - A File object 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, File.delete or File.getCanonicalPath fail.


Copyright © 2000-2004 Apache Software Foundation. All Rights Reserved.