com.perforce.p4java.impl.generic.sys
Interface ISystemFileCommandsHelper

All Known Implementing Classes:

RpcSystemFileCommandsHelper, SymbolicLinkHelper

public interface ISystemFileCommandsHelper

An interface that specifies a set of useful file-level functions (such as recognizing a symbolic link or setting writable or executable bits) that are not always implemented by vanilla Java installations, and that can be used by P4Java to implement these file operations when the surrounding JVm or JDK does not do a good job.

Java native P4Java implementations have to cope with the fact that most vanilla JDK 5 implementations have poor or even non-existent support for file-level metadata manipulations; JDK 6 is not much better, but does allow you to set a file writable and executable (albeit without honoring the Unix umask settings). In order to allow JDK 5 installations to use the P4Java NIO / RPC implementations, this interface is provided in conjunction with the server factory's setRpcFileSystemHelper method to allow users to specify a helper class (or classes) that implement these functions using native libraries or external functions (such as Eclipse's file helpers). Note that this class can be safely ignored if you are using the p4 command line protocol implementation, and can typically be ignored with all protocol implementations if you are using JDK 6 or later.

Methods here concentrate on mundane file mode changes and metadata, mostly, but may be added to as time goes by. The semantics of the individual methods below are intended to be the same as those for the corresponding methods defined on JDK 6's File class (where they exist), with broad interpretations allowed.

Note that all methods defined below must be implemented in a thread-safe way and not cause undue thread blocking, as they're called at crucial stages of the underlying RPC implementation. Note also that the supplied SystemFileCommands implementation must work safely even if it's just instantiated once per P4Java installation for all requests (i.e. it must work as a singleton).

setWritable

boolean setWritable(String fileName,
                    boolean writable)

Set the file's permissions to allow or disallow writing to it.

Parameters:

fileName - non-null path or name of the target file.

writable - if true, allow the file to be written to; if false, set the file read-only (or, more accurately, not writable).

Returns:

true iff the set permission operation succeeded. May return false if the file didn't exist or the operation failed or an exception was caught, etc.

setReadable

boolean setReadable(String fileName,
                    boolean readable,
                    boolean ownerOnly)

Set the file's permissions to allow or disallow reading from it.

Parameters:

fileName - non-null path or name of the target file. set the file read-only.

readable - if true, allow the file to be read; if false, set the file to not be readable

ownerOnly - true to only set the read-only bit for the owner

Returns:

true iff the set permission operation succeeded. May return false if the file didn't exist or the operation failed or an exception was caught, etc.

setOwnerReadOnly

boolean setOwnerReadOnly(String fileName)

Set the file's read permissions only allow reading by owner.

Parameters:

fileName - non-null path or name of the target file. set the file read-only.

Returns:

true iff the set permission operation succeeded. May return false if the file didn't exist or the operation failed or an exception was caught, etc.

setExecutable

boolean setExecutable(String fileName,
                      boolean executable,
                      boolean ownerOnly)

Set the file's permissions to allow or disallow it to be executed.

Parameters:

fileName - non-null path or name of the target file.

executable - if true, allow the file to be executed; if false, set the file not executable.

ownerOnly - true to only set the executable bit for the owner

Returns:

true iff the set permission operation succeeded. May return false if the file didn't exist or the operation failed or an exception was caught, etc.

canExecute

boolean canExecute(String fileName)

Return true iff the file exists and is executable.

Parameters:

fileName - non-null path or name of the target file.

Returns:

true iff the file existed and is executable.

isSymlink

boolean isSymlink(String fileName)

Return true iff the file exists and is a symbolic link.

This method is guaranteed to only be called when we suspect a specific file may be a symbolic link (i.e. we've exhausted other possibilities) and it is safe for this method to return false if it can't implement the associated plumbing or it simply can't tell whether the file is a symlink or not.

Parameters:

fileName - non-null path or name of the target file.

Returns:

true iff the file exists and is a symbolic link.