net.rcarz.jiraclient

Class JiraClient

java.lang.Object

net.rcarz.jiraclient.JiraClient

public class JiraClient
extends Object

A simple JIRA REST client.

Constructor Summary

Constructors

Constructor and Description
JiraClient(org.apache.http.client.HttpClient httpClient, String uri, ICredentials creds) Creates an authenticated JIRA client with custom HttpClient.
JiraClient(String uri) Creates a JIRA client.
JiraClient(String uri, ICredentials creds) Creates an authenticated JIRA client.

Method Summary

Modifier and Type	Method and Description
int	countIssues(String jql) count issues with the given query.
Component.FluentCreate	createComponent(String project) Creates a new component in the given project.
Issue.FluentCreate	createIssue(String project, String issueType) Creates a new issue in the given project.
ArrayList<IssueHistory>	filterChangeLog(List<IssueHistory> histoy, String fields)
Component	getComponent(String id) Obtains a component given its ID.
List<Component>	getComponentsAllowedValues(String project, String issueType) Get a list of options for a components
List<CustomFieldOption>	getCustomFieldAllowedValues(String field, String project, String issueType) Get a list of options for a custom field
Filter	getFilter(String id) Retrieve the jira filter with the supplied id.
Issue	getIssue(String key) Retreives the issue with the given key.
Issue	getIssue(String key, String includedFields) Retreives the issue with the given key.
Issue	getIssue(String key, String includedFields, String expand) Retreives the issue with the given key.
ArrayList<IssueHistory>	getIssueChangeLog(Issue issue)
List<IssueType>	getIssueTypes() Obtains the list of all issue types in Jira.
List<Priority>	getPriorities()
Project	getProject(String key) Obtains information about a project, given its project key.
List<Project>	getProjects() Obtains the list of all projects in Jira.
RestClient	getRestClient()
String	getSelf()
Issue.SearchResult	searchIssues(String jql) Search for issues with the given query.
Issue.SearchResult	searchIssues(String jql, Integer maxResults) Search for issues with the given query and max results.
Issue.SearchResult	searchIssues(String jql, String includedFields) Search for issues with the given query and specify which fields to retrieve.
Issue.SearchResult	searchIssues(String jql, String includedFields, Integer maxResults) Search for issues with the given query and specify which fields to retrieve.
Issue.SearchResult	searchIssues(String jql, String includedFields, Integer maxResults, Integer startAt) Search for issues with the given query and specify which fields to retrieve.
Issue.SearchResult	searchIssues(String jql, String includedFields, String expandFields) Search for issues with the given query and specify which fields to retrieve and expand.
Issue.SearchResult	searchIssues(String jql, String includedFields, String expandFields, Integer maxResults, Integer startAt) Search for issues with the given query and specify which fields to retrieve.

Methods inherited from class java.lang.Object

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

Constructor Detail

JiraClient

public JiraClient(String uri)
           throws JiraException

Creates a JIRA client.

Parameters:

uri - Base URI of the JIRA server

Throws:

JiraException

JiraClient

public JiraClient(String uri,
                  ICredentials creds)
           throws JiraException

Creates an authenticated JIRA client.

Parameters:

uri - Base URI of the JIRA server

creds - Credentials to authenticate with

Throws:

JiraException

JiraClient

public JiraClient(org.apache.http.client.HttpClient httpClient,
                  String uri,
                  ICredentials creds)
           throws JiraException

Creates an authenticated JIRA client with custom HttpClient.

Parameters:

httpClient - Custom HttpClient to be used

uri - Base URI of the JIRA server

creds - Credentials to authenticate with

Throws:

JiraException

Method Detail

createIssue

public Issue.FluentCreate createIssue(String project,
                                      String issueType)
                               throws JiraException

Creates a new issue in the given project.

Parameters:

project - Key of the project to create in

issueType - Name of the issue type to create

Returns:

a fluent create instance

Throws:

JiraException - when something goes wrong

getIssue

public Issue getIssue(String key)
               throws JiraException

Retreives the issue with the given key.

Parameters:

key - Issue key (PROJECT-123)

Returns:

an issue instance (issue includes all fields)

Throws:

JiraException - when something goes wrong

getIssue

public Issue getIssue(String key,
                      String includedFields)
               throws JiraException

Retreives the issue with the given key.

Parameters:

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 something goes wrong

getIssue

public Issue getIssue(String key,
                      String includedFields,
                      String expand)
               throws JiraException

Retreives the issue with the given key.

Parameters:

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 - issue fields to expand when getting issue data

Returns:

an issue instance

Throws:

JiraException - when something goes wrong

countIssues

public int countIssues(String jql)
                throws JiraException

count issues with the given query.

Parameters:

jql - JQL statement

Returns:

the count

Throws:

JiraException - when the search fails

searchIssues

public Issue.SearchResult searchIssues(String jql)
                                throws JiraException

Search for issues with the given query.

Parameters:

jql - JQL statement

Returns:

a search result structure with results (issues include all navigable fields)

Throws:

JiraException - when the search fails

searchIssues

public Issue.SearchResult searchIssues(String jql,
                                       Integer maxResults)
                                throws JiraException

Search for issues with the given query and max results.

Parameters:

jql - JQL statement

maxResults - limit the number of results

Returns:

a search result structure with results (issues include all navigable fields)

Throws:

JiraException - when the search fails

searchIssues

public Issue.SearchResult searchIssues(String jql,
                                       String includedFields)
                                throws JiraException

Search for issues with the given query and specify which fields to retrieve.

Parameters:

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

Returns:

a search result structure with results

Throws:

JiraException - when the search fails

searchIssues

public Issue.SearchResult searchIssues(String jql,
                                       String includedFields,
                                       String expandFields)
                                throws JiraException

Search for issues with the given query and specify which fields to retrieve and expand.

Parameters:

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

expandFields - Specifies with issue fields should be expanded

Returns:

a search result structure with results

Throws:

JiraException - when the search fails

searchIssues

public Issue.SearchResult searchIssues(String jql,
                                       String includedFields,
                                       Integer maxResults)
                                throws JiraException

Search for issues with the given query and specify which fields to retrieve.

Parameters:

jql - JQL statement

maxResults - limit the number of results

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:

a search result structure with results

Throws:

JiraException - when the search fails

searchIssues

public Issue.SearchResult searchIssues(String jql,
                                       String includedFields,
                                       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:

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

Returns:

a search result structure with results

Throws:

JiraException - when the search fails

searchIssues

public Issue.SearchResult searchIssues(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:

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

expandFields - Specifies with issue fields should be expanded

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

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

Returns:

a search result structure with results

Throws:

JiraException - when the search fails

getFilter

public Filter getFilter(String id)
                 throws JiraException

Retrieve the jira filter with the supplied id.

Parameters:

id - id of the filter to retreive.

Returns:

The Jira filter with the supplied id

Throws:

JiraException

getPriorities

public List<Priority> getPriorities()
                             throws JiraException

Returns:

a list of all priorities available in the Jira installation

Throws:

JiraException

getCustomFieldAllowedValues

public List<CustomFieldOption> getCustomFieldAllowedValues(String field,
                                                           String project,
                                                           String issueType)
                                                    throws JiraException

Get a list of options for a custom field

Parameters:

field - field id

project - Key of the project context

issueType - Name of the issue type

Returns:

a search result structure with results

Throws:

JiraException - when the search fails

getComponentsAllowedValues

public List<Component> getComponentsAllowedValues(String project,
                                                  String issueType)
                                           throws JiraException

Get a list of options for a components

Parameters:

project - Key of the project context

issueType - Name of the issue type

Returns:

a search result structure with results

Throws:

JiraException - when the search fails

getRestClient

public RestClient getRestClient()

getSelf

public String getSelf()

getProjects

public List<Project> getProjects()
                          throws JiraException

Obtains the list of all projects in Jira.

Returns:

all projects; not all data is returned for each project; to get the extra data use getProject(String)

Throws:

JiraException - failed to obtain the project list.

getProject

public Project getProject(String key)
                   throws JiraException

Obtains information about a project, given its project key.

Parameters:

key - the project key

Returns:

the project

Throws:

JiraException - failed to obtain the project

getIssueTypes

public List<IssueType> getIssueTypes()
                              throws JiraException

Obtains the list of all issue types in Jira.

Returns:

all issue types

Throws:

JiraException - failed to obtain the issue type list.

createComponent

public Component.FluentCreate createComponent(String project)

Creates a new component in the given project.

Parameters:

project - Key of the project to create in

Returns:

a fluent create instance

getComponent

public Component getComponent(String id)
                       throws JiraException

Obtains a component given its ID.

Parameters:

id - the component ID

Returns:

the component

Throws:

JiraException - failed to obtain the component

filterChangeLog

public ArrayList<IssueHistory> filterChangeLog(List<IssueHistory> histoy,
                                               String fields)

getIssueChangeLog

public ArrayList<IssueHistory> getIssueChangeLog(Issue issue)
                                          throws JiraException

Throws:

JiraException