org.redmine.ta
Class RedmineManager

java.lang.Object
  org.redmine.ta.RedmineManager

public class RedmineManager
extends Object

Entry point for the API: use this class to communicate with Redmine servers.

Author:

Alexey Skorokhodov

Nested Class Summary

static class

RedmineManager.INCLUDE

Constructor Summary

RedmineManager(String uri)

RedmineManager(String host, String apiAccessKey)
Creates an instance of RedmineManager class.

RedmineManager(String uri, String login, String password)
Deprecated. Use RedmineManager(String uri) constructor and then setLogin() , setPassword()

Method Summary

IssueCategory	createCategory(IssueCategory category) creates a new IssueCategory for the Project contained.
Issue	createIssue(String projectKey, Issue issue) Sample usage:
Project	createProject(Project project) Sample usage:
IssueRelation	createRelation(Integer issueId, Integer issueToId, String type)
IssueRelation	createRelation(String projectKey, Integer issueId, Integer issueToId, String type) Deprecated. use createRelation(Integer issueId, Integer issueToId, String type). "projectKey" parameter is not used anyway. this method will be deleted soon.
TimeEntry	createTimeEntry(TimeEntry obj)
User	createUser(User user)
Version	createVersion(Version version) creates a new Version for the Project contained.
void	deleteCategory(IssueCategory category) deletes an IssueCategory.
void	deleteIssue(Integer id)
void	deleteIssueRelations(Issue redmineIssue) Delete all issue's relations
void	deleteIssueRelationsByIssueId(Integer id) Delete relations for the given issue ID.
void	deleteProject(String projectKey)
void	deleteRelation(Integer id) Delete Issue Relation with the given ID.
void	deleteTimeEntry(Integer id)
void	deleteUser(Integer userId)
void	deleteVersion(Version version) deletes a new Version from the Project contained.
byte[]	downloadAttachmentContent(Attachment issueAttachment) Downloads the content of an Attachment from the Redmine server.
Attachment	getAttachmentById(int attachmentID) Delivers an Attachment by its ID.
List<IssueCategory>	getCategories(int projectID) delivers a list of IssueCategorys of a Project
User	getCurrentUser()
Issue	getIssueById(Integer id, RedmineManager.INCLUDE... include)
List<Issue>	getIssues(Map<String,String> pParameters) Generic method to search for issues.
List<Issue>	getIssues(String projectKey, Integer queryId, RedmineManager.INCLUDE... include)
List<Issue>	getIssuesBySummary(String projectKey, String summaryField) There could be several issues with the same summary, so the method returns List.
List<News>	getNews(String projectKey)
int	getObjectsPerPage() This number of objects (tasks, projects, users) will be requested from Redmine server in 1 request.
Project	getProjectByKey(String projectKey)
List<Project>	getProjects() Load the list of projects available to the user, which is represented by the API access key.
List<SavedQuery>	getSavedQueries() Get all "saved queries" available to the current user.
List<SavedQuery>	getSavedQueries(String projectKey) Get "saved queries" for the given project available to the current user.
List<IssueStatus>	getStatuses() Delivers a list of existing IssueStatuses.
List<TimeEntry>	getTimeEntries()
List<TimeEntry>	getTimeEntriesForIssue(Integer issueId)
TimeEntry	getTimeEntry(Integer id)
List<Tracker>	getTrackers()
User	getUserById(Integer userId)
List<User>	getUsers() Load the list of users on the server.
Version	getVersionById(int versionId)
List<Version>	getVersions(int projectID) delivers a list of Versions of a Project
void	setLogin(String login)
void	setObjectsPerPage(int pageSize) This number of objects (tasks, projects, users) will be requested from Redmine server in 1 request.
void	setPassword(String password)
void	update(Identifiable obj)
void	updateIssue(Issue issue) Deprecated. this method will be deleted in the future releases. use update() method instead Note: This method cannot return the updated Issue from Redmine because the server does not provide any XML in response.
void	updateProject(Project project) Deprecated. this method will be deleted in the future releases. use update() method instead
void	updateTimeEntry(TimeEntry obj) Deprecated. this method will be deleted in the future releases. use update() method instead
void	updateUser(User user) Deprecated. this method will be deleted in the future releases. use update() method instead This method cannot return the updated object from Redmine because the server does not provide any XML in response.

Methods inherited from class java.lang.Object

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

Constructor Detail

RedmineManager

public RedmineManager(String uri)

RedmineManager

public RedmineManager(String host,
                      String apiAccessKey)

Creates an instance of RedmineManager class. Host and apiAccessKey are not checked at this moment.

Parameters:

host - complete Redmine server web URI, including protocol and port number. Example: http://demo.redmine.org:8080

apiAccessKey - Redmine API access key. It is shown on "My Account" / "API access key" webpage (check http://redmine_server_url/my/account URL). This parameter is optional (can be set to NULL) for Redmine projects, which are "public".

RedmineManager

public RedmineManager(String uri,
                      String login,
                      String password)

Deprecated. Use RedmineManager(String uri) constructor and then setLogin() , setPassword()

Method Detail

createIssue

public Issue createIssue(String projectKey,
                         Issue issue)
                  throws IOException,
                         AuthenticationException,
                         NotFoundException,
                         RedmineException

Sample usage:

 Issue issueToCreate = new Issue();
   issueToCreate.setSubject("This is the summary line 123");
   Issue newIssue = mgr.createIssue(PROJECT_KEY, issueToCreate);
 


Parameters:
projectKey - The project "identifier". This is a string key like "project-ABC", NOT a database numeric ID.
issue - the Issue object to create on the server.
Returns:
the newly created Issue.
Throws:
IOException
AuthenticationException - invalid or no API access key is used with the server, which
                                 requires authorization. Check the constructor arguments.
NotFoundException - the project with the given projectKey is not found
RedmineException

updateIssue

public void updateIssue(Issue issue)
                 throws IOException,
                        AuthenticationException,
                        NotFoundException,
                        RedmineException

Deprecated. this method will be deleted in the future releases. use update() method instead Note: This method cannot return the updated Issue from Redmine because the server does not provide any XML in response.

Parameters:

issue - the Issue to update on the server. issue.getId() is used for identification.

Throws:

IOException

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

NotFoundException - the issue with the required ID is not found

RedmineException

getProjects

public List<Project> getProjects()
                          throws IOException,
                                 AuthenticationException,
                                 RedmineException

Load the list of projects available to the user, which is represented by the API access key.

Returns:

list of Project objects

Throws:

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

RedmineException

IOException

getIssuesBySummary

public List<Issue> getIssuesBySummary(String projectKey,
                                      String summaryField)
                               throws IOException,
                                      AuthenticationException,
                                      NotFoundException,
                                      RedmineException

There could be several issues with the same summary, so the method returns List.

Returns:

empty list if not issues with this summary field exist, never NULL

Throws:

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

NotFoundException

RedmineException

IOException

getIssues

public List<Issue> getIssues(Map<String,String> pParameters)
                      throws IOException,
                             AuthenticationException,
                             NotFoundException,
                             RedmineException

Generic method to search for issues.

Parameters:

pParameters - the http parameters key/value pairs to append to the rest api request

Returns:

empty list if not issues with this summary field exist, never NULL

Throws:

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

NotFoundException

RedmineException

IOException

getIssueById

public Issue getIssueById(Integer id,
                          RedmineManager.INCLUDE... include)
                   throws IOException,
                          AuthenticationException,
                          NotFoundException,
                          RedmineException

Parameters:

id - the Redmine issue ID

include - list of "includes". e.g. "relations", "journals", ...

Returns:

Issue object

Throws:

IOException

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

NotFoundException - the issue with the given id is not found on the server

RedmineException

getProjectByKey

public Project getProjectByKey(String projectKey)
                        throws IOException,
                               AuthenticationException,
                               NotFoundException,
                               RedmineException

Parameters:

projectKey - string key like "project-ABC", NOT a database numeric ID

Returns:

Redmine's project

Throws:

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

NotFoundException - the project with the given key is not found

RedmineException

IOException

deleteProject

public void deleteProject(String projectKey)
                   throws IOException,
                          AuthenticationException,
                          NotFoundException,
                          RedmineException

Parameters:

projectKey - string key like "project-ABC", NOT a database numeric ID

Throws:

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

NotFoundException - if the project with the given key is not found

RedmineException

IOException

deleteIssue

public void deleteIssue(Integer id)
                 throws IOException,
                        AuthenticationException,
                        NotFoundException,
                        RedmineException

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

getIssues

public List<Issue> getIssues(String projectKey,
                             Integer queryId,
                             RedmineManager.INCLUDE... include)
                      throws IOException,
                             AuthenticationException,
                             NotFoundException,
                             RedmineException

Parameters:

projectKey - ignored if NULL

queryId - id of the saved query in Redmine. the query must be accessible to the user represented by the API access key (if the Redmine project requires authorization). This parameter is optional, NULL can be provided to get all available issues.

Returns:

list of Issue objects

Throws:

IOException

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

RedmineException

NotFoundException

See Also:

Issue

update

public void update(Identifiable obj)
            throws IOException,
                   AuthenticationException,
                   NotFoundException,
                   RedmineException

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

createProject

public Project createProject(Project project)
                      throws IOException,
                             AuthenticationException,
                             RedmineException,
                             NotFoundException

Sample usage:

 Project project = new Project();
 	Long timeStamp = Calendar.getInstance().getTimeInMillis();
 	String key = "projkey" + timeStamp;
 	String name = "project number " + timeStamp;
 	String description = "some description for the project";
 	project.setIdentifier(key);
 	project.setName(name);
 	project.setDescription(description);

 	Project createdProject = mgr.createProject(project);
 
 

Parameters:

project - project to create on the server

Returns:

the newly created Project object.

Throws:

IOException

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

RedmineException

NotFoundException

updateProject

public void updateProject(Project project)
                   throws IOException,
                          AuthenticationException,
                          RedmineException,
                          NotFoundException

Deprecated. this method will be deleted in the future releases. use update() method instead

Throws:

IOException

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

RedmineException

NotFoundException

See Also:

update(org.redmine.ta.beans.Identifiable)

getObjectsPerPage

public int getObjectsPerPage()

This number of objects (tasks, projects, users) will be requested from Redmine server in 1 request.

setObjectsPerPage

public void setObjectsPerPage(int pageSize)

This number of objects (tasks, projects, users) will be requested from Redmine server in 1 request.

getUsers

public List<User> getUsers()
                    throws IOException,
                           AuthenticationException,
                           NotFoundException,
                           RedmineException

Load the list of users on the server.

This operation requires "Redmine Administrator" permission.

Returns:

list of User objects

Throws:

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

NotFoundException

RedmineException

IOException

getUserById

public User getUserById(Integer userId)
                 throws IOException,
                        AuthenticationException,
                        NotFoundException,
                        RedmineException

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

getCurrentUser

public User getCurrentUser()
                    throws IOException,
                           AuthenticationException,
                           RedmineException,
                           NotFoundException

Returns:

the current user logged into Redmine

Throws:

IOException

AuthenticationException

RedmineException

NotFoundException

createUser

public User createUser(User user)
                throws IOException,
                       AuthenticationException,
                       RedmineException,
                       NotFoundException

Throws:

IOException

AuthenticationException

RedmineException

NotFoundException

updateUser

public void updateUser(User user)
                throws IOException,
                       AuthenticationException,
                       RedmineException,
                       NotFoundException

Deprecated. this method will be deleted in the future releases. use update() method instead This method cannot return the updated object from Redmine because the server does not provide any XML in response.

Throws:

IOException

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

RedmineException

NotFoundException - some object is not found. e.g. the user with the given id

deleteUser

public void deleteUser(Integer userId)
                throws IOException,
                       AuthenticationException,
                       RedmineException,
                       NotFoundException

Parameters:

userId - user identifier (numeric ID)

Throws:

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

NotFoundException - if the user with the given id is not found

RedmineException

IOException

getTimeEntries

public List<TimeEntry> getTimeEntries()
                               throws IOException,
                                      AuthenticationException,
                                      NotFoundException,
                                      RedmineException

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

getTimeEntry

public TimeEntry getTimeEntry(Integer id)
                       throws IOException,
                              AuthenticationException,
                              NotFoundException,
                              RedmineException

Parameters:

id - the database Id of the TimeEntry record

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

getTimeEntriesForIssue

public List<TimeEntry> getTimeEntriesForIssue(Integer issueId)
                                       throws IOException,
                                              AuthenticationException,
                                              NotFoundException,
                                              RedmineException

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

createTimeEntry

public TimeEntry createTimeEntry(TimeEntry obj)
                          throws IOException,
                                 AuthenticationException,
                                 NotFoundException,
                                 RedmineException

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

updateTimeEntry

public void updateTimeEntry(TimeEntry obj)
                     throws IOException,
                            AuthenticationException,
                            NotFoundException,
                            RedmineException

Deprecated. this method will be deleted in the future releases. use update() method instead

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

deleteTimeEntry

public void deleteTimeEntry(Integer id)
                     throws IOException,
                            AuthenticationException,
                            NotFoundException,
                            RedmineException

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

getSavedQueries

public List<SavedQuery> getSavedQueries(String projectKey)
                                 throws IOException,
                                        AuthenticationException,
                                        NotFoundException,
                                        RedmineException

Get "saved queries" for the given project available to the current user.

This REST API feature was added in Redmine 1.3.0. See http://www.redmine.org/issues/5737

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

getSavedQueries

public List<SavedQuery> getSavedQueries()
                                 throws IOException,
                                        AuthenticationException,
                                        NotFoundException,
                                        RedmineException

Get all "saved queries" available to the current user.

This REST API feature was added in Redmine 1.3.0. See http://www.redmine.org/issues/5737

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

createRelation

public IssueRelation createRelation(Integer issueId,
                                    Integer issueToId,
                                    String type)
                             throws IOException,
                                    AuthenticationException,
                                    NotFoundException,
                                    RedmineException

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

deleteRelation

public void deleteRelation(Integer id)
                    throws IOException,
                           AuthenticationException,
                           NotFoundException,
                           RedmineException

Delete Issue Relation with the given ID.

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

deleteIssueRelations

public void deleteIssueRelations(Issue redmineIssue)
                          throws IOException,
                                 AuthenticationException,
                                 RedmineException,
                                 NotFoundException

Delete all issue's relations

Throws:

IOException

AuthenticationException

RedmineException

NotFoundException

deleteIssueRelationsByIssueId

public void deleteIssueRelationsByIssueId(Integer id)
                                   throws IOException,
                                          AuthenticationException,
                                          RedmineException,
                                          NotFoundException

Delete relations for the given issue ID.

Parameters:

id - issue ID

Throws:

IOException

AuthenticationException

RedmineException

NotFoundException

createRelation

public IssueRelation createRelation(String projectKey,
                                    Integer issueId,
                                    Integer issueToId,
                                    String type)
                             throws IOException,
                                    AuthenticationException,
                                    NotFoundException,
                                    RedmineException

Deprecated. use createRelation(Integer issueId, Integer issueToId, String type). "projectKey" parameter is not used anyway. this method will be deleted soon.

Throws:

IOException

AuthenticationException

NotFoundException

RedmineException

getStatuses

public List<IssueStatus> getStatuses()
                              throws IOException,
                                     AuthenticationException,
                                     RedmineException,
                                     NotFoundException

Delivers a list of existing IssueStatuses.

Returns:

a list of existing IssueStatuses.

Throws:

IOException - thrown in case something went wrong while performing I/O operations

AuthenticationException - thrown in case something went wrong while trying to login

RedmineException - thrown in case something went wrong in Redmine

NotFoundException - thrown in case an object can not be found

createVersion

public Version createVersion(Version version)
                      throws IOException,
                             AuthenticationException,
                             RedmineException,
                             IllegalArgumentException,
                             NotFoundException

creates a new Version for the Project contained.
Pre-condition: the attribute Project for the Version must not be null!

Parameters:

version - the Version. Must contain a Project.

Returns:

the new Version created by Redmine

Throws:

IllegalArgumentException - thrown in case the version does not contain a project.

IOException - thrown in case something went wrong while performing I/O operations

AuthenticationException - thrown in case something went wrong while trying to login

RedmineException - thrown in case something went wrong in Redmine

NotFoundException - thrown in case an object can not be found

deleteVersion

public void deleteVersion(Version version)
                   throws IOException,
                          AuthenticationException,
                          RedmineException,
                          NotFoundException

deletes a new Version from the Project contained.

Parameters:

version - the Version.

Throws:

IOException - thrown in case something went wrong while performing I/O operations

AuthenticationException - thrown in case something went wrong while trying to login

RedmineException - thrown in case something went wrong in Redmine

NotFoundException - thrown in case an object can not be found

getVersions

public List<Version> getVersions(int projectID)
                          throws IOException,
                                 AuthenticationException,
                                 RedmineException,
                                 NotFoundException

delivers a list of Versions of a Project

Parameters:

projectID - the ID of the Project

Returns:

the list of Versions of the Project

Throws:

IOException - thrown in case something went wrong while performing I/O operations

AuthenticationException - thrown in case something went wrong while trying to login

RedmineException - thrown in case something went wrong in Redmine

NotFoundException - thrown in case an object can not be found

getVersionById

public Version getVersionById(int versionId)
                       throws IOException,
                              AuthenticationException,
                              RedmineException,
                              NotFoundException

Throws:

IOException

AuthenticationException

RedmineException

NotFoundException

getCategories

public List<IssueCategory> getCategories(int projectID)
                                  throws IOException,
                                         AuthenticationException,
                                         RedmineException,
                                         NotFoundException

delivers a list of IssueCategorys of a Project

Parameters:

projectID - the ID of the Project

Returns:

the list of IssueCategorys of the Project

Throws:

IOException - thrown in case something went wrong while performing I/O operations

AuthenticationException - thrown in case something went wrong while trying to login

RedmineException - thrown in case something went wrong in Redmine

NotFoundException - thrown in case an object can not be found

createCategory

public IssueCategory createCategory(IssueCategory category)
                             throws IOException,
                                    AuthenticationException,
                                    RedmineException,
                                    IllegalArgumentException,
                                    NotFoundException

creates a new IssueCategory for the Project contained.
Pre-condition: the attribute Project for the IssueCategory must not be null!

Parameters:

category - the IssueCategory. Must contain a Project.

Returns:

the new IssueCategory created by Redmine

Throws:

IllegalArgumentException - thrown in case the category does not contain a project.

IOException - thrown in case something went wrong while performing I/O operations

AuthenticationException - thrown in case something went wrong while trying to login

RedmineException - thrown in case something went wrong in Redmine

NotFoundException - thrown in case an object can not be found

deleteCategory

public void deleteCategory(IssueCategory category)
                    throws IOException,
                           AuthenticationException,
                           RedmineException,
                           NotFoundException

deletes an IssueCategory.

Parameters:

category - the IssueCategory.

Throws:

IOException - thrown in case something went wrong while performing I/O operations

AuthenticationException - thrown in case something went wrong while trying to login

RedmineException - thrown in case something went wrong in Redmine

NotFoundException - thrown in case an object can not be found

getTrackers

public List<Tracker> getTrackers()
                          throws IOException,
                                 AuthenticationException,
                                 RedmineException,
                                 NotFoundException

Returns:

a list of all Trackers available

Throws:

IOException - thrown in case something went wrong while performing I/O operations

AuthenticationException - thrown in case something went wrong while trying to login

RedmineException - thrown in case something went wrong in Redmine

NotFoundException - thrown in case an object can not be found

getAttachmentById

public Attachment getAttachmentById(int attachmentID)
                             throws IOException,
                                    AuthenticationException,
                                    NotFoundException,
                                    RedmineException

Delivers an Attachment by its ID.

Parameters:

attachmentID - the ID

Returns:

the Attachment

Throws:

IOException - thrown in case something went wrong while performing I/O operations

AuthenticationException - thrown in case something went wrong while trying to login

RedmineException - thrown in case something went wrong in Redmine

NotFoundException - thrown in case an object can not be found

downloadAttachmentContent

public byte[] downloadAttachmentContent(Attachment issueAttachment)
                                 throws IOException

Downloads the content of an Attachment from the Redmine server.

Parameters:

issueAttachment - the Attachment

Returns:

the content of the attachment as a byte[] array

Throws:

IOException - thrown in case the download fails

setLogin

public void setLogin(String login)

setPassword

public void setPassword(String password)

getNews

public List<News> getNews(String projectKey)
                   throws IOException,
                          AuthenticationException,
                          NotFoundException,
                          RedmineException

Parameters:

projectKey - ignored if NULL

Returns:

list of news objects

Throws:

IOException

AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.

RedmineException

NotFoundException

See Also:

News