com.taskadapter.redmineapi
Class RedmineManager

java.lang.Object
  com.taskadapter.redmineapi.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 uri, RedmineOptions options)

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

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

RedmineManager(String uri, String login, String password)

RedmineManager(String uri, String login, String password, RedmineOptions options)

Method Summary

void	addMembership(Membership membership) Add a membership.
void	addUserToGroup(User user, Group group) Adds the given user to the given group.
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)
TimeEntry	createTimeEntry(TimeEntry obj)
User	createUser(User user)
Version	createVersion(Version version) creates a new Version for the Project contained.
void	delete(Membership membership)
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	deleteMembership(int 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.
void	downloadAttachmentContent(Attachment issueAttachment, OutputStream stream)
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()
List<Group>	getGroups() Load the list of groups on the server.
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.
Membership	getMembership(int id)
List<Membership>	getMemberships(Project project)
List<Membership>	getMemberships(String project)
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<Role>	getRoles()
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) This does NOT require Admin privileges by default Redmine installation (tested with Redmine 2.0.3).
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	shutdown() Shutdowns a communicator.
void	update(Identifiable obj)
Attachment	uploadAttachment(String contentType, File content) Uploads an attachment.
Attachment	uploadAttachment(String fileName, String contentType, byte[] content) Uploads an attachment.
Attachment	uploadAttachment(String fileName, String contentType, InputStream content) Uploads an attachment.

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 uri,
                      String login,
                      String password)

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 host,
                      String apiAccessKey,
                      RedmineOptions options)

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,
                      RedmineOptions options)

RedmineManager

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

Method Detail

createIssue

public Issue createIssue(String projectKey,
                         Issue issue)
                  throws 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:
RedmineAuthenticationException - 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

getProjects

public List<Project> getProjects()
                          throws RedmineException

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

Returns:

list of Project objects

Throws:

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

RedmineException

getIssuesBySummary

public List<Issue> getIssuesBySummary(String projectKey,
                                      String summaryField)
                               throws 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:

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

NotFoundException

RedmineException

getIssues

public List<Issue> getIssues(Map<String,String> pParameters)
                      throws 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:

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

NotFoundException

RedmineException

getIssueById

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

Parameters:

id - the Redmine issue ID

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

Returns:

Issue object

Throws:

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

Parameters:

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

Returns:

Redmine's project

Throws:

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

deleteProject

public void deleteProject(String projectKey)
                   throws RedmineException

Parameters:

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

Throws:

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

deleteIssue

public void deleteIssue(Integer id)
                 throws RedmineException

Throws:

RedmineException

getIssues

public List<Issue> getIssues(String projectKey,
                             Integer queryId,
                             RedmineManager.INCLUDE... include)
                      throws 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:

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

RedmineException

See Also:

Issue

update

public void update(Identifiable obj)
            throws RedmineException

Throws:

RedmineException

createProject

public Project createProject(Project project)
                      throws RedmineException

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:

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

RedmineException

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 RedmineException

Load the list of users on the server.

This operation requires "Redmine Administrator" permission.

Returns:

list of User objects

Throws:

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

NotFoundException

RedmineException

getUserById

public User getUserById(Integer userId)
                 throws RedmineException

This does NOT require Admin privileges by default Redmine installation (tested with Redmine 2.0.3).

Throws:

RedmineException

getCurrentUser

public User getCurrentUser()
                    throws RedmineException

Returns:

the current user logged into Redmine

Throws:

RedmineException

createUser

public User createUser(User user)
                throws RedmineException

Throws:

RedmineException

deleteUser

public void deleteUser(Integer userId)
                throws RedmineException

Parameters:

userId - user identifier (numeric ID)

Throws:

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

getGroups

public List<Group> getGroups()
                      throws RedmineException

Load the list of groups on the server.

This operation requires "Redmine Administrator" permission.

Returns:

list of User objects

Throws:

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

NotFoundException

RedmineException

getTimeEntries

public List<TimeEntry> getTimeEntries()
                               throws RedmineException

Throws:

RedmineException

getTimeEntry

public TimeEntry getTimeEntry(Integer id)
                       throws RedmineException

Parameters:

id - the database Id of the TimeEntry record

Throws:

RedmineException

getTimeEntriesForIssue

public List<TimeEntry> getTimeEntriesForIssue(Integer issueId)
                                       throws RedmineException

Throws:

RedmineException

createTimeEntry

public TimeEntry createTimeEntry(TimeEntry obj)
                          throws RedmineException

Throws:

RedmineException

deleteTimeEntry

public void deleteTimeEntry(Integer id)
                     throws RedmineException

Throws:

RedmineException

getSavedQueries

public List<SavedQuery> getSavedQueries(String projectKey)
                                 throws 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:

RedmineException

getSavedQueries

public List<SavedQuery> getSavedQueries()
                                 throws 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:

RedmineException

createRelation

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

Throws:

RedmineException

deleteRelation

public void deleteRelation(Integer id)
                    throws RedmineException

Delete Issue Relation with the given ID.

Throws:

RedmineException

deleteIssueRelations

public void deleteIssueRelations(Issue redmineIssue)
                          throws RedmineException

Delete all issue's relations

Throws:

RedmineException

deleteIssueRelationsByIssueId

public void deleteIssueRelationsByIssueId(Integer id)
                                   throws RedmineException

Delete relations for the given issue ID.

Parameters:

id - issue ID

Throws:

RedmineException

getStatuses

public List<IssueStatus> getStatuses()
                              throws RedmineException

Delivers a list of existing IssueStatuses.

Returns:

a list of existing IssueStatuses.

Throws:

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

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.

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

deletes a new Version from the Project contained.

Parameters:

version - the Version.

Throws:

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

delivers a list of Versions of a Project

Parameters:

projectID - the ID of the Project

Returns:

the list of Versions of the Project

Throws:

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

Throws:

RedmineException

getCategories

public List<IssueCategory> getCategories(int projectID)
                                  throws RedmineException

delivers a list of IssueCategorys of a Project

Parameters:

projectID - the ID of the Project

Returns:

the list of IssueCategorys of the Project

Throws:

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

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.

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

deletes an IssueCategory.

Parameters:

category - the IssueCategory.

Throws:

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

Returns:

a list of all Trackers available

Throws:

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

Delivers an Attachment by its ID.

Parameters:

attachmentID - the ID

Returns:

the Attachment

Throws:

RedmineAuthenticationException - 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 void downloadAttachmentContent(Attachment issueAttachment,
                                      OutputStream stream)
                               throws RedmineException

Throws:

RedmineException

downloadAttachmentContent

public byte[] downloadAttachmentContent(Attachment issueAttachment)
                                 throws RedmineException

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:

RedmineCommunicationException - thrown in case the download fails

RedmineException

setLogin

public void setLogin(String login)

setPassword

public void setPassword(String password)

getNews

public List<News> getNews(String projectKey)
                   throws RedmineException

Parameters:

projectKey - ignored if NULL

Returns:

list of news objects

Throws:

RedmineException

See Also:

News

shutdown

public void shutdown()

Shutdowns a communicator.

uploadAttachment

public Attachment uploadAttachment(String fileName,
                                   String contentType,
                                   InputStream content)
                            throws RedmineException,
                                   IOException

Uploads an attachment.

Parameters:

fileName - file name of the attachment.

contentType - content type of the attachment.

content - attachment content stream.

Returns:

attachment content.

Throws:

RedmineException - if something goes wrong.

IOException - if input cannot be read. This exception cannot be thrown yet (I am not sure if http client can distinguish "network" errors and local errors) but is will be good to distinguish reading errors and transport errors.

uploadAttachment

public Attachment uploadAttachment(String fileName,
                                   String contentType,
                                   byte[] content)
                            throws RedmineException,
                                   IOException

Uploads an attachment.

Parameters:

fileName - file name of the attachment.

contentType - content type of the attachment.

content - attachment content stream.

Returns:

attachment content.

Throws:

RedmineException - if something goes wrong.

IOException - if input cannot be read.

uploadAttachment

public Attachment uploadAttachment(String contentType,
                                   File content)
                            throws RedmineException,
                                   IOException

Uploads an attachment.

Parameters:

contentType - content type of the attachment.

content - attachment content stream.

Returns:

attachment content.

Throws:

RedmineException - if something goes wrong.

IOException - if input cannot be read.

getRoles

public List<Role> getRoles()
                    throws RedmineException

Throws:

RedmineException

getMemberships

public List<Membership> getMemberships(String project)
                                throws RedmineException

Throws:

RedmineException

getMemberships

public List<Membership> getMemberships(Project project)
                                throws RedmineException

Throws:

RedmineException

addMembership

public void addMembership(Membership membership)
                   throws RedmineException

Add a membership.

Parameters:

membership - membership.

Throws:

RedmineException

getMembership

public Membership getMembership(int id)
                         throws RedmineException

Throws:

RedmineException

deleteMembership

public void deleteMembership(int id)
                      throws RedmineException

Throws:

RedmineException

delete

public void delete(Membership membership)
            throws RedmineException

Throws:

RedmineException

addUserToGroup

public void addUserToGroup(User user,
                           Group group)
                    throws RedmineException

Adds the given user to the given group.

Parameters:

user - - The user being added.

group - - The new group of the user.

Throws:

RedmineException