Package jenkins.scm.api

Class SCMFile

java.lang.Object
jenkins.scm.api.SCMFile
public abstract class SCMFile extends Object
A file/directory inspected by SCMFileSystem.

  • Constructor Details

    • 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 Details

    • 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:

    • 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:

    • 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

      @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.