org.eclipse.jgit.util

Class FS

java.lang.Object

org.eclipse.jgit.util.FS

Direct Known Subclasses:

FS_POSIX, FS_Win32

public abstract class FS
extends Object

Abstraction to support various file system operations not in Java.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FS.Attributes File attributes we typically care for.
static class	FS.FSFactory This class creates FS instances.

Field Summary

Fields

Modifier and Type	Field and Description
static FS	DETECTED The auto-detected implementation selected for this operating system and JRE.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FS() Constructs a file system abstraction.
protected	FS(FS src) Initialize this FS using another's current settings.

Method Summary

Methods

Modifier and Type	Method and Description
abstract boolean	canExecute(File f) Determine if the file is executable (or not).
void	createSymLink(File path, String target) Create a symbolic link
void	delete(File f) Delete a file.
static FS	detect() Auto-detect the appropriate file system abstraction.
static FS	detect(Boolean cygwinUsed) Auto-detect the appropriate file system abstraction, taking into account the presence of a Cygwin installation on the system.
protected abstract File	discoverGitPrefix()
boolean	exists(File path) Tests if the path exists, in case of a symbolic link, true even if the target does not exist
File	findHook(Repository repository, Hook hook) Tries to find a hook matching the given one in the given repository.
FS.Attributes	getAttributes(File path)
File	gitPrefix()
protected ProcessResult	internalRunIfPresent(Repository repository, Hook hook, String[] args, PrintStream outRedirect, PrintStream errRedirect, String stdinArgs) See runIfPresent(Repository, Hook, String[], PrintStream, PrintStream, String) .
abstract boolean	isCaseSensitive() Is this file system case sensitive
boolean	isDirectory(File path) Check if path is a directory.
boolean	isFile(File path) Examine if path represents a regular file.
boolean	isHidden(File path)
boolean	isSymLink(File path)
long	lastModified(File f) Get the last modified time of a file system object.
long	length(File path) Get the length of a file or link, If the OS/JRE supports symbolic links it's the length of the link, else the length of the target.
abstract FS	newInstance()
File	normalize(File file) Normalize the unicode path to composed form.
String	normalize(String name) Normalize the unicode path to composed form.
protected static String	readPipe(File dir, String[] command, String encoding) Execute a command and return a single line of output as a String
String	readSymLink(File path) Check if a file is a symbolic link and read it
String	relativize(String base, String other) See FileUtils.relativize(String, String).
File	resolve(File dir, String name) Resolve this file to its actual path name that the JRE can use.
abstract boolean	retryFailedLockFileCommit() Does this file system have problems with atomic renames?
ProcessResult	runIfPresent(Repository repository, Hook hook, String[] args) Checks whether the given hook is defined for the given repository, then runs it with the given arguments.
ProcessResult	runIfPresent(Repository repository, Hook hook, String[] args, PrintStream outRedirect, PrintStream errRedirect, String stdinArgs) Checks whether the given hook is defined for the given repository, then runs it with the given arguments.
abstract ProcessBuilder	runInShell(String cmd, String[] args) Initialize a ProcesssBuilder to run a command using the system shell.
protected int	runProcess(ProcessBuilder hookProcessBuilder, OutputStream outRedirect, OutputStream errRedirect, String stdinArgs) Runs the given process until termination, clearing its stdout and stderr streams on-the-fly.
protected static File	searchPath(String path, String... lookFor) Searches the given path to see if it contains one of the given files.
abstract boolean	setExecute(File f, boolean canExec) Set a file to be executable by the user.
FS	setGitPrefix(File path) Set the $prefix directory C Git uses.
void	setHidden(File path, boolean hidden) Set the hidden attribute for file whose name starts with a period.
void	setLastModified(File f, long time) Set the last modified time of a file system object.
FS	setUserHome(File path) Set the user's home directory location.
abstract boolean	supportsExecute() Does this operating system and JRE support the execute flag on files?
boolean	supportsSymlinks() Does this operating system and JRE supports symbolic links.
File	userHome() Determine the user's home directory (location where preferences are).
protected File	userHomeImpl() Determine the user's home directory (location where preferences are).

Methods inherited from class java.lang.Object

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

Field Detail

DETECTED

public static final FS DETECTED

The auto-detected implementation selected for this operating system and JRE.

Constructor Detail

FS

protected FS()

Constructs a file system abstraction.

FS

protected FS(FS src)

Initialize this FS using another's current settings.

Parameters:

src - the source FS to copy from.

Method Detail

detect

public static FS detect()

Auto-detect the appropriate file system abstraction.

Returns:

detected file system abstraction

detect

public static FS detect(Boolean cygwinUsed)

Auto-detect the appropriate file system abstraction, taking into account the presence of a Cygwin installation on the system. Using jgit in combination with Cygwin requires a more elaborate (and possibly slower) resolution of file system paths.

Parameters:

cygwinUsed -

• Boolean.TRUE to assume that Cygwin is used in combination with jgit
• Boolean.FALSE to assume that Cygwin is not used with jgit
• null to auto-detect whether a Cygwin installation is present on the system and in this case assume that Cygwin is used

Note: this parameter is only relevant on Windows.

Returns:

detected file system abstraction

newInstance

public abstract FS newInstance()

Returns:

a new instance of the same type of FS.

supportsExecute

public abstract boolean supportsExecute()

Does this operating system and JRE support the execute flag on files?

Returns:

true if this implementation can provide reasonably accurate executable bit information; false otherwise.

supportsSymlinks

public boolean supportsSymlinks()

Does this operating system and JRE supports symbolic links. The capability to handle symbolic links is detected at runtime.

Returns:

true if symbolic links may be used

Since:

3.0

isCaseSensitive

public abstract boolean isCaseSensitive()

Is this file system case sensitive

Returns:

true if this implementation is case sensitive

canExecute

public abstract boolean canExecute(File f)

Determine if the file is executable (or not).

Not all platforms and JREs support executable flags on files. If the feature is unsupported this method will always return false.

If the platform supports symbolic links and f is a symbolic link this method returns false, rather than the state of the executable flags on the target file.

Parameters:

f - abstract path to test.

Returns:

true if the file is believed to be executable by the user.

setExecute

public abstract boolean setExecute(File f,
                 boolean canExec)

Set a file to be executable by the user.

Not all platforms and JREs support executable flags on files. If the feature is unsupported this method will always return false and no changes will be made to the file specified.

Parameters:

f - path to modify the executable status of.

canExec - true to enable execution; false to disable it.

Returns:

true if the change succeeded; false otherwise.

lastModified

public long lastModified(File f)
                  throws IOException

Get the last modified time of a file system object. If the OS/JRE support symbolic links, the modification time of the link is returned, rather than that of the link target.

Parameters:

f -

Returns:

last modified time of f

Throws:

IOException

Since:

3.0

setLastModified

public void setLastModified(File f,
                   long time)
                     throws IOException

Set the last modified time of a file system object. If the OS/JRE support symbolic links, the link is modified, not the target,

Parameters:

f -

time -

Throws:

IOException

Since:

3.0

length

public long length(File path)
            throws IOException

Get the length of a file or link, If the OS/JRE supports symbolic links it's the length of the link, else the length of the target.

Parameters:

path -

Returns:

length of a file

Throws:

IOException

Since:

3.0

delete

public void delete(File f)
            throws IOException

Delete a file. Throws an exception if delete fails.

Parameters:

f -

Throws:

IOException - this may be a Java7 subclass with detailed information

Since:

3.3

resolve

public File resolve(File dir,
           String name)

Resolve this file to its actual path name that the JRE can use.

This method can be relatively expensive. Computing a translation may require forking an external process per path name translated. Callers should try to minimize the number of translations necessary by caching the results.

Not all platforms and JREs require path name translation. Currently only Cygwin on Win32 require translation for Cygwin based paths.

Parameters:

dir - directory relative to which the path name is.

name - path name to translate.

Returns:

the translated path. new File(dir,name) if this platform does not require path name translation.

userHome

public File userHome()

Determine the user's home directory (location where preferences are).

This method can be expensive on the first invocation if path name translation is required. Subsequent invocations return a cached result.

Not all platforms and JREs require path name translation. Currently only Cygwin on Win32 requires translation of the Cygwin HOME directory.

Returns:

the user's home directory; null if the user does not have one.

setUserHome

public FS setUserHome(File path)

Set the user's home directory location.

Parameters:

path - the location of the user's preferences; null if there is no home directory for the current user.

Returns:

this.

retryFailedLockFileCommit

public abstract boolean retryFailedLockFileCommit()

Does this file system have problems with atomic renames?

Returns:

true if the caller should retry a failed rename of a lock file.

userHomeImpl

protected File userHomeImpl()

Determine the user's home directory (location where preferences are).

Returns:

the user's home directory; null if the user does not have one.

searchPath

protected static File searchPath(String path,
              String... lookFor)

Searches the given path to see if it contains one of the given files. Returns the first it finds. Returns null if not found or if path is null.

Parameters:

path - List of paths to search separated by File.pathSeparator

lookFor - Files to search for in the given path

Returns:

the first match found, or null

Since:

3.0

readPipe

protected static String readPipe(File dir,
              String[] command,
              String encoding)

Execute a command and return a single line of output as a String

Parameters:

dir - Working directory for the command

command - as component array

encoding -

Returns:

the one-line output of the command

gitPrefix

public File gitPrefix()

Returns:

the $prefix directory C Git would use.

discoverGitPrefix

protected abstract File discoverGitPrefix()

Returns:

the $prefix directory C Git would use.

setGitPrefix

public FS setGitPrefix(File path)

Set the $prefix directory C Git uses.

Parameters:

path - the directory. Null if C Git is not installed.

Returns:

this

readSymLink

public String readSymLink(File path)
                   throws IOException

Check if a file is a symbolic link and read it

Parameters:

path -

Returns:

target of link or null

Throws:

IOException

Since:

3.0

isSymLink

public boolean isSymLink(File path)
                  throws IOException

Parameters:

path -

Returns:

true if the path is a symbolic link (and we support these)

Throws:

IOException

Since:

3.0

exists

public boolean exists(File path)

Tests if the path exists, in case of a symbolic link, true even if the target does not exist

Parameters:

path -

Returns:

true if path exists

Since:

3.0

isDirectory

public boolean isDirectory(File path)

Check if path is a directory. If the OS/JRE supports symbolic links and path is a symbolic link to a directory, this method returns false.

Parameters:

path -

Returns:

true if file is a directory,

Since:

3.0

isFile

public boolean isFile(File path)

Examine if path represents a regular file. If the OS/JRE supports symbolic links the test returns false if path represents a symbolic link.

Parameters:

path -

Returns:

true if path represents a regular file

Since:

3.0

isHidden

public boolean isHidden(File path)
                 throws IOException

Parameters:

path -

Returns:

true if path is hidden, either starts with . on unix or has the hidden attribute in windows

Throws:

IOException

Since:

3.0

setHidden

public void setHidden(File path,
             boolean hidden)
               throws IOException

Set the hidden attribute for file whose name starts with a period.

Parameters:

path -

hidden -

Throws:

IOException

Since:

3.0

createSymLink

public void createSymLink(File path,
                 String target)
                   throws IOException

Create a symbolic link

Parameters:

path -

target -

Throws:

IOException

Since:

3.0

relativize

public String relativize(String base,
                String other)

See FileUtils.relativize(String, String).

Parameters:

base - The path against which other should be relativized.

other - The path that will be made relative to base.

Returns:

A relative path that, when resolved against base, will yield the original other.

Since:

3.7

See Also:

FileUtils.relativize(String, String)

runIfPresent

public ProcessResult runIfPresent(Repository repository,
                         Hook hook,
                         String[] args)
                           throws JGitInternalException

Checks whether the given hook is defined for the given repository, then runs it with the given arguments.

The hook's standard output and error streams will be redirected to System.out and System.err respectively. The hook will have no stdin.

Parameters:

repository - The repository for which a hook should be run.

hook - The hook to be executed.

args - Arguments to pass to this hook. Cannot be null, but can be an empty array.

Returns:

The ProcessResult describing this hook's execution.

Throws:

JGitInternalException - if we fail to run the hook somehow. Causes may include an interrupted process or I/O errors.

Since:

3.7

runIfPresent

public ProcessResult runIfPresent(Repository repository,
                         Hook hook,
                         String[] args,
                         PrintStream outRedirect,
                         PrintStream errRedirect,
                         String stdinArgs)
                           throws JGitInternalException

Checks whether the given hook is defined for the given repository, then runs it with the given arguments.

Parameters:

repository - The repository for which a hook should be run.

hook - The hook to be executed.

args - Arguments to pass to this hook. Cannot be null, but can be an empty array.

outRedirect - A print stream on which to redirect the hook's stdout. Can be null, in which case the hook's standard output will be lost.

errRedirect - A print stream on which to redirect the hook's stderr. Can be null, in which case the hook's standard error will be lost.

stdinArgs - A string to pass on to the standard input of the hook. May be null.

Returns:

The ProcessResult describing this hook's execution.

Throws:

JGitInternalException - if we fail to run the hook somehow. Causes may include an interrupted process or I/O errors.

Since:

3.7

internalRunIfPresent

protected ProcessResult internalRunIfPresent(Repository repository,
                                 Hook hook,
                                 String[] args,
                                 PrintStream outRedirect,
                                 PrintStream errRedirect,
                                 String stdinArgs)
                                      throws JGitInternalException

See runIfPresent(Repository, Hook, String[], PrintStream, PrintStream, String) . Should only be called by FS supporting shell scripts execution.

Parameters:

repository - The repository for which a hook should be run.

hook - The hook to be executed.

args - Arguments to pass to this hook. Cannot be null, but can be an empty array.

outRedirect - A print stream on which to redirect the hook's stdout. Can be null, in which case the hook's standard output will be lost.

errRedirect - A print stream on which to redirect the hook's stderr. Can be null, in which case the hook's standard error will be lost.

stdinArgs - A string to pass on to the standard input of the hook. May be null.

Returns:

The ProcessResult describing this hook's execution.

Throws:

JGitInternalException - if we fail to run the hook somehow. Causes may include an interrupted process or I/O errors.

Since:

3.7

findHook

public File findHook(Repository repository,
            Hook hook)

Tries to find a hook matching the given one in the given repository.

Parameters:

repository - The repository within which to find a hook.

hook - The hook we're trying to find.

Returns:

The File containing this particular hook if it exists in the given repository, null otherwise.

Since:

3.7

runProcess

protected int runProcess(ProcessBuilder hookProcessBuilder,
             OutputStream outRedirect,
             OutputStream errRedirect,
             String stdinArgs)
                  throws IOException,
                         InterruptedException

Runs the given process until termination, clearing its stdout and stderr streams on-the-fly.

Parameters:

hookProcessBuilder - The process builder configured for this hook.

outRedirect - A print stream on which to redirect the hook's stdout. Can be null, in which case the hook's standard output will be lost.

errRedirect - A print stream on which to redirect the hook's stderr. Can be null, in which case the hook's standard error will be lost.

stdinArgs - A string to pass on to the standard input of the hook. Can be null.

Returns:

the exit value of this hook.

Throws:

IOException - if an I/O error occurs while executing this hook.

InterruptedException - if the current thread is interrupted while waiting for the process to end.

Since:

3.7

runInShell

public abstract ProcessBuilder runInShell(String cmd,
                        String[] args)

Initialize a ProcesssBuilder to run a command using the system shell.

Parameters:

cmd - command to execute. This string should originate from the end-user, and thus is platform specific.

args - arguments to pass to command. These should be protected from shell evaluation.

Returns:

a partially completed process builder. Caller should finish populating directory, environment, and then start the process.

getAttributes

public FS.Attributes getAttributes(File path)

Parameters:

path -

Returns:

the file attributes we care for

Since:

3.3

normalize

public File normalize(File file)

Normalize the unicode path to composed form.

Parameters:

file -

Returns:

NFC-format File

Since:

3.3

normalize

public String normalize(String name)

Normalize the unicode path to composed form.

Parameters:

name -

Returns:

NFC-format string

Since:

3.3