Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.redmine.ta
Class RedmineManager

java.lang.Object
  extended by 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)
           
 
Method Summary
 Issue createIssue(String projectKey, Issue issue)
          Sample usage:
 Project createProject(Project project)
          Sample usage:
 IssueRelation createRelation(String projectKey, Integer issueId, Integer issueToId, String type)
           
 TimeEntry createTimeEntry(TimeEntry obj)
           
 User createUser(User user)
           
 void deleteIssue(Integer id)
           
 void deleteProject(String projectKey)
           
 void deleteTimeEntry(Integer id)
           
 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.
 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<TimeEntry> getTimeEntries()
           
 List<TimeEntry> getTimeEntriesForIssue(Integer issueId)
           
 TimeEntry getTimeEntry(Integer id)
           
 User getUserById(Integer userId)
           
 List<User> getUsers()
          Load the list of users on the server.
 void setObjectsPerPage(int pageSize)
          This number of objects (tasks, projects, users) will be requested from Redmine server in 1 request.
 void updateIssue(Issue issue)
          Note: This method cannot return the updated Issue from Redmine because the server does not provide any XML in response.
 void updateProject(Project project)
           
 void updateTimeEntry(TimeEntry obj)
           
 void updateUser(User user)
          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)
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
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
NotFoundException
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.

Parameters:
summaryField -
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 -
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

createProject

public Project createProject(Project project)
                      throws IOException,
                             AuthenticationException,
                             RedmineException
Sample usage: 

 Project project = new Project();
 	Long timeStamp = Calendar.getInstance().getTimeInMillis();
 	String key = "projkey" + timeStamp;
 	String name = &quot;project number &quot; + timeStamp;
 	String description = &quot;some description for the project&quot;;
 	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

updateProject

public void updateProject(Project project)
                   throws IOException,
                          AuthenticationException,
                          RedmineException,
                          NotFoundException
Parameters:
project -
Throws:
IOException
AuthenticationException - invalid or no API access key is used with the server, which requires authorization. Check the constructor arguments.
RedmineException
NotFoundException

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
Throws:
IOException
AuthenticationException
RedmineException

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
This method cannot return the updated object from Redmine because the server does not provide any XML in response.

Parameters:
user -
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

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
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(String projectKey,
                                    Integer issueId,
                                    Integer issueToId,
                                    String type)
                             throws IOException,
                                    AuthenticationException,
                                    NotFoundException,
                                    RedmineException
Throws:
IOException
AuthenticationException
NotFoundException
RedmineException
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2011. All Rights Reserved.