Package com.atlassian.jira.bc.issue.worklog

Interface WorklogService

All Known Implementing Classes:
DefaultWorklogService
@PublicApi public interface WorklogService
This is the business layer component that must be used to access all WorklogService functionality. This will perform validation before it hands off to the WorklogManager. Operations will not be performed if validation fails.

  • Method Details

    • validateDelete

      WorklogResult validateDelete(JiraServiceContext jiraServiceContext, Long worklogId)
      Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToDelete(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to delete a worklog for this issue.
      Parameters:
      jiraServiceContext - containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
      worklogId - identifies the worklog that the update validation will occur against
      Returns:
      WorklogResult which can be passed to the delete methods if has permission and the data passed in is valid, null otherwise

    • validateDeleteWithNewEstimate

      WorklogNewEstimateResult validateDeleteWithNewEstimate(JiraServiceContext jiraServiceContext, Long worklogId, String newEstimate)
      Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToDelete(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to delete a worklog for this issue.
      Parameters:
      jiraServiceContext - containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
      worklogId - identifies the worklog that the delete validation will occur against
      newEstimate - The value to change the issues remaining estimate to.
      Returns:
      Worklog which can be passed to the delete methods if has permission and the data passed in is valid, null otherwise

    • validateDeleteWithManuallyAdjustedEstimate

      WorklogAdjustmentAmountResult validateDeleteWithManuallyAdjustedEstimate(JiraServiceContext jiraServiceContext, Long worklogId, String adjustmentAmount)
      Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToDelete(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to delete a worklog for this issue.
      Parameters:
      jiraServiceContext - containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
      worklogId - identifies the worklog that the delete validation will occur against
      adjustmentAmount - The value to increase the issues remaining estimate by.
      Returns:
      Worklog which can be passed to the delete methods if has permission and the data passed in is valid, null otherwise

    • deleteWithNewRemainingEstimate

      boolean deleteWithNewRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateResult worklogNewEstimate, boolean dispatchEvent)
      Deletes the specified Worklog. This method will adjust the issues remaining estimate to be the new value which has been passed to this method, the old remaining estimate value will be lost.
      Parameters:
      jiraServiceContext - containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
      worklogNewEstimate - the Worklog and new estimate for the issue.
      dispatchEvent - whether or not you want to have an event dispatched on Worklog delete @return the deleted Worklog object, or null if no object has been deleted.
      Returns:
      true if the Worklog was successfully deleted, false otherwise

    • deleteWithManuallyAdjustedEstimate

      boolean deleteWithManuallyAdjustedEstimate(JiraServiceContext jiraServiceContext, WorklogAdjustmentAmountResult worklogAdjustmentAmount, boolean dispatchEvent)
      Deletes the specified Worklog. This method will adjust the issues remaining estimate to be the new value which has been passed to this method, the old remaining estimate value will be lost.
      Parameters:
      jiraServiceContext - containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
      worklogAdjustmentAmount - the Worklog and adjustmentAmount for the issue.
      dispatchEvent - whether or not you want to have an event dispatched on Worklog delete @return the deleted Worklog object, or null if no object has been deleted.
      Returns:
      true if the Worklog was successfully deleted, false otherwise

    • deleteAndRetainRemainingEstimate

      boolean deleteAndRetainRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
      Deletes the specified Worklog. This method will make no adjustment to the issues remaining estimate.
      Parameters:
      jiraServiceContext - containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
      worklogResult - result of the call to validateDelete(com.atlassian.jira.bc.JiraServiceContext, Long) which contains the Worklog to delete
      dispatchEvent - whether or not you want to have an event dispatched on Worklog delete
      Returns:
      true if the Worklog was successfully deleted, false otherwise

    • deleteAndAutoAdjustRemainingEstimate

      boolean deleteAndAutoAdjustRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
      Deletes the specified Worklog. This method will auto-adjust the issues remaining estimate by adding the time spent on the deleted worklog.
      Parameters:
      jiraServiceContext - containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
      worklogResult - result of the call to validateDelete(com.atlassian.jira.bc.JiraServiceContext, Long) which contains the Worklog to delete
      dispatchEvent - whether or not you want to have an event dispatched on Worklog delete
      Returns:
      true if the Worklog was successfully deleted, false otherwise

    • validateUpdate

      WorklogResult validateUpdate(JiraServiceContext jiraServiceContext, WorklogInputParameters params)
      Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToUpdate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to update a worklog for this issue.
      Parameters:
      jiraServiceContext - containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
      params - parameter object that contains all the values required to validate
      Returns:
      WorklogResult which can be passed to the update methods if has permission and the data passed in is valid, null otherwise

    • validateUpdateWithNewEstimate

      WorklogNewEstimateResult validateUpdateWithNewEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateInputParameters params)
      Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToUpdate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to update a worklog for this issue.
      Parameters:
      jiraServiceContext - containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
      params - parameter object that contains all the values required to validate
      Returns:
      WorklogResult which can be passed to the update methods if has permission and the data passed in is valid, null otherwise

    • updateWithNewRemainingEstimate

      Worklog updateWithNewRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateResult worklogNewEstimate, boolean dispatchEvent)
      Updates the provided Worklog. This method will adjust the issues remaining estimate to be the new value which has been passed to this method, the old remaining estimate value will be lost.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      worklogNewEstimate - the Worklog and new estimate for the issue.
      dispatchEvent - whether or not you want to have an event dispatched on Worklog update @return the updated Worklog object, or null if no object has been updated.
      Returns:
      the updated Worklog object, or null if no object has been updated.

    • updateAndRetainRemainingEstimate

      Worklog updateAndRetainRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
      Updates the provided Worklog. This method will make no adjustment to the issues remaining estimate.
      Parameters:
      jiraServiceContext - containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
      worklogResult - result of the call to validateUpdate(com.atlassian.jira.bc.JiraServiceContext, WorklogInputParameters) which contains the Worklog to update
      dispatchEvent - whether or not you want to have an event dispatched on Worklog update
      Returns:
      the updated Worklog object, or null if no object has been updated.

    • updateAndAutoAdjustRemainingEstimate

      Worklog updateAndAutoAdjustRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
      Updates the provided Worklog. This method will auto-adjust the issues remaining estimate based on the updated value of the time spent on the work.
      Parameters:
      jiraServiceContext - containing the User who wishes to update the worklog and the ErrorCollection that will contain any errors in calling the method
      worklogResult - result of the call to validateUpdate(com.atlassian.jira.bc.JiraServiceContext, WorklogInputParameters) which contains the Worklog to update
      dispatchEvent - whether or not you want to have an event dispatched on Worklog update
      Returns:
      the update Worklog object, or null if no object has been updated.

    • hasPermissionToUpdate

      boolean hasPermissionToUpdate(JiraServiceContext jiraServiceContext, Worklog worklog)
      Determine whether the current user has the permission to update the supplied worklog, timetracking is enabled in JIRA and that the associated issue is in an editable workflow state.

      In case of errors, add error messages to the error collection within the servicecontext.

      Passing in null worklog or a worklog with null ID will return false and an error message will be added to the error collection.

      Passing in null error collection will throw NPE.

      This method will return true if the user is a member of the worklog's group/role level (if specified) AND

      and false otherwise.
      Parameters:
      jiraServiceContext - containing the User who wishes to update the worklog and the ErrorCollection that will contain any errors in calling the method
      worklog - the Worklog the user wishes to update
      Returns:
      true if the user has permission to update the supplied worklog, false otherwise

    • hasPermissionToDelete

      boolean hasPermissionToDelete(JiraServiceContext jiraServiceContext, Worklog worklog)
      Determine whether the current user has the permission to delete the supplied worklog, timetracking is enabled in JIRA and that the associated issue is in an editable workflow state.

      In case of errors, add error messages to the error collection within the servicecontext.

      Passing in null worklog or a worklog with null ID will return false and an error message will be added to the error collection.

      Passing in null error collection will throw NPE.

      This method will return true if the user is a member of the worklog's group/role level (if specified) AND

      and false otherwise.
      Parameters:
      jiraServiceContext - containing the User who wishes to delete the worklog and the ErrorCollection that will contain any errors in calling the method
      worklog - the Worklog the user wishes to delete
      Returns:
      true if the user has permission to delete the supplied worklog, false otherwise

    • validateCreate

      WorklogResult validateCreate(JiraServiceContext jiraServiceContext, WorklogInputParameters params)
      Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToCreate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.Issue, boolean) to create a worklog for this issue.
      Parameters:
      jiraServiceContext - containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
      params - parameter object that contains all the values required to validate
      Returns:
      WorklogResult which can be passed to the create methods if has permission and the data passed in is valid, null otherwise

    • validateCreateWithNewEstimate

      WorklogNewEstimateResult validateCreateWithNewEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateInputParameters params)
      Determines whether worklogs are enabled in JIRA and if the user has the required permission as determined by calling hasPermissionToCreate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.Issue, boolean) to create a worklog for this issue.
      Parameters:
      jiraServiceContext - containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
      params - parameter object that contains all the values required to validate
      Returns:
      WorklogNewEstimateResult the Worklog of which can be passed to the create methods if has permission and the data passed in is valid, null otherwise

    • validateCreateWithManuallyAdjustedEstimate

      WorklogAdjustmentAmountResult validateCreateWithManuallyAdjustedEstimate(JiraServiceContext jiraServiceContext, WorklogAdjustmentAmountInputParameters params)
      Determines whether worklogs are enabled in JIRA and if the user has the required permission as determined by calling hasPermissionToCreate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.Issue, boolean) to create a worklog for this issue.
      Parameters:
      jiraServiceContext - containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
      params - parameter object that contains all the values required to validate
      Returns:
      WorklogAdjustmentAmountResult the Worklog of which can be passed to the create methods if has permission and the data passed in is valid, null otherwise

    • createWithNewRemainingEstimate

      Worklog createWithNewRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateResult worklogNewEstimate, boolean dispatchEvent)
      Persists a new Worklog on the given Issue. This method will adjust the issues remaining estimate to be the new value which has been passed to this method, the old remaining estimate value will be lost.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      worklogNewEstimate - the Worklog and new estimate for the issue.
      dispatchEvent - whether or not you want to have an event dispatched on Worklog creation
      Returns:
      the created Worklog object or null if no object was created.
      See Also:

    • createWithManuallyAdjustedEstimate

      Worklog createWithManuallyAdjustedEstimate(JiraServiceContext jiraServiceContext, WorklogAdjustmentAmountResult worklogAdjustmentAmount, boolean dispatchEvent)
      Persists a new Worklog on the given Issue. This method will adjust the issues remaining estimate by reducing by the adjustmentAmount which has been passed to this method. Before calling this method, you must call validateCreateWithManuallyAdjustedEstimate() to ensure that the creation is OK.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      worklogAdjustmentAmount - the Worklog and adjustmentAmount for the issue.
      dispatchEvent - whether or not you want to have an event dispatched on Worklog creation
      Returns:
      the created Worklog object or null if no object was created.
      See Also:

    • createAndRetainRemainingEstimate

      Worklog createAndRetainRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
      Persists a new Worklog on the given Issue. This method will make no adjustment to the issues remaining estimate.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      worklogResult - the WorklogResult generated by the validate call
      dispatchEvent - whether or not you want to have an event dispatched on Worklog creation @return the created Worklog object, or null if no object created.
      Returns:
      the created Worklog object or null if no object was created.

    • createAndAutoAdjustRemainingEstimate

      Worklog createAndAutoAdjustRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
      Persists a new Worklog on the given Issue. This method will auto-adjust the issues remaining estimate based on the value of the time spent on the work.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      worklogResult - the WorklogResult generated by the validate call
      dispatchEvent - whether or not you want to have an event dispatched on Worklog creation @return the created Worklog object, or null if no object created.
      Returns:
      the created Worklog object or null if no object was created.

    • hasPermissionToCreate

      boolean hasPermissionToCreate(JiraServiceContext jiraServiceContext, Issue issue, boolean isEditableCheckRequired)
      Determines if the user has the Permissions.WORK_ISSUE permission, that timetracking is enabled in JIRA and that the associated issue is in an editable workflow state.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      issue - the issue to add the worklog to
      isEditableCheckRequired - set to true if we require the issue to be in an editable state. This should always be the case except when logging work on transition
      Returns:
      true if the user has permission to create a worklog on the specified issue, false otherwise

    • getById

      Worklog getById(JiraServiceContext jiraServiceContext, Long id)
      Used to get a worklog by its id.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      id - uniquely identifies the worklog
      Returns:
      returns the worklog for the passed in id, null if not found.

    • getWorklogsUpdatedSince

      WorklogChangedSincePage<Worklog> getWorklogsUpdatedSince(ApplicationUser user, Long sinceInMilliseconds)
      Returns a list of worklogs visible by the calling user, which were modified since time provided in . The list is limited to WorklogManager.WORKLOG_UPDATE_DATA_PAGE_SIZE elements, in order to get more elements, execute this method again with which is equal to the updated time of the last element in the result. This won't return worklogs updated within last minute.
      Parameters:
      user - user retrieving the list of modified worklogs since a qiven time expressed in miliseconds.
      sinceInMilliseconds - the time (measured as a difference between the timestamp and midnight, January 1, 1970 UTC) since which the modified worklogs will be returned.
      Returns:
      a list of worklogs visible by the calling users, which were modified since the time provided in .

    • getWorklogsDeletedSince

      WorklogChangedSincePage<DeletedWorklog> getWorklogsDeletedSince(ApplicationUser user, Long sinceInMilliseconds)
      Returns a list of ids of worklogs which were removed, since the time provided in . The list is limited to WorklogManager.WORKLOG_UPDATE_DATA_PAGE_SIZE elements, in order to get more elements, execute this method again with which is equal to removal time of the last element in the result. This won't return worklogs updated within last minute.
      Parameters:
      user - user retrieving the list of deleted worklogs since a qiven time expressed in milliseconds.
      sinceInMilliseconds - the time (measured as a difference between the timestamp and midnight, January 1, 1970 UTC) since which the deleted worklogs will be returned.
      Returns:
      a list of ids of deleted worklogs, which were removed since the time provided in .

    • getWorklogsForIds

      ServiceOutcome<Set<Worklog>> getWorklogsForIds(JiraServiceContext jiraServiceContext, Set<Long> idsOfWorklogs)
      Returns a set of worklogs for provided ids. If the calling user doesn't have permissions to get worklog for given id, the worklog won't be returned. The set is limited to WorklogManager.WORKLOG_UPDATE_DATA_PAGE_SIZE elements, in order to get more elements, execute this method again providing ids of other Worklog to retrieve.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      idsOfWorklogs - set of ids for which worklogs will be returned.
      Returns:
      a set of worklogs for provided ids.

    • getByIssue

      List getByIssue(JiraServiceContext jiraServiceContext, Issue issue)
      Returns all child worklogs of a specified issue.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      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

    • getByIssueVisibleToUser

      List<Worklog> getByIssueVisibleToUser(JiraServiceContext jiraServiceContext, Issue issue)
      Returns all child worklogs of a specified issue that the provided user has permission to see.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      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

    • getByIssueVisibleToUser

      Window<Worklog> getByIssueVisibleToUser(CommentSearchParameters parameters)
      Returns child worklogs filtered according CommentSearchParameters to parameters. CommentSearchParameters are used because they are able to handle focused items.
      Parameters:
      parameters - parameters for search (not null)
      Returns:
      a Window of Worklogs, ordered by start date. An empty Window will be returned if none are found

    • getByIssueVisibleToUser

      PagedList<Worklog> getByIssueVisibleToUser(JiraServiceContext jiraServiceContext, Issue issue, int pageSize)
      Returns a PagedList over all all child worklogs of a specified issue that the provided user has permission to see.
      Parameters:
      jiraServiceContext - containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
      issue - the specified parent issue (not null)
      pageSize - the number of worklogs per page
      Returns:
      a List of Worklogs, ordered by creation date. An empty List will be returned if none are found

    • isTimeTrackingEnabled

      boolean isTimeTrackingEnabled()
      Will return true if APKeys.JIRA_OPTION_TIMETRACKING is true, false otherwise.
      Returns:
      true if enabled, false otherwise.

    • isIssueInEditableWorkflowState

      boolean isIssueInEditableWorkflowState(Issue issue)
      Will return true if the issue is in an editable workflow state.
      Parameters:
      issue - the issue to see if it is in an editable store
      Returns:
      true if editable, false otherwise