@PublicApi public interface

WorklogManager

com.atlassian.jira.issue.worklog.WorklogManager
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

The WorklogManager is used to retrieve, create, update, and remove work logs in JIRA. Worklogs are always associated with an issue.

Summary

Constants
int WORKLOG_UPDATE_DATA_PAGE_SIZE
Public Methods
Worklog create(ApplicationUser user, Worklog worklog, Long newEstimate, boolean dispatchEvent)
Creates a worklog based on the passed in Worklog object and associates it with the given issue.
boolean delete(ApplicationUser user, Worklog worklog, Long newEstimate, boolean dispatchEvent)
Deletes the specified worklog and updates the issue's remaining estimate and time spent fields.
Worklog getById(Long id)
Used to get a worklog by its id.
PagedList<Worklog> getByIssue(Issue issue, int pageSize)
Returns all child worklogs of a specified issue, in a PagedList
List<Worklog> getByIssue(Issue issue)
Returns all child worklogs of a specified issue
long getCountForWorklogsRestrictedByGroup(String groupName)
Returns the count of all Worklog's that have a visibility restriction of the provided group.
long getCountForWorklogsRestrictedByRole(Long roleId)
Returns the count of all Worklog's that have a visibility restriction of the provided role.
ProjectRole getProjectRole(Long projectRoleId)
This is a convenience method to allow us to easily get a ProjectRole.
List<DeletedWorklog> getWorklogsDeletedSince(Long sinceInMilliseconds)
Returns WORKLOG_UPDATE_DATA_PAGE_SIZE of worklog ids and removal dates, which were removed after (inclusive) provided time in milliseconds.
Set<Worklog> getWorklogsForIds(Set<Long> idsOfWorklogs)
Returns a set of worklogs for provided ids.
List<Worklog> getWorklogsUpdatedSince(Long sinceInMilliseconds)
Returns WORKLOG_UPDATE_DATA_PAGE_SIZE of worklogs, which were updated or created after (inclusive) provided time in milliseconds.
int swapWorklogGroupRestriction(String groupName, String swapGroup)
Updates Worklog's such that worklogs that have a visibility restriction of the provided groupName will be changed to have a visibility restriction of the provided swapGroup.
int swapWorklogRoleRestriction(Long roleId, Long swapRoleId)
Updates Worklog's such that worklogs that have a visibility restriction of the provided role will be changed to have a visibility restriction of a role with the provided swapRoleId.
Worklog update(ApplicationUser user, Worklog worklog, Long newEstimate, boolean dispatchEvent)
Updates the provided Worklog.

Constants

public static final int WORKLOG_UPDATE_DATA_PAGE_SIZE

Constant Value: 1000 (0x000003e8)

Public Methods

public Worklog create (ApplicationUser user, Worklog worklog, Long newEstimate, boolean dispatchEvent)

Creates a worklog based on the passed in Worklog object and associates it with the given issue.

If you have provided a groupLevel then the worklog visibility will be restricted to the provided group, it is assumed that validation to insure that the group actually exists has been performed outside of this method. If you have provided a roleLevelId then the worklog visibility will be restricted to the provided role, it is assumed that validation to insure that the role actually exists has been performed outside of this method.

NOTE: this method does not do any permission checks to see if the user can perform the requested operation.

Parameters
user is the user who is trying to create the worklog, this can be different than the user identified by getAuthor().
worklog the object used to provide the parameters that will be used to create the worklog.
newEstimate will be used to set the time estimate for this worklog.
dispatchEvent if true then an event of type ISSUE_WORKLOGGED_ID will be dispatched and any notifications listening for that event will be triggered. If false no event will be dispatched.
Returns
  • a Worklog object that represents the newly created worklog.

public boolean delete (ApplicationUser user, Worklog worklog, Long newEstimate, boolean dispatchEvent)

Deletes the specified worklog and updates the issue's remaining estimate and time spent fields.

Parameters
user the user who is performing the action
worklog the value to remove in the database
newEstimate the value to set the Issue's remainig estimate. If null the value will be left alone.
dispatchEvent if true then an event of type ISSUE_WORKLOG_DELETED_ID will be dispatched and any notifications listening for that event will be triggered. If false no event will be dispatched.
Returns
  • true if the worklog was deleted, false otherwise.

public Worklog getById (Long id)

Used to get a worklog by its id.

Parameters
id uniquely identifies the worklog
Returns
  • returns the worklog for the passed in id, null if not found.

public PagedList<Worklog> getByIssue (Issue issue, int pageSize)

Returns all child worklogs of a specified issue, in a PagedList

Parameters
issue the specified parent issue (not null)
Returns
  • a List of Worklogs, ordered by creation date. An empty List will be returned if none are found

public List<Worklog> getByIssue (Issue issue)

Returns all child worklogs of a specified issue

Parameters
issue the specified parent issue (not null)
Returns
  • a List of Worklogs, ordered by creation date. An empty List will be returned if none are found

public long getCountForWorklogsRestrictedByGroup (String groupName)

Returns the count of all Worklog's that have a visibility restriction of the provided group.

Parameters
groupName identifies the group the worklogs are restricted by, this must not be null.
Returns
  • the count of restriced groups

public long getCountForWorklogsRestrictedByRole (Long roleId)

Returns the count of all Worklog's that have a visibility restriction of the provided role.

Parameters
roleId identifies the role the worklogs are restricted by, this must not be null.
Returns
  • the count of restricted worklogs

public ProjectRole getProjectRole (Long projectRoleId)

This is a convenience method to allow us to easily get a ProjectRole. This is being used by the CommentImpl to get a ProjectRole.

NOTE: If you are trying to retrieve a ProjectRole then you should be using the ProjectRoleManager.

Parameters
projectRoleId the id to the ProjectRole object you would like returned.
Returns
  • will return a ProjectRole based on the passed in projectRoleId.

public List<DeletedWorklog> getWorklogsDeletedSince (Long sinceInMilliseconds)

Returns WORKLOG_UPDATE_DATA_PAGE_SIZE of worklog ids and removal dates, which were removed after (inclusive) provided time in milliseconds.

Parameters
sinceInMilliseconds the time in unix timestamp format.
Returns
  • ids and removal dates of worklogs which were deleted since provided time.

public Set<Worklog> getWorklogsForIds (Set<Long> idsOfWorklogs)

Returns a set of worklogs for provided ids. This method expects the size of to be less than WORKLOG_UPDATE_DATA_PAGE_SIZE.

Parameters
idsOfWorklogs set of worklog ids.
Returns
  • a list of worklogs for provided ids.

public List<Worklog> getWorklogsUpdatedSince (Long sinceInMilliseconds)

Returns WORKLOG_UPDATE_DATA_PAGE_SIZE of worklogs, which were updated or created after (inclusive) provided time in milliseconds. Returned worklogs are ordered by the update time.

Parameters
sinceInMilliseconds the time in unix timestamp format. since which the modified worklogs will be returned.
Returns
  • worklogs updated since provided time.

public int swapWorklogGroupRestriction (String groupName, String swapGroup)

Updates Worklog's such that worklogs that have a visibility restriction of the provided groupName will be changed to have a visibility restriction of the provided swapGroup.

Note: There is no validation performed by this method to determine if the provided swapGroup is a valid group with JIRA. This validation must be done by the caller.

Parameters
groupName identifies the group the worklogs are restricted by, this must not be null.
swapGroup identifies the group the worklogs will be changed to be restricted by, this must not be null.
Returns
  • tbe number of worklogs affected by the update.

public int swapWorklogRoleRestriction (Long roleId, Long swapRoleId)

Updates Worklog's such that worklogs that have a visibility restriction of the provided role will be changed to have a visibility restriction of a role with the provided swapRoleId.

Note: There is no validation performed by this method to determine if the provided swapGroup is a valid group with JIRA. This validation must be done by the caller.

Parameters
roleId identifies the role the worklogs are restricted by, this must not be null.
swapRoleId identifies the role the worklogs will be changed to be restricted by, this must not be null.
Returns
  • tbe number of worklogs affected by the update.

public Worklog update (ApplicationUser user, Worklog worklog, Long newEstimate, boolean dispatchEvent)

Updates the provided Worklog. This method will adjust the issue's remaining estimate to be the new value which has been passed to this method, the old remaining estimate value will be lost.

If you have provided a groupLevel then the worklog visibility will be restricted to the provided group, it is assumed that validation to insure that the group actually exists has been performed outside of this method. If you have provided a roleLevelId then the worklog visibility will be restricted to the provided role, it is assumed that validation to insure that the role actually exists has been performed outside of this method.

NOTE: this method does not do any permission checks to see if the user can perform the requested operation.

Parameters
user the user who is performing the action
worklog the value to update in the database
newEstimate the value to set the Issue's remainig estimate. If null the value will be left alone.
dispatchEvent if true then an event of type ISSUE_WORKLOG_UPDATED_ID will be dispatched and any notifications listening for that event will be triggered. If false no event will be dispatched.
Returns
  • the updated worklog