jenkins.scm.api

Class SCMFile

java.lang.Object

jenkins.scm.api.SCMFile

public abstract class SCMFile
extends Object

A file/directory inspected by SCMFileSystem.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SCMFile.Type Represents the type of a SCMFile.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SCMFile() Constructor for the root entry.
protected	SCMFile(SCMFile parent, String name) Constructor for any entry that is not the root.

Method Summary

Modifier and Type	Method and Description
SCMFile	child(String path) Constructs a child/descendant SCMFile instance path relative from this object.
abstract Iterable<SCMFile>	children() If this object represents a directory, lists up all the immediate children.
abstract InputStream	content() Reads the content of this file.
byte[]	contentAsBytes() A convenience method that reads the content and then turns it into a byte array.
String	contentAsString() A convenience method that reads the content and then turns it into a string.
Charset	contentEncoding() Encoding of this file.
String	contentMimeType() Returns the MIME type of this file.
boolean	exists() Returns true if this object represents something that exists.
String	getName() Gets the file name of this file without any path portion, such as just "foo.txt"
String	getPath() Gets the file name including the path portion, such as "foo/bar/manchu.txt".
SCMFile.Type	getType() The type of this object.
boolean	isContentBinary() Checks if this file is a binary file.
boolean	isContentText() The opposite of isContentBinary()
boolean	isDirectory() Returns true if this object represents a directory.
boolean	isFile() Returns true if this object represents a file.
boolean	isRoot() Tests if this instance is the root of the filesystem.
abstract long	lastModified() Returns the time that the SCMFile was last modified.
protected abstract SCMFile	newChild(String name, boolean assumeIsDirectory) Constructs an immediate child with the supplied type hint.
SCMFile	parent() Retrieves the parent SCMFile instance.
protected abstract SCMFile.Type	type() The type of this object.
protected void	type(SCMFile.Type type) Proactively seeds the type information where that has been already obtained in a different request.

Methods inherited from class java.lang.Object

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

Constructor Detail

SCMFile

protected SCMFile()

Constructor for the root entry.

Since:

2.0

SCMFile

protected SCMFile(@NonNull
                  SCMFile parent,
                  String name)

Constructor for any entry that is not the root.

Parameters:

parent - the parent reference or null if this is the root object.

name - the name of this entry (cannot contain '/').

Since:

2.0

Method Detail

getName

@NonNull
public final String getName()

Gets the file name of this file without any path portion, such as just "foo.txt"

This method is the equivalent of File.getName().

Returns:

the file name of this file without any path portion.

getPath

@NonNull
public String getPath()

Gets the file name including the path portion, such as "foo/bar/manchu.txt". Will never end in /.

Returns:

the pathname of this file.

Since:

2.0

isRoot

public final boolean isRoot()

Tests if this instance is the root of the filesystem.

Returns:

true if this instance is the root of the filesystem.

Since:

2.0

parent

@CheckForNull
public SCMFile parent()

Retrieves the parent SCMFile instance.

Returns:

the parent or null if this instance is the root already.

Since:

2.0

child

@NonNull
public SCMFile child(String path)

Constructs a child/descendant SCMFile instance path relative from this object.

Parameters:

path - Relative path of the child to return.

Returns:

The instance.

newChild

@NonNull
protected abstract SCMFile newChild(@NonNull
                                             String name,
                                             boolean assumeIsDirectory)

Constructs an immediate child with the supplied type hint.

Parameters:

name - the name of the immediate child, never null, never empty and never containing a /.

assumeIsDirectory - true if it this entry is being used as an intermediate in a multi-segment path and should thus be assumed to be a directory.

Returns:

the instance.

Since:

2.0.1

children

@NonNull
public abstract Iterable<SCMFile> children()
                                             throws IOException,
                                                    InterruptedException

If this object represents a directory, lists up all the immediate children.

This method is the equivalent of File.listFiles().

Returns:

Always non-null. If this method is not a directory, this method returns an empty iterable.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

lastModified

public abstract long lastModified()
                           throws IOException,
                                  InterruptedException

Returns the time that the SCMFile was last modified.

Returns:

A long value representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970) or 0L if the operation is unsupported.

Throws:

FileNotFoundException - if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

exists

public final boolean exists()
                     throws IOException,
                            InterruptedException

Returns true if this object represents something that exists.

This method is the equivalent of File.exists().

NOTE: Typically to minimize round trips, getType() would be preferred

Returns:

true if this object represents something that exists.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

See Also:

getType()

isFile

public final boolean isFile()
                     throws IOException,
                            InterruptedException

Returns true if this object represents a file.

This method is the equivalent of File.isFile().

NOTE: Typically to minimize round trips, getType() would be preferred

Returns:

true if this object represents a file.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

See Also:

getType()

isDirectory

public final boolean isDirectory()
                          throws IOException,
                                 InterruptedException

Returns true if this object represents a directory.

This method is the equivalent of File.isDirectory().

NOTE: Typically to minimize round trips, getType() would be preferred

Returns:

true if this object represents a directory.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

See Also:

getType()

getType

@NonNull
public final SCMFile.Type getType()
                                    throws IOException,
                                           InterruptedException

The type of this object.

Returns:

the SCMFile.Type of this object, specifically SCMFile.Type.NONEXISTENT if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

type

protected final void type(@NonNull
                          SCMFile.Type type)

Proactively seeds the type information where that has been already obtained in a different request.

Parameters:

type - the type of this object.

Since:

2.0

type

@NonNull
protected abstract SCMFile.Type type()
                                       throws IOException,
                                              InterruptedException

The type of this object.

Returns:

the SCMFile.Type of this object, specifically SCMFile.Type.NONEXISTENT if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

Since:

2.0

content

@NonNull
public abstract InputStream content()
                                      throws IOException,
                                             InterruptedException

Reads the content of this file.

Returns:

an open stream to read the file content. The caller must close the stream.

Throws:

FileNotFoundException - if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

IOException - if this object represents a directory or if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

contentAsBytes

@NonNull
public byte[] contentAsBytes()
                               throws IOException,
                                      InterruptedException

A convenience method that reads the content and then turns it into a byte array.

Returns:

the file content as a byte array.

Throws:

FileNotFoundException - if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

IOException - if this object represents a directory or if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

contentAsString

@NonNull
public String contentAsString()
                                throws IOException,
                                       InterruptedException

A convenience method that reads the content and then turns it into a string.

Returns:

the file content as a string.

Throws:

FileNotFoundException - if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

IOException - if this object represents a directory or if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

contentMimeType

@NonNull
public String contentMimeType()
                                throws IOException,
                                       InterruptedException

Returns the MIME type of this file.

The default implementation infers this based on the file name, but sophisticated server might provide this information from different sources, such as "svn:mime-type" in Subversion.

Returns:

the MIME type of this file.

Throws:

FileNotFoundException - if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

isContentBinary

public boolean isContentBinary()
                        throws IOException,
                               InterruptedException

Checks if this file is a binary file.

What exactly is a binary file is up to the implementation. Some SCMs (such as Subversion) has a way of letting users mark files as binaries.

Returns:

true if this file is a binary file.

Throws:

FileNotFoundException - if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

isContentText

public boolean isContentText()
                      throws IOException,
                             InterruptedException

The opposite of isContentBinary()

Returns:

true if this file is not a binary file.

Throws:

FileNotFoundException - if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.

contentEncoding

@NonNull
public Charset contentEncoding()
                                 throws IOException,
                                        InterruptedException

Encoding of this file.

This is used to interpret text files.

Some SCM implementations allow users to mark content encoding of files, and this method may provide those. As a fallback, the default implementation returns the platform default encoding.

Returns:

the encoding of this file.

Throws:

FileNotFoundException - if this SCMFile instance does not exist in the remote system (e.g. if you created a nonexistent instance via child(String))

IOException - if an error occurs while performing the operation.

InterruptedException - if interrupted while performing the operation.