net.rcarz.jiraclient

Class Issue

java.lang.Object

net.rcarz.jiraclient.Resource

net.rcarz.jiraclient.Issue

public class Issue
extends Resource

Represents a JIRA issue.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Issue.FluentCreate Used to chain fields to a create action.
static class	Issue.FluentRemoteLink Used to create remote links.
class	Issue.FluentTransition Used to chain fields to a transition action.
class	Issue.FluentUpdate Used to chain fields to an update action.
static class	Issue.NewAttachment
static class	Issue.SearchResult Issue search results structure.

Field Summary

Fields inherited from class net.rcarz.jiraclient.Resource

apirev, DEFAULT_API_REV, id, restclient, self

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Issue(RestClient restclient, net.sf.json.JSONObject json) Creates an issue from a JSON payload.

Method Summary

Modifier and Type	Method and Description
void	addAttachment(File file) Adds an attachment to this issue.
void	addAttachments(Issue.NewAttachment... attachments) Adds an attachments to this issue.
Comment	addComment(String body) Adds a comment to this issue.
Comment	addComment(String body, String visType, String visName) Adds a comment to this issue with limited visibility.
void	addRemoteLink(String url, String title, String summary) Adds a remote link to this issue.
void	addWatcher(String username) Adds a watcher to the issue.
WorkLog	addWorkLog(String comment, org.joda.time.DateTime startDate, long timeSpentSeconds) Adds WorkLog to this issue
static int	count(RestClient restclient, String jql) count issues with the given query.
static Issue.FluentCreate	create(RestClient restclient, String project, String issueType) Creates a new JIRA issue.
Issue.FluentCreate	createSubtask() Creates a new sub-task.
boolean	delete(boolean deleteSubtasks)
void	deleteWatcher(String username) Removes a watcher to the issue.
static Issue	get(RestClient restclient, String key) Retrieves the given issue record.
static Issue	get(RestClient restclient, String key, String includedFields) Retrieves the given issue record.
static Issue	get(RestClient restclient, String key, String includedFields, String expand) Retrieves the given issue record.
List<WorkLog>	getAllWorkLogs()
User	getAssignee()
List<Attachment>	getAttachments()
ChangeLog	getChangeLog()
List<Comment>	getComments()
List<Component>	getComponents()
Date	getCreatedDate()
static net.sf.json.JSONObject	getCreateMetadata(RestClient restclient, String project, String issueType)
String	getDescription()
Date	getDueDate()
Object	getField(String name) Gets an arbitrary field by its name.
List<Version>	getFixVersions()
List<IssueLink>	getIssueLinks()
IssueType	getIssueType()
String	getKey()
List<String>	getLabels()
Issue	getParent()
Priority	getPriority()
Project	getProject()
List<RemoteLink>	getRemoteLinks()
User	getReporter()
Resolution	getResolution()
Date	getResolutionDate()
Security	getSecurity()
Status	getStatus()
List<Issue>	getSubtasks()
String	getSummary()
Integer	getTimeEstimate()
Integer	getTimeSpent()
TimeTracking	getTimeTracking()
List<Transition>	getTransitions()
Date	getUpdatedDate()
List<Version>	getVersions()
Votes	getVotes()
Watches	getWatches()
List<WorkLog>	getWorkLogs()
void	link(String issue, String type) Links this issue with another issue.
void	link(String issue, String type, String body) Links this issue with another issue and adds a comment.
void	link(String issue, String type, String body, String visType, String visName) Links this issue with another issue and adds a comment with limited visibility.
void	refresh() Reloads issue data from the JIRA server (issue includes all navigable fields).
void	refresh(String includedFields) Reloads issue data from the JIRA server and specify which fields to retrieve.
Issue.FluentRemoteLink	remoteLink() Adds a remote link to this issue.
void	removeAttachment(String attachmentId) Removes an attachments.
static Issue.SearchResult	search(RestClient restclient, String jql, String includedFields, String expandFields, Integer maxResults, Integer startAt) Search for issues with the given query and specify which fields to retrieve.
String	toString()
Issue.FluentTransition	transition() Begins a transition field chain.
void	unvote() Removes the current user's vote from the issue.
Issue.FluentUpdate	update() Begins an update field chain.
void	vote() Casts a vote in favour of an issue.

Methods inherited from class net.rcarz.jiraclient.Resource

getApiRev, getAuthUri, getBaseUri, getId, getSelf, getUrl, setApiRev

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Issue

protected Issue(RestClient restclient,
                net.sf.json.JSONObject json)

Creates an issue from a JSON payload.

Parameters:

restclient - REST client instance

json - JSON payload

Method Detail

count

public static int count(RestClient restclient,
                        String jql)
                 throws JiraException

count issues with the given query.

Parameters:

restclient - REST client instance

jql - JQL statement

Returns:

the count

Throws:

JiraException - when the search fails

getCreateMetadata

public static net.sf.json.JSONObject getCreateMetadata(RestClient restclient,
                                                       String project,
                                                       String issueType)
                                                throws JiraException

Throws:

JiraException

getTransitions

public List<Transition> getTransitions()
                                throws JiraException

Throws:

JiraException

addAttachment

public void addAttachment(File file)
                   throws JiraException

Adds an attachment to this issue.

Parameters:

file - java.io.File

Throws:

JiraException - when the attachment creation fails

addRemoteLink

public void addRemoteLink(String url,
                          String title,
                          String summary)
                   throws JiraException

Adds a remote link to this issue.

Parameters:

url - Url of the remote link

title - Title of the remote link

summary - Summary of the remote link

Throws:

JiraException - when the link creation fails

See Also:

remoteLink()

remoteLink

public Issue.FluentRemoteLink remoteLink()

Adds a remote link to this issue. At least set the url or globalId and title before creating the link.

Returns:

a fluent remote link instance

addAttachments

public void addAttachments(Issue.NewAttachment... attachments)
                    throws JiraException

Adds an attachments to this issue.

Parameters:

attachments - the attachments to add

Throws:

JiraException - when the attachments creation fails

removeAttachment

public void removeAttachment(String attachmentId)
                      throws JiraException

Removes an attachments.

Parameters:

attachmentId - attachment id to remove

Throws:

JiraException - when the attachment removal fails

addComment

public Comment addComment(String body)
                   throws JiraException

Adds a comment to this issue.

Parameters:

body - Comment text

Throws:

JiraException - when the comment creation fails

addComment

public Comment addComment(String body,
                          String visType,
                          String visName)
                   throws JiraException

Adds a comment to this issue with limited visibility.

Parameters:

body - Comment text

visType - Target audience type (role or group)

visName - Name of the role or group to limit visibility to

Throws:

JiraException - when the comment creation fails

addWorkLog

public WorkLog addWorkLog(String comment,
                          org.joda.time.DateTime startDate,
                          long timeSpentSeconds)
                   throws JiraException

Adds WorkLog to this issue

Parameters:

comment - provided comment

startDate - provided start date

timeSpentSeconds - provided time spent. This cannot be lower than 1m inute

Returns:

Throws:

JiraException - when worklog creation fails

link

public void link(String issue,
                 String type)
          throws JiraException

Links this issue with another issue.

Parameters:

issue - Other issue key

type - Link type name

Throws:

JiraException - when the link creation fails

link

public void link(String issue,
                 String type,
                 String body)
          throws JiraException

Links this issue with another issue and adds a comment.

Parameters:

issue - Other issue key

type - Link type name

body - Comment text

Throws:

JiraException - when the link creation fails

link

public void link(String issue,
                 String type,
                 String body,
                 String visType,
                 String visName)
          throws JiraException

Links this issue with another issue and adds a comment with limited visibility.

Parameters:

issue - Other issue key

type - Link type name

body - Comment text

visType - Target audience type (role or group)

visName - Name of the role or group to limit visibility to

Throws:

JiraException - when the link creation fails

create

public static Issue.FluentCreate create(RestClient restclient,
                                        String project,
                                        String issueType)
                                 throws JiraException

Creates a new JIRA issue.

Parameters:

restclient - REST client instance

project - Key of the project to create the issue in

issueType - Name of the issue type to create

Returns:

a fluent create instance

Throws:

JiraException - when the client fails to retrieve issue metadata

createSubtask

public Issue.FluentCreate createSubtask()
                                 throws JiraException

Creates a new sub-task.

Returns:

a fluent create instance

Throws:

JiraException - when the client fails to retrieve issue metadata

get

public static Issue get(RestClient restclient,
                        String key)
                 throws JiraException

Retrieves the given issue record.

Parameters:

restclient - REST client instance

key - Issue key (PROJECT-123)

Returns:

an issue instance (issue includes all navigable fields)

Throws:

JiraException - when the retrieval fails

get

public static Issue get(RestClient restclient,
                        String key,
                        String includedFields)
                 throws JiraException

Retrieves the given issue record.

Parameters:

restclient - REST client instance

key - Issue key (PROJECT-123)

includedFields - Specifies which issue fields will be included in the result.
Some examples how this parameter works:

• *all - include all fields
• *navigable - include just navigable fields
• summary,comment - include just the summary and comments
• *all,-comment - include all fields

Returns:

an issue instance

Throws:

JiraException - when the retrieval fails

get

public static Issue get(RestClient restclient,
                        String key,
                        String includedFields,
                        String expand)
                 throws JiraException

Retrieves the given issue record.

Parameters:

restclient - REST client instance

key - Issue key (PROJECT-123)

includedFields - Specifies which issue fields will be included in the result.
Some examples how this parameter works:

• *all - include all fields
• *navigable - include just navigable fields
• summary,comment - include just the summary and comments
• *all,-comment - include all fields

expand - fields to expand when obtaining the issue

Returns:

an issue instance

Throws:

JiraException - when the retrieval fails

search

public static Issue.SearchResult search(RestClient restclient,
                                        String jql,
                                        String includedFields,
                                        String expandFields,
                                        Integer maxResults,
                                        Integer startAt)
                                 throws JiraException

Search for issues with the given query and specify which fields to retrieve. If the total results is bigger than the maximum returned results, then further calls can be made using different values for the startAt field to obtain all the results.

Parameters:

restclient - REST client instance

jql - JQL statement

includedFields - Specifies which issue fields will be included in the result.
Some examples how this parameter works:

• *all - include all fields
• *navigable - include just navigable fields
• summary,comment - include just the summary and comments
• *all,-comment - include all fields

maxResults - if non-null, defines the maximum number of results that can be returned

startAt - if non-null, defines the first issue to return

expandFields - fields to expand when obtaining the issue

Returns:

a search result structure with results

Throws:

JiraException - when the search fails

refresh

public void refresh()
             throws JiraException

Reloads issue data from the JIRA server (issue includes all navigable fields).

Throws:

JiraException - when the retrieval fails

refresh

public void refresh(String includedFields)
             throws JiraException

Reloads issue data from the JIRA server and specify which fields to retrieve.

Parameters:

includedFields - Specifies which issue fields will be included in the result.
Some examples how this parameter works:

• *all - include all fields
• *navigable - include just navigable fields
• summary,comment - include just the summary and comments
• *all,-comment - include all fields

Throws:

JiraException - when the retrieval fails

getField

public Object getField(String name)

Gets an arbitrary field by its name.

Parameters:

name - Name of the field to retrieve

Returns:

the field value or null if not found

transition

public Issue.FluentTransition transition()
                                  throws JiraException

Begins a transition field chain.

Returns:

a fluent transition instance

Throws:

JiraException - when the client fails to retrieve issue metadata

update

public Issue.FluentUpdate update()
                          throws JiraException

Begins an update field chain.

Returns:

a fluent update instance

Throws:

JiraException - when the client fails to retrieve issue metadata

vote

public void vote()
          throws JiraException

Casts a vote in favour of an issue.

Throws:

JiraException - when the voting fails

unvote

public void unvote()
            throws JiraException

Removes the current user's vote from the issue.

Throws:

JiraException - when the voting fails

addWatcher

public void addWatcher(String username)
                throws JiraException

Adds a watcher to the issue.

Parameters:

username - Username of the watcher to add

Throws:

JiraException - when the operation fails

deleteWatcher

public void deleteWatcher(String username)
                   throws JiraException

Removes a watcher to the issue.

Parameters:

username - Username of the watcher to remove

Throws:

JiraException - when the operation fails

toString

public String toString()

Overrides:

toString in class Object

getChangeLog

public ChangeLog getChangeLog()

getKey

public String getKey()

getAssignee

public User getAssignee()

getAttachments

public List<Attachment> getAttachments()

getComments

public List<Comment> getComments()

getComponents

public List<Component> getComponents()

getDescription

public String getDescription()

getDueDate

public Date getDueDate()

getFixVersions

public List<Version> getFixVersions()

getIssueLinks

public List<IssueLink> getIssueLinks()

getIssueType

public IssueType getIssueType()

getLabels

public List<String> getLabels()

getParent

public Issue getParent()

getPriority

public Priority getPriority()

getProject

public Project getProject()

getReporter

public User getReporter()

getRemoteLinks

public List<RemoteLink> getRemoteLinks()
                                throws JiraException

Throws:

JiraException

getResolution

public Resolution getResolution()

getResolutionDate

public Date getResolutionDate()

getStatus

public Status getStatus()

getSubtasks

public List<Issue> getSubtasks()

getSummary

public String getSummary()

getTimeTracking

public TimeTracking getTimeTracking()

getVersions

public List<Version> getVersions()

getVotes

public Votes getVotes()

getWatches

public Watches getWatches()

getWorkLogs

public List<WorkLog> getWorkLogs()

getAllWorkLogs

public List<WorkLog> getAllWorkLogs()
                             throws JiraException

Throws:

JiraException

getTimeSpent

public Integer getTimeSpent()

getTimeEstimate

public Integer getTimeEstimate()

getCreatedDate

public Date getCreatedDate()

getUpdatedDate

public Date getUpdatedDate()

getSecurity

public Security getSecurity()

delete

public boolean delete(boolean deleteSubtasks)
               throws JiraException

Throws:

JiraException