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<java.lang.Void>	addAttachment(java.net.URI attachmentsUri, java.io.InputStream in, java.lang.String filename) Uploads attachments to JIRA (adding it to selected issue)
com.atlassian.util.concurrent.Promise<java.lang.Void>	addAttachments(java.net.URI attachmentsUri, AttachmentInput... attachments) Uploads attachments to JIRA (adding it to selected issue)
com.atlassian.util.concurrent.Promise<java.lang.Void>	addAttachments(java.net.URI attachmentsUri, java.io.File... files) Uploads attachments to JIRA (adding it to selected issue)
com.atlassian.util.concurrent.Promise<java.lang.Void>	addComment(java.net.URI commentsUri, Comment comment) Adds a comment to JIRA (adding it to selected issue)
com.atlassian.util.concurrent.Promise<java.lang.Void>	addWatcher(java.net.URI watchersUri, java.lang.String username) Adds selected person as a watcher for selected issue.
com.atlassian.util.concurrent.Promise<java.lang.Void>	addWorklog(java.net.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(java.util.Collection<IssueInput> issues) Creates new issues in batch.
com.atlassian.util.concurrent.Promise<java.io.InputStream>	getAttachment(java.net.URI attachmentUri) Retrieves the content of given attachment.
com.atlassian.util.concurrent.Promise<java.lang.Iterable<CimProject>>	getCreateIssueMetadata(GetCreateIssueMetadataOptions options) Retrieves CreateIssueMetadata with specified filters.
com.atlassian.util.concurrent.Promise<Issue>	getIssue(java.lang.String issueKey) Retrieves issue with selected issue key.
com.atlassian.util.concurrent.Promise<Issue>	getIssue(java.lang.String issueKey, java.lang.Iterable<IssueRestClient.Expandos> expand) Retrieves issue with selected issue key, with specified additional expandos.
com.atlassian.util.concurrent.Promise<java.lang.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<java.lang.Iterable<Transition>>	getTransitions(java.net.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(java.net.URI votesUri) Retrieves complete information (if the caller has permission) about voters for selected issue.
com.atlassian.util.concurrent.Promise<Watchers>	getWatchers(java.net.URI watchersUri) Retrieves complete information (if the caller has permission) about watchers for selected issue.
com.atlassian.util.concurrent.Promise<java.lang.Void>	linkIssue(LinkIssuesInput linkIssuesInput) Creates link between two issues and adds a comment (optional) to the source issues.
com.atlassian.util.concurrent.Promise<java.lang.Void>	removeWatcher(java.net.URI watchersUri, java.lang.String username) Removes selected person from the watchers list for selected issue.
com.atlassian.util.concurrent.Promise<java.lang.Void>	transition(Issue issue, TransitionInput transitionInput) Performs selected transition on selected issue.
com.atlassian.util.concurrent.Promise<java.lang.Void>	transition(java.net.URI transitionsUri, TransitionInput transitionInput) Performs selected transition on selected issue.
com.atlassian.util.concurrent.Promise<java.lang.Void>	unvote(java.net.URI votesUri) Removes your vote from the selected issue.
com.atlassian.util.concurrent.Promise<java.lang.Void>	unwatch(java.net.URI watchersUri) Stops watching selected issue
com.atlassian.util.concurrent.Promise<java.lang.Void>	vote(java.net.URI votesUri) Casts your vote on the selected issue.
com.atlassian.util.concurrent.Promise<java.lang.Void>	watch(java.net.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

getCreateIssueMetadata

com.atlassian.util.concurrent.Promise<java.lang.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(java.util.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(java.lang.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(java.lang.String issueKey,
                                                    java.lang.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

getWatchers

com.atlassian.util.concurrent.Promise<Watchers> getWatchers(java.net.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(java.net.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<java.lang.Iterable<Transition>> getTransitions(java.net.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<java.lang.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<java.lang.Void> transition(java.net.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<java.lang.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<java.lang.Void> vote(java.net.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<java.lang.Void> unvote(java.net.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<java.lang.Void> watch(java.net.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<java.lang.Void> unwatch(java.net.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<java.lang.Void> addWatcher(java.net.URI watchersUri,
                                                               java.lang.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<java.lang.Void> removeWatcher(java.net.URI watchersUri,
                                                                  java.lang.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<java.lang.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<java.lang.Void> addAttachment(java.net.URI attachmentsUri,
                                                                  java.io.InputStream in,
                                                                  java.lang.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<java.lang.Void> addAttachments(java.net.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<java.lang.Void> addAttachments(java.net.URI attachmentsUri,
                                                                   java.io.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<java.lang.Void> addComment(java.net.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<java.io.InputStream> getAttachment(java.net.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<java.lang.Void> addWorklog(java.net.URI worklogUri,
                                                               WorklogInput worklogInput)

Adds new worklog entry to issue.

Parameters:

worklogUri - URI for worklog in issue

worklogInput - worklog input object to create