com.twelvegm.hudson.plugin.reviewboard
Class ReviewboardHttpAPI

java.lang.Object
  com.twelvegm.hudson.plugin.reviewboard.ReviewboardHttpAPI

public class ReviewboardHttpAPI
extends Object

Creates an instance of the Reviewboard API. Calls are currently executed against the RESTful HTTP endpoints exposed by Reviewboard. Authentication is done by Basic Authentication with supplied username and password during instantiation. Assumptions are that you have a configured version of Reviewboard associated with a SCM. Currently, this has only been tested with Perforce. Currently supports a limited selection of HTTP endpoints pre-1.5 beta 2. TODO: Add better/more error handling and logging What this DOES currently do: 1) Update an existing review with changes uploaded to the SCM (post-commit). 2) Add a change description to a new diff (see #1). 3) Set default reviewers on a review request. 4) Set bugs on a review request. 5) Set default review groups on a review request. 6) Publish a review that is in draft. 7) Get reviewboard users matching a query. 8) Get reviewboard groups matching a query. 9) Supports Perforce SCM What this DOESN'T currently do: 1) Create a new review request. This API currently assumes a review request already exists, having been created through the web interface or post-review (for pre/post-commits). 2) Set the branch field of a review request (haven't had a need for it yet). 3) Get a complete review request. 4) Password encryption/decryption. It's currently clear-text. 5) Add a review to a review request. 6) Add a test description to a review request. 7) Add a screenshot to a review request. 8) Star a review request. 9) Close a review request. 10) Become sentient and destroy all humans. 11) Support CVS, SVN, Git, or any SCMs other than Perforce Known issues / To Dos: 1) The API URLs are known to be changing in the release of 1.5, so these will need to be updated accordingly. For backward compatibility, the constants for these APIs should probably have versions included in their name so the 1.5 version of the URLs don't conflict when added. 2) Some strings need to be made into constants, such as the JSON keys for retrieval of groups and users. String literals embedded in source code are bad, mmmm-kay?

Version:

1.0-beta

Author:

Ryan Shelley

Constructor Summary

ReviewboardHttpAPI(String username, String password, String baseUrl)
Creates a new ReviewboardHttpAPI object used to connect to Reviewboard and execute commands.

Method Summary

Set<String>	getGroups(String query) Retrieves a list of Reviewboard Groups that match the query argument.
Set<String>	getReviewers(String query) Retrieves a list of Reviewboard users who match the query argument.
boolean	publishReview(ReviewRequest review) Publishes a review request in draft.
boolean	setBugs(ReviewRequest review, String bugs) Sets the related bugs of a pending review request.
boolean	setChangeDescription(ReviewRequest review, String description) Sets the change description on a review that is being updated and in draft.
boolean	setGroups(ReviewRequest review, String groups) Sets one or more groups as default review groups on a review request.
boolean	setReviewers(ReviewRequest review, String reviewers) Sets one or more users as default reviewers on a review request.

Methods inherited from class java.lang.Object

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

Constructor Detail

ReviewboardHttpAPI

public ReviewboardHttpAPI(String username,
                          String password,
                          String baseUrl)
                   throws org.apache.commons.httpclient.URIException,
                          NullPointerException

Creates a new ReviewboardHttpAPI object used to connect to Reviewboard and execute commands. Tested with v1.5 beta 2. All parameters are required. User must have the following permissions in Reviewboard: Can add default reviewer Can change status Can edit review request Can submit as another user Can change review request Can change review request draft

Parameters:

username - Username of account that has access rights to Reviewboard

password - Password of Username

baseUrl - Base URL at which Reviewboard is running

Throws:

NullPointerException

org.apache.commons.httpclient.URIException

Method Detail

getGroups

public Set<String> getGroups(String query)

Retrieves a list of Reviewboard Groups that match the query argument. Group names are case-sensitive.

Parameters:

query - part of string to search Reviewboard to match group names against.

Returns:

Set of matching groups, or empty list if none were found. Group names are case-sensitive.

getReviewers

public Set<String> getReviewers(String query)

Retrieves a list of Reviewboard users who match the query argument. Usernames are case-sensitive.

Parameters:

query - part of usernames to match against Reviewboard users.

Returns:

Set of matching usernames or empty list if none were found. Usernames are case-sensitive.

setGroups

public boolean setGroups(ReviewRequest review,
                         String groups)

Sets one or more groups as default review groups on a review request. The groups argument should be a comma-delimited string of valid Reviewboard groups. Use getGroups(String) to validate input before passing to this method. The review request being modified should be in draft and not yet submit. This method will overwrite any existing groups on the review request.

Parameters:

review - Review to modify set the review groups on

groups - String of comma-separated groups to set

Returns:

true if successful, false otherwise

setReviewers

public boolean setReviewers(ReviewRequest review,
                            String reviewers)

Sets one or more users as default reviewers on a review request. The reviewers argument should be a comma-delimited string of valid Reviewboard users. Use getReviewers(String) to validate input before passing to this method. The review request being modified should be in draft and not yet submit. This method will overwrite any existing reviewers on the review request.

Parameters:

review - Review to set the reviewers on

reviewers - String of comma-separated Reviewboard users to set

Returns:

true if successful, false otherwise

setChangeDescription

public boolean setChangeDescription(ReviewRequest review,
                                    String description)

Sets the change description on a review that is being updated and in draft. This method is used to add a description to an updated diff of an existing review request.

Parameters:

review - Review to add the description to

description - Description to add to the pending diff

Returns:

true if successful, false otherwise

setBugs

public boolean setBugs(ReviewRequest review,
                       String bugs)

Sets the related bugs of a pending review request. This is usually the JIRA/Bugzilla/etc ID(s) associated with the review request and often the same as the External ID.

Parameters:

review - Review to add the bug(s) to

bugs - String of comma-separated bug IDs

Returns:

publishReview

public boolean publishReview(ReviewRequest review)

Publishes a review request in draft. If the review request is configured to notify reviewers and review groups, they will be sent emails.

Parameters:

review - Review to publish

Returns:

true if successful, false otherwise