Package de.unibremen.informatik.st.libvcs4j

Interface RevisionRange

  • All Superinterfaces:
    VCSModelElement
    public interface RevisionRange
extends VCSModelElement
    This class represents the state transition between two revisions. The "from" revision (if any) is available with getPrevious(). The "to" revision is available with getCurrent().

    A single range may subsume several commits to merge commits on, for instance, a monthly basis.

    • Method Detail

      • getOrdinal

        int getOrdinal()
        Returns the ordinal of this range. Ordinals are used to identify individual ranges with a serial number when processing a VCS. The origin is 1.
        Returns:
        The ordinal of this range (>= 1).

      • getRevision

        @Deprecated
default Revision getRevision()
        Deprecated.
        Use getCurrent() instead.
        Returns the "to" revision the file changes of this range belong to.
        Returns:
        The "to" revision the file changes of this range belong to.

      • getCurrent

        Revision getCurrent()
        Returns the "to" revision the file changes of this range belong to.
        Returns:
        The "to" revision the file changes of this range belong to.

      • getPredecessorRevision

        @Deprecated
default java.util.Optional<Revision> getPredecessorRevision()
        Deprecated.
        Use getPrevious() instead.
        Returns the "from" revision the file changes of this range belong to.
        Returns:
        The "from" revision the file changes of this range belong to or an empty Optional if this is the first range.

      • getPrevious

        java.util.Optional<Revision> getPrevious()
        Returns the "from" revision the file changes of this range belong to.
        Returns:
        The "from" revision the file changes of this range belong to or an empty Optional if this is the first range.

      • getCommits

        java.util.List<Commit> getCommits()
        Returns the commits that have been applied to getPrevious() so that getCurrent() results from it. The order of the returned list is from oldest to latest. Contains at least one commit.
        Returns:
        The list of commits.

      • getFileChanges

        default java.util.List<FileChange> getFileChanges()
        Returns all files that have changed between getPrevious() and getCurrent(). The default implementation, if necessary, merges the file changes of all commits listed in getCommits().
        Returns:
        The list of file changes.

      • getAddedFiles

        default java.util.List<FileChange> getAddedFiles()
        Returns all files that have been added.
        Returns:
        All files that have been added.

      • getRemovedFiles

        default java.util.List<FileChange> getRemovedFiles()
        Returns all files that have been removed.
        Returns:
        All files that have been removed.

      • getModifiedFiles

        default java.util.List<FileChange> getModifiedFiles()
        Returns all files that have been modified.
        Returns:
        All files that have been modified.

      • getRelocatedFiles

        default java.util.List<FileChange> getRelocatedFiles()
        Returns all files that have been relocated.
        Returns:
        All files that have been relocated.

      • getFileChangesBySuffix

        default java.util.List<FileChange> getFileChangesBySuffix​(java.lang.String suffix)
        Filters the list of file changes returned by getFileChanges() and returns only those whose old or the new relative path end with suffix. You may use this method to analyze file changes affecting a certain file type only. For instance, call getFileChangesBySuffix(".java") to get only the file changes affecting Java files.
        Parameters:
        suffix - The suffix used to filter the file changes.
        Returns:
        All file changes whose old or the new relative path end with suffix.

      • getFileChangesByPrefix

        default java.util.List<FileChange> getFileChangesByPrefix​(java.lang.String prefix)
        Filters the list of file changes returned by getFileChanges() and returns only those whose old or new relative path start with prefix. You may use this method to analyze file changes affecting a certain directory (and its subdirectories) only. For instance, call getFileChangesByPrefix("src/main/java") to get only the file changes affecting files located in "src/main/java".
        Parameters:
        prefix - The prefix used to filter the file changes.
        Returns:
        All file changes whose old or new relative file path start with prefix.

      • getFileChangesByRegex

        default java.util.List<FileChange> getFileChangesByRegex​(java.lang.String regex)
        Filters the list of file changes returned by getFileChanges() and returns only those whose old or new relative path match regex. Paths are matched using String.matches(String).
        Parameters:
        regex - The regular expression used to filter the file changes.
        Returns:
        All file changes whose old or new relative path match regex.

      • getIssues

        default java.util.List<Issue> getIssues()
        Returns the issues referenced by the commits of this range. To enable this feature when processing a repository, set an appropriate ITEngine with VCSEngine.setITEngine(ITEngine). The returned list does not contain the same issue (according to Issue.getId()) twice.
        Returns:
        The issues referenced by the commits of this range.

      • isFirst

        default boolean isFirst()
        Returns whether this range is the first one. That is, there is no predecessor revision and, consequently, all changes returned by getFileChanges() are additions. The default implementation simply checks whether getPrevious() returns an empty Optional.
        Returns:
        true if this range is the first one, false otherwise.

      • ifFirst

        default void ifFirst​(java.util.function.Consumer<RevisionRange> action)
        Runs the given action if this range is the first one.
        Parameters:
        action - The action to run if this is the first range.

      • ifNotFirst

        default void ifNotFirst​(java.util.function.Consumer<RevisionRange> action)
        Runs the given action if this range is not the first one.
        Parameters:
        action - The action to run if this is not the first range.

      • merge

        default RevisionRange merge​(RevisionRange predecessor)
                     throws java.lang.NullPointerException
        Merges this range into predecessor and returns a new instance that represents the state transition from predecessor.getPrevious() to this.getCurrent(). The commits of predecessor and this are combined such that the commits of this are applied onto the commits of predecessor.
        Parameters:
        predecessor - The predecessor range to merge this range into.
        Returns:
        A new revision range representing the state transition from predecessor.getPrevious() to this.getCurrent().
        Throws:
        java.lang.NullPointerException - If predecessor is null.