com.atlassian.jira.rest.client.api

Interface IssueRestClient

public interface IssueRestClient

The com.atlassian.jira.rest.client.api handling issue resources.

Since:

0.1

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	IssueRestClient.Expandos Expandos supported by getIssue(String, Iterable)

Method Summary

Methods

Modifier and Type	Method and Description
com.atlassian.util.concurrent.Promise<Void>	addAttachment(URI attachmentsUri, InputStream in, String filename) Uploads attachments to JIRA (adding it to selected issue)
com.atlassian.util.concurrent.Promise<Void>	addAttachments(URI attachmentsUri, AttachmentInput... attachments) Uploads attachments to JIRA (adding it to selected issue)
com.atlassian.util.concurrent.Promise<Void>	addAttachments(URI attachmentsUri, File... files) Uploads attachments to JIRA (adding it to selected issue)
com.atlassian.util.concurrent.Promise<Void>	addComment(URI commentsUri, Comment comment) Adds a comment to JIRA (adding it to selected issue)
com.atlassian.util.concurrent.Promise<Void>	addWatcher(URI watchersUri, String username) Adds selected person as a watcher for selected issue.
com.atlassian.util.concurrent.Promise<Void>	addWorklog(URI worklogUri, WorklogInput worklogInput) Adds new worklog entry to issue.
com.atlassian.util.concurrent.Promise<BasicIssue>	createIssue(IssueInput issue) Creates new issue.
com.atlassian.util.concurrent.Promise<BulkOperationResult<BasicIssue>>	createIssues(Collection<IssueInput> issues) Creates new issues in batch.
com.atlassian.util.concurrent.Promise<Void>	deleteIssue(String issueKey, boolean deleteSubtasks) Deletes issue with given issueKey.
com.atlassian.util.concurrent.Promise<InputStream>	getAttachment(URI attachmentUri) Retrieves the content of given attachment.
com.atlassian.util.concurrent.Promise<Iterable<CimProject>>	getCreateIssueMetadata(GetCreateIssueMetadataOptions options) Retrieves CreateIssueMetadata with specified filters.
com.atlassian.util.concurrent.Promise<Issue>	getIssue(String issueKey) Retrieves issue with selected issue key.
com.atlassian.util.concurrent.Promise<Issue>	getIssue(String issueKey, Iterable<IssueRestClient.Expandos> expand) Retrieves issue with selected issue key, with specified additional expandos.
com.atlassian.util.concurrent.Promise<Iterable<Transition>>	getTransitions(Issue issue) Retrieves complete information (if the caller has permission) about transitions available for the selected issue in its current state.
com.atlassian.util.concurrent.Promise<Iterable<Transition>>	getTransitions(URI transitionsUri) Retrieves complete information (if the caller has permission) about transitions available for the selected issue in its current state.
com.atlassian.util.concurrent.Promise<Votes>	getVotes(URI votesUri) Retrieves complete information (if the caller has permission) about voters for selected issue.
com.atlassian.util.concurrent.Promise<Watchers>	getWatchers(URI watchersUri) Retrieves complete information (if the caller has permission) about watchers for selected issue.
com.atlassian.util.concurrent.Promise<Void>	linkIssue(LinkIssuesInput linkIssuesInput) Creates link between two issues and adds a comment (optional) to the source issues.
com.atlassian.util.concurrent.Promise<Void>	removeWatcher(URI watchersUri, String username) Removes selected person from the watchers list for selected issue.
com.atlassian.util.concurrent.Promise<Void>	transition(Issue issue, TransitionInput transitionInput) Performs selected transition on selected issue.
com.atlassian.util.concurrent.Promise<Void>	transition(URI transitionsUri, TransitionInput transitionInput) Performs selected transition on selected issue.
com.atlassian.util.concurrent.Promise<Void>	unvote(URI votesUri) Removes your vote from the selected issue.
com.atlassian.util.concurrent.Promise<Void>	unwatch(URI watchersUri) Stops watching selected issue
com.atlassian.util.concurrent.Promise<Void>	updateIssue(String issueKey, IssueInput issue) Update an existing issue.
com.atlassian.util.concurrent.Promise<Void>	vote(URI votesUri) Casts your vote on the selected issue.
com.atlassian.util.concurrent.Promise<Void>	watch(URI watchersUri) Starts watching selected issue

Method Detail

createIssue

com.atlassian.util.concurrent.Promise<BasicIssue> createIssue(IssueInput issue)

Creates new issue.

Parameters:

issue - populated with data to create new issue

Returns:

basicIssue with generated issueKey

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

Since:

com.atlassian.jira.rest.client.api 1.0, server 5.0

updateIssue

com.atlassian.util.concurrent.Promise<Void> updateIssue(String issueKey,
                                                      IssueInput issue)

Update an existing issue.

Parameters:

issueKey - issue key (like TST-1, or JRA-9)

issue - populated with fields to set (no other verbs) in issue

Returns:

Void

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

Since:

com.atlassian.jira.rest.client.api 3.0, server 5.0

getCreateIssueMetadata

com.atlassian.util.concurrent.Promise<Iterable<CimProject>> getCreateIssueMetadata(@Nullable
                                                                                 GetCreateIssueMetadataOptions options)

Retrieves CreateIssueMetadata with specified filters.

Parameters:

options - optional request configuration like filters and expandos. You may use GetCreateIssueMetadataOptionsBuilder to build them. Pass null if you don't want to set any option.

Returns:

List of CimProject describing projects, issue types and fields.

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

Since:

com.atlassian.jira.rest.client.api 1.0, server 5.0

createIssues

com.atlassian.util.concurrent.Promise<BulkOperationResult<BasicIssue>> createIssues(Collection<IssueInput> issues)

Creates new issues in batch.

Parameters:

issues - populated with data to create new issue

Returns:

BulkOperationResult with generated issueKey and errors for failed issues

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

Since:

com.atlassian.jira.rest.client.api 2.0, server 6.0

getIssue

com.atlassian.util.concurrent.Promise<Issue> getIssue(String issueKey)

Retrieves issue with selected issue key.

Parameters:

issueKey - issue key (like TST-1, or JRA-9)

Returns:

issue with given issueKey

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

getIssue

com.atlassian.util.concurrent.Promise<Issue> getIssue(String issueKey,
                                                    Iterable<IssueRestClient.Expandos> expand)

Retrieves issue with selected issue key, with specified additional expandos.

Parameters:

issueKey - issue key (like TST-1, or JRA-9)

expand - additional expands. Currently CHANGELOG is the only supported expand that is not expanded by default.

Returns:

issue with given issueKey

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

Since:

0.6

deleteIssue

com.atlassian.util.concurrent.Promise<Void> deleteIssue(String issueKey,
                                                      boolean deleteSubtasks)

Deletes issue with given issueKey. You can set deleteSubtasks to delete issue with subtasks. If issue have subtasks and deleteSubtasks is set to false, then issue won't be deleted.

Parameters:

issueKey - issue key (like TST-1, or JRA-9)

deleteSubtasks - Determines if subtask of issue should be also deleted. If false, and issue has subtasks, then it won't be deleted.

Returns:

Void

Since:

2.0

getWatchers

com.atlassian.util.concurrent.Promise<Watchers> getWatchers(URI watchersUri)

Retrieves complete information (if the caller has permission) about watchers for selected issue.

Parameters:

watchersUri - URI of watchers resource for selected issue. Usually obtained by calling Issue.getWatchers().getSelf()

Returns:

detailed information about watchers watching selected issue.

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

See Also:

Issue.getWatchers()

getVotes

com.atlassian.util.concurrent.Promise<Votes> getVotes(URI votesUri)

Retrieves complete information (if the caller has permission) about voters for selected issue.

Parameters:

votesUri - URI of voters resource for selected issue. Usually obtained by calling Issue.getVotesUri()

Returns:

detailed information about voters of selected issue

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

See Also:

Issue.getVotesUri()

getTransitions

com.atlassian.util.concurrent.Promise<Iterable<Transition>> getTransitions(URI transitionsUri)

Retrieves complete information (if the caller has permission) about transitions available for the selected issue in its current state.

Parameters:

transitionsUri - URI of transitions resource of selected issue. Usually obtained by calling Issue.getTransitionsUri()

Returns:

transitions about transitions available for the selected issue in its current state.

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

getTransitions

com.atlassian.util.concurrent.Promise<Iterable<Transition>> getTransitions(Issue issue)

Retrieves complete information (if the caller has permission) about transitions available for the selected issue in its current state.

Parameters:

issue - issue

Returns:

transitions about transitions available for the selected issue in its current state.

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

Since:

v0.5

transition

com.atlassian.util.concurrent.Promise<Void> transition(URI transitionsUri,
                                                     TransitionInput transitionInput)

Performs selected transition on selected issue.

Parameters:

transitionsUri - URI of transitions resource of selected issue. Usually obtained by calling Issue.getTransitionsUri()

transitionInput - data for this transition (fields modified, the comment, etc.)

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

transition

com.atlassian.util.concurrent.Promise<Void> transition(Issue issue,
                                                     TransitionInput transitionInput)

Performs selected transition on selected issue.

Parameters:

issue - selected issue

transitionInput - data for this transition (fields modified, the comment, etc.)

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

Since:

v0.5

vote

com.atlassian.util.concurrent.Promise<Void> vote(URI votesUri)

Casts your vote on the selected issue. Casting a vote on already votes issue by the caller, causes the exception.

Parameters:

votesUri - URI of votes resource for selected issue. Usually obtained by calling Issue.getVotesUri()

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

unvote

com.atlassian.util.concurrent.Promise<Void> unvote(URI votesUri)

Removes your vote from the selected issue. Removing a vote from the issue without your vote causes the exception.

Parameters:

votesUri - URI of votes resource for selected issue. Usually obtained by calling Issue.getVotesUri()

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

watch

com.atlassian.util.concurrent.Promise<Void> watch(URI watchersUri)

Starts watching selected issue

Parameters:

watchersUri - URI of watchers resource for selected issue. Usually obtained by calling Issue.getWatchers().getSelf()

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

unwatch

com.atlassian.util.concurrent.Promise<Void> unwatch(URI watchersUri)

Stops watching selected issue

Parameters:

watchersUri - URI of watchers resource for selected issue. Usually obtained by calling Issue.getWatchers().getSelf()

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

addWatcher

com.atlassian.util.concurrent.Promise<Void> addWatcher(URI watchersUri,
                                                     String username)

Adds selected person as a watcher for selected issue. You need to have permissions to do that (otherwise the exception is thrown).

Parameters:

watchersUri - URI of watchers resource for selected issue. Usually obtained by calling Issue.getWatchers().getSelf()

username - user to add as a watcher

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

removeWatcher

com.atlassian.util.concurrent.Promise<Void> removeWatcher(URI watchersUri,
                                                        String username)

Removes selected person from the watchers list for selected issue. You need to have permissions to do that (otherwise the exception is thrown).

Parameters:

watchersUri - URI of watchers resource for selected issue. Usually obtained by calling Issue.getWatchers().getSelf()

username - user to remove from the watcher list

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, etc.)

linkIssue

com.atlassian.util.concurrent.Promise<Void> linkIssue(LinkIssuesInput linkIssuesInput)

Creates link between two issues and adds a comment (optional) to the source issues.

Parameters:

linkIssuesInput - details for the link and the comment (optional) to be created

Throws:

RestClientException - in case of problems (connectivity, malformed messages, invalid argument, permissions, etc.)

Since:

com.atlassian.jira.rest.client.api 0.2, server 4.3

addAttachment

com.atlassian.util.concurrent.Promise<Void> addAttachment(URI attachmentsUri,
                                                        InputStream in,
                                                        String filename)

Uploads attachments to JIRA (adding it to selected issue)

Parameters:

attachmentsUri - where to upload the attachment. You can get this URI by examining issue resource first

in - stream from which to read data to upload

filename - file name to use for the uploaded attachment

Since:

com.atlassian.jira.rest.client.api 0.2, server 4.3

addAttachments

com.atlassian.util.concurrent.Promise<Void> addAttachments(URI attachmentsUri,
                                                         AttachmentInput... attachments)

Uploads attachments to JIRA (adding it to selected issue)

Parameters:

attachmentsUri - where to upload the attachments. You can get this URI by examining issue resource first

attachments - attachments to upload

Since:

com.atlassian.jira.rest.client.api 0.2, server 4.3

addAttachments

com.atlassian.util.concurrent.Promise<Void> addAttachments(URI attachmentsUri,
                                                         File... files)

Uploads attachments to JIRA (adding it to selected issue)

Parameters:

attachmentsUri - where to upload the attachments. You can get this URI by examining issue resource first

files - files to upload

Since:

com.atlassian.jira.rest.client.api 0.2, server 4.3

addComment

com.atlassian.util.concurrent.Promise<Void> addComment(URI commentsUri,
                                                     Comment comment)

Adds a comment to JIRA (adding it to selected issue)

Parameters:

commentsUri - where to add comment

comment - the Comment to add

Since:

com.atlassian.jira.rest.client.api 1.0, server 5.0

getAttachment

@Beta
com.atlassian.util.concurrent.Promise<InputStream> getAttachment(URI attachmentUri)

Retrieves the content of given attachment.

Parameters:

attachmentUri - URI for the attachment to retrieve

Returns:

stream from which the caller may read the attachment content (bytes). The caller is responsible for closing the stream.

addWorklog

com.atlassian.util.concurrent.Promise<Void> addWorklog(URI worklogUri,
                                                     WorklogInput worklogInput)

Adds new worklog entry to issue.

Parameters:

worklogUri - URI for worklog in issue

worklogInput - worklog input object to create