@Deprecated public interface

CommonHistoryService

com.atlassian.stash.history.CommonHistoryService
Known Indirect Subclasses

This interface is deprecated.
in 2.11 for removal in 3.0. Use CommitService, which more accurately reflects the purpose of this service.

Class Overview

Do not use this interface. It exists to help ease the transition from HistoryService to its new name, CommitService. All new code should use the CommitService.

Summary

Public Methods
@Nonnull Page<Change> getChanges(ChangesRequest request, PageRequest pageRequest)
Retrieves a page of changes between two changesets.
@Nonnull Changeset getChangeset(Repository repository, String changesetId, Collection<String> attributesToLoad)
Retrieves a changeset by its id or the most recent changeset affecting a branch or tag.
@Nonnull Changeset getChangeset(Repository repository, String changesetId, String path)
Retrieves the most recent changeset affecting the specified repository and path, starting from the changeset identified by changesetId, which may be a commit, branch or tag.
@Nonnull Changeset getChangeset(Repository repository, String changesetId, String path, Collection<String> attributesToLoad)
Retrieves the most recent changeset affecting the specified repository and path, starting from the changeset identified by changesetId, which may be a commit, branch or tag.
@Nonnull Changeset getChangeset(Repository repository, String changesetId)
Retrieves a changeset by its id or the most recent changeset affecting a branch or tag.
@Nonnull Page<Changeset> getChangesets(Repository repository, String changesetId, String path, Collection<String> attributesToLoad, PageRequest pageRequest)
@Nonnull Page<Changeset> getChangesets(Repository repository, String changesetId, String path, PageRequest pageRequest)
Retrieves a page of changesets for the provided path on the specified branch.
@Nonnull Page<Changeset> getChangesetsBetween(ChangesetsBetweenRequest request, PageRequest pageRequest)
Retrieves a page of changesets between the included changesets and the excluded changesets.
@Nonnull Page<DetailedChangeset> getDetailedChangesets(DetailedChangesetsRequest request, PageRequest pageRequest)
Retrieves each of the changesets in getChangesetIds() changesetIds} and returns their details, including the first page of changes between the changeset in question and its first parent.
void streamChanges(ChangesRequest request, ChangeCallback callback)
Streams changes between the until and since changesets.
void streamChangesetsBetween(ChangesetsBetweenRequest request, ChangesetCallback callback)

Public Methods

@Nonnull public Page<Change> getChanges (ChangesRequest request, PageRequest pageRequest)

Retrieves a page of changes between two changesets. If the since changeset is not specified, the until changeset's first parent is used automatically.

Parameters
request describes the two changesets to retrieve changes between and the repository which contains both changesets
pageRequest the start and limit for the page being requested
Returns
  • a page of changes within the repository between the specified IDs

@Nonnull public Changeset getChangeset (Repository repository, String changesetId, Collection<String> attributesToLoad)

Retrieves a changeset by its id or the most recent changeset affecting a branch or tag. The specified attributesToLoad will also be loaded. These attributes are metadata associated with the changeset by a given ChangesetIndexer.

Parameters
repository the repository to find the changeset
changesetId the starting changeset, which may be a specific commit or a branch or tag name
Returns
  • the matching changeset within the repository
Throws
NoSuchEntityException Thrown if no matching changeset can be found.

@Nonnull public Changeset getChangeset (Repository repository, String changesetId, String path)

Retrieves the most recent changeset affecting the specified repository and path, starting from the changeset identified by changesetId, which may be a commit, branch or tag.

Parameters
repository the repository to find the changeset and path in
changesetId the starting changeset, which may be a specific commit or a branch or tag name
path the path to find the first changeset for
Returns
  • the first changeset affecting the specified path within the repository
Throws
NoSuchEntityException Thrown if no matching changeset can be found.

@Nonnull public Changeset getChangeset (Repository repository, String changesetId, String path, Collection<String> attributesToLoad)

Retrieves the most recent changeset affecting the specified repository and path, starting from the changeset identified by changesetId, which may be a commit, branch or tag. The specified attributesToLoad will also be loaded. These attributes are metadata associated with the changeset by a given ChangesetIndexer.

Parameters
repository the repository to find the changeset and path in
changesetId the starting changeset, which may be a specific commit or a branch or tag name
path the path to find the first changeset for
Returns
  • the first changeset affecting the specified path within the repository
Throws
NoSuchEntityException Thrown if no matching changeset can be found.

@Nonnull public Changeset getChangeset (Repository repository, String changesetId)

Retrieves a changeset by its id or the most recent changeset affecting a branch or tag.

Parameters
repository the repository to find the changeset
changesetId the starting changeset, which may be a specific commit or a branch or tag name
Returns
  • the matching changeset within the repository
Throws
NoSuchEntityException Thrown if no matching changeset can be found.

@Nonnull public Page<Changeset> getChangesets (Repository repository, String changesetId, String path, Collection<String> attributesToLoad, PageRequest pageRequest)

@Nonnull public Page<Changeset> getChangesets (Repository repository, String changesetId, String path, PageRequest pageRequest)

Retrieves a page of changesets for the provided path on the specified branch.

If the provided changesetId is null, the default branch for the repository will be assumed. If the path is null, changesets are returned starting from (and including) the provided changesetId (where, again, the repository's default branch will be used if null). As a result this service call may be used to:

  • Retrieve pages of changesets on a given branch or tag
  • Retrieve pages of ancestral changesets for a given changeset
  • Retrieve pages of changesets where a given file has be modified
Each usage is for a single starting point. This means a single branch, tag or changeset. For example, retrieving all changesets where a given file has been modified on all branches is not possible.

Note: If the provided path is renamed at some point in its history, changesets will not follow the path across the rename. In other words, only changesets for the exact path provided will be included.

Parameters
repository the repository to find the changesets and path in
changesetId the starting changeset from which to search for other changesets, which may be a branch or tag name or a changeset hash
path the path find changesets for
pageRequest the start and limit for the page being requested
Returns
  • a page of changes

@Nonnull public Page<Changeset> getChangesetsBetween (ChangesetsBetweenRequest request, PageRequest pageRequest)

Retrieves a page of changesets between the included changesets and the excluded changesets. Included and excluded changesets may be specified by branch or tag name or by hash. The changesets returned are those which are reachable an included changeset and not reachable from any excluded changeset. While this may imply an ancestral relationship between include and exclude IDs, that is not strictly required. When the IDs are unrelated, all changesets referenceable from included changesets are candidates for the returned page, and excluded changesets are effectively ignored. Paths may be provided to further narrow the results, restricting the returned changesets to only those affecting one or more of the specified paths.

Which changesets are included and which are excluded is important here. Consider the following example:

  1. Branch "feature-A" was created from "master" when "master" was at changeset A
  2. Changesets FA1, FA2 and FA3 were created on the "feature-A" branch
  3. Changesets B and C were made on "master" after the branch was created
The graph would look like this:
 ---- A ---- B ---- C
       \
        \
        FA1 ---- FA2 ---- FA3
 
If "master" is excluded and "feature-A" is included, changesets FA1, FA2 and FA3 will be returned, because they are reachable from "feature-A" but not from "master". If the two IDs were reversed, changesets B and C would be returned, because they are reachable from "master" but not from "feature-A". This approach of swapping includes and excludes can be used to determine how two branches have diverged over time.

Warning: Changesets specified using branch or tag names, will be resolved against the primary repository. When retrieving changesets between repositories, changesets in the secondary repository may only be specified by hash. This means requesting a page like this will not work:


     ChangesetsBetweenRequest request = new ChangesetsBetweenRequest.Builder(repository)
             .exclude("master")
             .include("master")
             .secondaryRepository(forkOfRepository)
             .build();
     Page<Changeset> page = historyService.getChangesetsBetween(request, PageUtils.newRequest(0, 25));
 
The returned page will always be empty, because "master" was resolved on both sides using the same repository, and so it produced the same changeset to include and exclude.

Parameters
request the changesets to include/exclude, paths to filter by and which repository, or repositories, contain the changesets
pageRequest the start and limit for the page being requested
Returns
  • a page containing 0 or more changesets reachable from any included changesets and not reachable from any excluded ones

@Nonnull public Page<DetailedChangeset> getDetailedChangesets (DetailedChangesetsRequest request, PageRequest pageRequest)

Retrieves each of the changesets in getChangesetIds() changesetIds} and returns their details, including the first page of changes between the changeset in question and its first parent.

If the page size is less than the size of the collection of IDs, a subset of the collection will be returned. Otherwise, detailed changesets for all IDs in the requested collection are returned.

Parameters
request request parameters, including repository and the relevant changesets
pageRequest the start and limit of the page being request
Returns
  • a page containing detailed changesets for a subset of the requested IDs
Throws
NoSuchChangesetException if ignoreMissing is not set and any given changeset cannot be found.

public void streamChanges (ChangesRequest request, ChangeCallback callback)

Streams changes between the until and since changesets. If the since changeset is not specified, the until changeset's first parent is used automatically.

Parameters
request describes the two changesets to retrieve changes between and the repository which contains both changesets
callback the callback for receiving the changes

public void streamChangesetsBetween (ChangesetsBetweenRequest request, ChangesetCallback callback)

Streams changesets between the included changesets) and the {@link ChangesetsBetweenRequest#getExcludes() excluded changesets.

This method promises to call onStart() on the supplied callback once followed by zero or more calls to onChangeset(Changeset), one for each changeset to be streamed (until false is returned by onChangeset(...) or there are no more changesets), followed by a single call to onEnd().

See getChangesetsBetween(...) for a description of the semantics of the changesets returned.

Parameters
request the changesets to include/exclude, paths to filter by and which repository, or repositories, contain the changesets
callback the callback for receiving the changesets