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<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>	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

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

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