@PublicApi public interface

ChangeHistoryManager

com.atlassian.jira.issue.changehistory.ChangeHistoryManager
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

Manages the change history of issues. TODO: expand this interface to include the functionality from ChangeLogUtils

Summary

Public Methods
Map<StringString> findAllPossibleValues(String field)
This method is deprecated. since 5.2 - and will be removed in 6.0, it sucks performance wise and can kill a JIRA instance if you really need to find all values then use JiraLuceneFieldFinder
@Deprecated Issue findMovedIssue(String originalKey)
This method is deprecated. Use getIssue(String) instead. Since v6.1.
Collection<Issue> findUserHistory(ApplicationUser remoteUser, Collection<String> userkeys, Collection<Project> projects, int maxResults)
Find a list of issues that the given users have acted on with the option to limit the projects included in the search.
Collection<Issue> findUserHistory(ApplicationUser remoteUser, Collection<String> userkeys, int maxResults)
Find a list of issues that the given users have acted on.
List<ChangeHistoryItem> getAllChangeItems(Issue issue)
Returns a List of ChangeHistoryItem's for the given issue
List<ChangeHistory> getChangeHistories(Issue issue)
Returns a List of ChangeHistory entities
List<ChangeHistory> getChangeHistoriesForUser(Issue issue, ApplicationUser remoteUser)
Returns a List of ChangeHistory entities for a single issue.
List<ChangeHistory> getChangeHistoriesForUser(Iterable<Issue> issues, ApplicationUser remoteUser)
Returns a List of ChangeHistory entities for multiple issues.
@Nonnull List<ChangeHistory> getChangeHistoriesSince(Issue issue, Date since)
Returns a List of ChangeHistory entities that occurred after the provided date.
@Nullable ChangeHistory getChangeHistoryById(Long changeGroupId)
List<ChangeItemBean> getChangeItemsForField(Issue issue, String changeItemFieldName)
Returns a List of ChangeItemBean's for the given issue which also are for the provided changeItemFieldName (i.e.
List<ChangeHistory> getChangeItemsWithFieldsForIssues(Iterable<Issue> issues, Iterable<String> fieldNames)
Returns a List of ChangeHistory for the listed issues with changes only for the listed fields.
@Deprecated Collection<String> getPreviousIssueKeys(String issueKey)
This method is deprecated. Use getAllIssueKeys(Long) instead. Since v6.1.
@Deprecated Collection<String> getPreviousIssueKeys(Long issueId)
This method is deprecated. Use getAllIssueKeys(Long) instead. Since v6.1.
void removeAllChangeItems(Issue issue)
Remove all change items associated with an issue.

Public Methods

public Map<StringString> findAllPossibleValues (String field)

This method is deprecated.
since 5.2 - and will be removed in 6.0, it sucks performance wise and can kill a JIRA instance if you really need to find all values then use JiraLuceneFieldFinder

Find a map of all names ever used in the change history.

Parameters
field The field name.
Returns
  • An immutable map of issue objects sorted by creation date in descending order

@Deprecated public Issue findMovedIssue (String originalKey)

This method is deprecated.
Use getIssue(String) instead. Since v6.1.

Returns an issue that has been moved by searching on the old issue key.

Parameters
originalKey the original key of an issue that has since been moved (moving between projects assigns a new key to an issue)
Returns
Throws
GenericEntityException if an unexpected error occurs

public Collection<Issue> findUserHistory (ApplicationUser remoteUser, Collection<String> userkeys, Collection<Project> projects, int maxResults)

Find a list of issues that the given users have acted on with the option to limit the projects included in the search.

Parameters
remoteUser The user executing this request.
userkeys The keys of users to find the history for. If null, returns the history for all users. If empty, no results will be found.
projects The projects to include issues from
maxResults The maxmimum number of issues to return
Returns
  • An immutable collection of issue objects sorted by creation date in descending order

public Collection<Issue> findUserHistory (ApplicationUser remoteUser, Collection<String> userkeys, int maxResults)

Find a list of issues that the given users have acted on.

Parameters
remoteUser The user executing this request.
userkeys The keys of users to find the history for. If null, returns the history for all users. If empty, no results will be found.
maxResults The maxmimum number of issues to return
Returns
  • An immutable collection of issue objects sorted by creation date in descending order

public List<ChangeHistoryItem> getAllChangeItems (Issue issue)

Returns a List of ChangeHistoryItem's for the given issue

Parameters
issue the issue
Returns
  • A list containing all of the change items for a specific Issue

public List<ChangeHistory> getChangeHistories (Issue issue)

Returns a List of ChangeHistory entities

Parameters
issue the issue.
Returns
  • a List of ChangeHistory entries.

public List<ChangeHistory> getChangeHistoriesForUser (Issue issue, ApplicationUser remoteUser)

Returns a List of ChangeHistory entities for a single issue.

Parameters
issue the issue.
remoteUser the user who is asking.
Returns
  • a List of ChangeHistory entries.
See Also
  • #getChangeHistoriesForUser(com.atlassian.jira.issue.Issue, com.atlassian.crowd.embedded.api.User) for a more efficient way to read change histories for multiple issues

public List<ChangeHistory> getChangeHistoriesForUser (Iterable<Issue> issues, ApplicationUser remoteUser)

Returns a List of ChangeHistory entities for multiple issues. This method is much more efficient than #getChangeHistoriesForUser(com.atlassian.jira.issue.Issue, com.atlassian.crowd.embedded.api.User) and should be prefered whenever possible.

Parameters
issues the issues.
remoteUser the user who is asking.
Returns
  • a List of ChangeHistory entries.

@Nonnull public List<ChangeHistory> getChangeHistoriesSince (Issue issue, Date since)

Returns a List of ChangeHistory entities that occurred after the provided date.

Parameters
issue the issue. Must not be null.
since only change histories made after this date will be returned. Must not be null.
Returns
  • a possibly empty List of ChangeHistory entries made after the provided date. Will not be null.

@Nullable public ChangeHistory getChangeHistoryById (Long changeGroupId)

Returns
  • a ChangeHistory group with the given id, or null if not found

public List<ChangeItemBean> getChangeItemsForField (Issue issue, String changeItemFieldName)

Returns a List of ChangeItemBean's for the given issue which also are for the provided changeItemFieldName (i.e. Link, Fix Version/s, etc). The order of the list will from oldest to newest.

Parameters
issue the issue the change items are associated with, not null.
changeItemFieldName the field name the change item is stored under, not null or empty.
Returns
  • a List of ChangeItemBean's for the given issue.

public List<ChangeHistory> getChangeItemsWithFieldsForIssues (Iterable<Issue> issues, Iterable<String> fieldNames)

Returns a List of ChangeHistory for the listed issues with changes only for the listed fields.

Parameters
issues The list of issues to search
fieldNames The list of field names
Returns
  • A list of changes.

@Deprecated public Collection<String> getPreviousIssueKeys (String issueKey)

This method is deprecated.
Use getAllIssueKeys(Long) instead. Since v6.1.

Given an issue key, this method returns a list of previous issue keys this issue was moved from. This may be useful for source control plugins for example, where a given changeset should be displayed even after an issue has been moved and it's issue key has changed.

Note: The list of previous issue keys is no longer returned in chronological order.

Parameters
issueKey The current issue key.
Returns
  • A collection of previous issue keys or an empty list if none exist.

@Deprecated public Collection<String> getPreviousIssueKeys (Long issueId)

This method is deprecated.
Use getAllIssueKeys(Long) instead. Since v6.1.

Returns the same as getPreviousIssueKeys(String) but is slightly more efficient since no lookup of the issue id needs to be performed. If you have an issue object available with the issue's id use this method.

Parameters
issueId The id of the issue being looked up.
Returns
  • A collection of previous issue keys or an empty list if none exist.

public void removeAllChangeItems (Issue issue)

Remove all change items associated with an issue.

Parameters
issue affected issue