Package de.unibremen.informatik.st.libvcs4j

Interface VCSEngine

  • All Superinterfaces:
    java.lang.Iterable<RevisionRange>
    public interface VCSEngine
extends java.lang.Iterable<RevisionRange>
    A VCSEngine is supposed to extract a linear sequence of RevisionRange instances for arbitrary version control systems (VCS) as well as single input files and directories. In order to calculate the file changes of a particular RevisionRange, real VCS (or similar) operations are performed. Consequently, all files of the currently processed revision are physically available at getTarget() and getOutput(). Due to the complexity of some VCS, the generated sequence of revision ranges is a "one-way-iterator" that allows forward directed processing only. By extending the Iterable interface, a VCSEngine allows to retrieve revision ranges using foreach loops. There are several things to consider, though. First of all, Iterator instances returned by Iterable.iterator() depend on the state of the corresponding engine. Consequently, calling next() on an engine e, modifies all available iterators of e, too. Similarly, calling Iterator.next() on an iterator i, modifies any other iterator sharing i's engine. Due to the circumstance that Iterator.hasNext() and Iterator.next() perform real VCS (or similar) operations an IOException may be thrown by these methods which, in order to fulfill the Iterable interface, is encapsulated in an UncheckedIOException. Long story short, you should not use several iterators at once. Note: Neither getRepository() nor getRoot() nor getTarget() nor getOutput() may change at any time. This is an important property because it allows users of this API to maintain incrementally updated models reflecting the current state of a VCS. Note 2: readAllBytes(VCSFile), readLineInfo(VCSFile), and computeDiff(FileChange) are stateless operations. That is, one may read any file in any state.

    • Method Detail

      • next

        java.util.Optional<RevisionRange> next()
                                throws java.io.IOException
        Extracts the next revision range, if any. If necessary, the first call of this method initializes the repository---for instance, cloning the repository to getTarget().
        Returns:
        The next revision range, if any.
        Throws:
        java.io.IOException - If an error occurred while extracting the next revision range.

      • readAllBytes

        byte[] readAllBytes​(VCSFile file)
             throws java.lang.NullPointerException,
                    java.lang.IllegalArgumentException,
                    java.io.IOException
        Reads the contents of the given file. This method does not depend on the current state of this engine. (see Note 2 above).
        Parameters:
        file - The file to read the contents from.
        Returns:
        A byte array containing the bytes read from the file.
        Throws:
        java.lang.NullPointerException - If file is null.
        java.lang.IllegalArgumentException - If file is unknown to this engine.
        java.io.IOException - If an error occurred while reading the contents.

      • readLineInfo

        java.util.List<LineInfo> readLineInfo​(VCSFile file)
                               throws java.lang.NullPointerException,
                                      java.lang.IllegalArgumentException,
                                      java.io.IOException
        Reads the line information of the given file.
        Parameters:
        file - The file to read the line information from.
        Returns:
        The line information of file.
        Throws:
        java.lang.NullPointerException - If file is null.
        java.lang.IllegalArgumentException - If file is unknown to this engine.
        java.io.IOException - If an error occurred while reading the line information.

      • guessCharset

        java.util.Optional<java.nio.charset.Charset> guessCharset​(VCSFile file)
                                                   throws java.io.IOException
        Tries to guess the charset of file.
        Returns:
        The guessed charset.
        Throws:
        java.io.IOException - If an error occurred while reading the contents of file.

      • getRevision

        java.util.Optional<Revision> getRevision()
        Returns the currently checked out revision.
        Returns:
        The currently checked out revision or an empty Optional if next() has not been called yet.

      • getRepository

        java.lang.String getRepository()
        Returns the path to the processed Repository. Note: This path never changes.
        Returns:
        Path to the processed repository.

      • getRoot

        java.lang.String getRoot()
        Returns the path (relative to getRepository()) to the tracked file or directory. For instance, if "/path/to/git/src" is the directory you want to track, "src" is the value returned by this method. For the sake of convenience, an empty String rather than null is returned if a provider tracks the root (top) directory. Note: This path never changes.
        Returns:
        Path to the tracked file or directory within getRepository().

      • getTarget

        java.nio.file.Path getTarget()
        Returns the path to the output directory of the currently processed revision. For example, "/tmp/git-clone", "/tmp/svn-working-copy", and so on. Some VCS engines (Git for instance) do not support partial checkouts. Therefore, use getOutput() to retrieve the path to the tracked files and directories within 'target' rather than the root (top) of the processed directory. Note: This path never changes.
        Returns:
        Path to the currently processed revision.

      • getOutput

        java.nio.file.Path getOutput()
        This method is somewhat similar to getTarget(), but may return the composite of getTarget() and getRoot() if the underlying VCS does not support partial checkouts (just like Git, for instance). If the VCS supports partial checkouts, getTarget() is returned. Use this method if you want to access the tracked files and directories of the currently processed revision. Note: This path never changes.
        Returns:
        Path to tracked files and directories of the currently processed revision.

      • computeDiff

        java.util.List<LineChange> computeDiff​(FileChange fileChange)
                                throws java.lang.NullPointerException,
                                       java.io.IOException
        Computes the changed lines of the given file change.
        Parameters:
        fileChange - The file change to compute the line diff for.
        Returns:
        A sequence of LineChange objects.
        Throws:
        java.lang.NullPointerException - If fileChange is null.
        java.io.IOException - If an error occurred while reading the content of the old or new file (see VCSFile.readContent()).

      • setITEngine

        void setITEngine​(ITEngine itEngine)
        Sets the engine used to extract issues from an issue tracker. If null is passed, the currently set engine is removed.
        Parameters:
        itEngine - The engine used to extract issues from an issue tracker or null to unset the currently set engine.

      • getITEngine

        java.util.Optional<ITEngine> getITEngine()
        Returns the engine used to extract issues from an issue tracker.
        Returns:
        The engine used to extract issues from an issue tracker.

      • getModelFactory

        VCSModelFactory getModelFactory()
        Returns the factory used to create vcs model instances.
        Returns:
        The factory used to create vcs model instances.

      • setModelFactory

        void setModelFactory​(VCSModelFactory factory)
              throws java.lang.NullPointerException
        Sets the factory used to create vcs model instances.
        Parameters:
        factory - The factory used to create vcs model instances.
        Throws:
        java.lang.NullPointerException - If factory is null.

      • createVCSFileFilter

        default java.io.FilenameFilter createVCSFileFilter()
        Returns a FilenameFilter that is supposed to exclude VCS specific files and directories. The default implementation creates a filter that does not exclude any file or directory. Note: A file or directory is excluded if and only if FilenameFilter.accept(File, String) returns false.
        Returns:
        A FilenameFilter to exclude VCS specific files and directories.

      • listFilesInOutput

        default java.util.List<java.nio.file.Path> listFilesInOutput()
                                                      throws java.io.IOException
        Returns all non-VCS-specific files located in getOutput(). All paths of the returned list are absolute and the list does not contain any directory path. The default implementation uses the FilenameFilter returned by createVCSFileFilter() to exclude particular files from getOutput(). getOutput() itself can not be excluded.
        Returns:
        All non-VCS-specific files located in getOutput().
        Throws:
        java.io.FileNotFoundException - If getOutput() does not exist.
        java.io.IOException - If an error occurred while collecting files.