org.entityfs.cap.symlink.util
Class DCSymbolicLinkUtil

java.lang.Object
  org.entityfs.cap.symlink.util.DCSymbolicLinkUtil

public final class DCSymbolicLinkUtil
extends Object

This utility class contains static methods for working with Directory :s that support the DCSymbolicLink capability.

The methods in this class will use the locking strategy for utility classes described in EntityLock.

Since:

1.0

Author:

Karl Gustafsson

In_jar:

entityfs-symlink

Method Summary

static DCSymbolicLink	getCapability(DirectoryView dv) Get the DCSymbolicLink capability for a directory.
static SymbolicLinkView	getSymbolicLink(EntityHolder eh, RelativeLocation rl) Get the symbolic link with the given location relative to the entity holder.
static SymbolicLinkView	getSymbolicLink(EntityHolder eh, String name) Get the symbolic link with the given name from an entity holder.
static SymbolicLinkView	getSymbolicLinkOrNull(EntityHolder eh, RelativeLocation rl) Get an existing symbolic link with the given location relative to the entity holder, returning null if the symbolic link does not exist or if it has been made invisible by view filters.
static SymbolicLinkView	getSymbolicLinkOrNull(EntityHolder eh, String name) Get an existing symbolic link from the holder, returning null if the symbolic link does not exist or if it has been made invisible by view filters.
static SymbolicLinkView	newAbsoluteSymbolicLink(EntityAcceptingEntityView<?> parent, String name, EntityView target) Create a new absolute symbolic link pointing to the current location of the supplied entity.
static SymbolicLinkView	newRelativeSymbolicLink(EntityAcceptingEntityView<?> parent, String name, EntityView target) Create a new relative symbolic link pointing to the current location of the supplied entity.
static SymbolicLinkView	newSymbolicLink(EntityAcceptingEntityView<?> parent, String name, EntityLocation<?> target) Create a new symbolic link in the directory.
static boolean	supportsSymbolicLinks(DirectoryView dv) Check if the directory supports the DCSymbolicLink capability.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newSymbolicLink

public static SymbolicLinkView newSymbolicLink(EntityAcceptingEntityView<?> parent,
                                               String name,
                                               EntityLocation<?> target)
                                        throws NotADirectoryException,
                                               UnsupportedCapabilityException

Create a new symbolic link in the directory. If the symbolic link is created in a directory view, the returned view will inherit all the directory view's filters.

Entity locks that this method will acquire (temporarily):

• A write lock for the parent directory.
• Read locks for all entities needed to dereference the parent entity. (If the parent entity is an entity-accepting entity that is not a directory (a symbolic link).)

Parameters:

parent - An entity-accepting entity that can be dereferenced to the directory where the symbolic link will be created.

name - The name of the symbolic link.

target - The symbolic link target. The target can be a RelativeLocation or an AbsoluteLocation.

Returns:

The new symbolic link.

Throws:

NotADirectoryException - If the parent argument cannot be dereferenced to a directory.

UnsupportedCapabilityException - If the parent directory does not support the DCSymbolicLink capability.

newRelativeSymbolicLink

public static SymbolicLinkView newRelativeSymbolicLink(EntityAcceptingEntityView<?> parent,
                                                       String name,
                                                       EntityView target)
                                                throws NotADirectoryException,
                                                       UnsupportedCapabilityException

Create a new relative symbolic link pointing to the current location of the supplied entity. If the symbolic link is created in a directory view, the returned view will inherit all the directory view's filters.

Entity locks that this method will acquire (temporarily):

• A write lock for the parent directory.
• Read locks for all entities needed to dereference the parent entity. (If the parent entity is an entity-accepting entity that is not a directory (a symbolic link).)
• Read locks for all entities needed to create the target's location relative to the parent directory.

Parameters:

parent - An entity-accepting entity that can be dereferenced to the directory where the symbolic link will be created.

name - The name of the symbolic link.

target - The entity that will be referenced by the created relative symbolic link.

Returns:

A relative symbolic link.

Throws:

NotADirectoryException - If the parent argument cannot be dereferenced to a directory.

UnsupportedCapabilityException - If the parent directory does not support the DCSymbolicLink capability.

newAbsoluteSymbolicLink

public static SymbolicLinkView newAbsoluteSymbolicLink(EntityAcceptingEntityView<?> parent,
                                                       String name,
                                                       EntityView target)
                                                throws NotADirectoryException,
                                                       UnsupportedCapabilityException

Create a new absolute symbolic link pointing to the current location of the supplied entity. If the symbolic link is created in a directory view, the returned view will inherit all the directory view's filters.

Entity locks that this method will acquire (temporarily):

• A write lock for the parent directory.
• Read locks for all entities needed to dereference the parent entity. (If the parent entity is an entity-accepting entity that is not a directory (a symbolic link).)
• Read locks for all entities needed to create the absolute location of the link target. This will include read locking the file system's root directory.

Parameters:

parent - An entity-accepting entity that can be dereferenced to the directory where the symbolic link will be created.

name - The name of the symbolic link.

target - The entity that will be referenced by the created absolute symbolic link.

Returns:

An absolute symbolic link.

Throws:

NotADirectoryException - If the parent argument cannot be dereferenced to a directory.

UnsupportedCapabilityException - If the parent directory does not support the DCSymbolicLink capability.

getSymbolicLink

public static SymbolicLinkView getSymbolicLink(EntityHolder eh,
                                               String name)
                                        throws EntityNotFoundException,
                                               AccessDeniedException,
                                               NotASymbolicLinkException

Get the symbolic link with the given name from an entity holder.

Parameters:

eh - The entity holder containing the symbolic link.

name -

Returns:

The symbolic link or symbolic link view.

Throws:

EntityNotFoundException - If no entity with the supplied name exists in the directory.

AccessDeniedException - If the calling thread lacks proper access rights.

NotASymbolicLinkException - If an entity with the supplied name was found, but it was not a symbolic link.

Permissions_required:

Execute access.

getSymbolicLink

public static SymbolicLinkView getSymbolicLink(EntityHolder eh,
                                               RelativeLocation rl)
                                        throws EntityNotFoundException,
                                               AccessDeniedException,
                                               NotASymbolicLinkException,
                                               IllegalArgumentException

Get the symbolic link with the given location relative to the entity holder. If this is called with a symbolic link view argument, the returned symbolic link view uses the same filter instances as the provided symbolic link view.

If this method is called with a SymbolicLink argument, the result can safely be cast to SymbolicLink.

Parameters:

eh - The entity holder, for instance a directory or directory view.

rl - The relative location of the symbolic link compared with the holder's. If this is called on a non-entity holder, this location cannot reference the holder or a location above the holder.

Returns:

The symbolic link or symbolic link view.

Throws:

EntityNotFoundException - If the symbolic link does not exist or if it has been made invisible by view filters.

AccessDeniedException - If the client does not have execute access to the entity holder.

NotASymbolicLinkException - If the found entity is not a symbolic link.

IllegalArgumentException - If this is called with a location that references a non-entity entity holder or a location above an entity holder, i.e. an entity holder that does not implement EntityView. (Referencing entities or parents of entities are allowed.)

Permissions_required:

Execute access to all directories visited while finding the target entity.

getSymbolicLinkOrNull

public static SymbolicLinkView getSymbolicLinkOrNull(EntityHolder eh,
                                                     String name)
                                              throws AccessDeniedException,
                                                     NotASymbolicLinkException

Get an existing symbolic link from the holder, returning null if the symbolic link does not exist or if it has been made invisible by view filters.

If this is called with a directory view argument, a symbolic link view that is identical to the supplied directory view (same filter instances) is returned.

Parameters:

eh - The entity holder, for instance a directory or directory view.

name - The name of the symbolic link.

Returns:

The symbolic link or null if it does not exist or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the client does not have execute access to the entity holder.

NotASymbolicLinkException - If the entity exists but is not a symbolic link.

Permissions_required:

Execute access.

getSymbolicLinkOrNull

public static SymbolicLinkView getSymbolicLinkOrNull(EntityHolder eh,
                                                     RelativeLocation rl)
                                              throws AccessDeniedException,
                                                     NotASymbolicLinkException,
                                                     IllegalArgumentException

Get an existing symbolic link with the given location relative to the entity holder, returning null if the symbolic link does not exist or if it has been made invisible by view filters.

If this method is called with a directory view argument, the returned symbolic link is an identical (same filter instances) view of the requested symbolic link.

Parameters:

eh - The entity holder, for instance a directory or directory view.

rl - The relative location of the symbolic link compared with the holder's. If this is called on a non-entity holder, this location cannot reference the holder or a location above the holder.

Returns:

The symbolic link or null if it does not exist or has been made invisible by view filters.

Throws:

AccessDeniedException - If the client does not have execute access to directories needed to find the target entity.

NotASymbolicLinkException - If the entity exists but is not a symbolic link.

IllegalArgumentException - If this is called with a location that references a non-entity entity holder or a location above an entity holder, i.e. an entity holder that does not implement EntityView. (Referencing entities or parents of entities are allowed.)

Permissions_required:

Execute access to all directories visited while finding the target entity.

getCapability

public static DCSymbolicLink getCapability(DirectoryView dv)
                                    throws UnsupportedCapabilityException

Get the DCSymbolicLink capability for a directory.

Parameters:

dv - The directory to get the capability for.

Returns:

The capability.

Throws:

UnsupportedCapabilityException - If the directory does not support the capability.

supportsSymbolicLinks

public static boolean supportsSymbolicLinks(DirectoryView dv)

Check if the directory supports the DCSymbolicLink capability.

Parameters:

dv - The directory to investigate.

Returns:

true if the directory supports the capability, false otherwise.