com.atlassian.crucible.spi.services
Interface ReviewService

public interface ReviewService

Provides an API for working with reviews.

Each method performs its operations within a transaction.

Nested Class Summary

static class

ReviewService.Action The actions which can be performed on a review, changing its state.

Method Summary

ReviewData	addChangesetsToReview(PermId<ReviewData> id, java.lang.String repository, java.util.List<ChangesetData> changesets) Add a changeset to existing review -- the review will contain all the revisions in the changesets.
VersionedLineCommentData	addComment(PermId<ReviewItemData> id, VersionedLineCommentData comment) Add a comment to a review item.
FisheyeReviewItemData	addFileToReview(PermId<ReviewData> id, FileData file, FileData diff) Adds a file to the review, optionally diff'ed to a second file.
ReviewItemData	addFisheyeDiff(PermId<ReviewData> id, java.lang.String repositoryName, java.lang.String fromPath, java.lang.String fromRevision, java.lang.String toPath, java.lang.String toRevision) Add the changes between two files in a fisheye repository to the review.
GeneralCommentData	addGeneralComment(PermId<ReviewData> id, GeneralCommentData comment) Add a general comment to a review.
ReviewData	addPatchToReview(PermId<ReviewData> id, java.lang.String patch) Add a patch to existing review -- the review will contain provied patch
ReviewData	addPatchToReview(PermId<ReviewData> id, java.lang.String patch, AnchorData anchorData) Add a patch to existing review.
GeneralCommentData	addReply(PermId<CommentData> commentId, GeneralCommentData comment) Add a reply to comment in a review.
void	addReviewers(PermId<ReviewData> id, java.lang.String[] userNames) Add reviewers to a review
FisheyeReviewItemData	addReviewItem(PermId<ReviewData> reviewId, FisheyeReviewItemData reviewItem) Adds the given review item to the review.
ReviewItemData	addReviewItemRevisions(PermId<ReviewData> reviewId, PermId<ReviewItemData> itemId, java.util.List<java.lang.String> revisions) Adds the given list of revisions to the supplied review item, merging if required.
DetailedReviewData	addReviewRevisions(PermId<ReviewData> reviewId, java.util.List<CrucibleRevisionData> reviewItems) Adds a review item for each of the CrucibleRevisionData given.
ReviewData	changeState(PermId<ReviewData> id, ReviewService.Action action) Change the state of a review by performing an action on it.
ReviewData	changeState(PermId<ReviewData> id, java.lang.String action) Change the state of a review by performing an action on it.
ReviewData	closeReviewWithSummary(PermId<ReviewData> id, java.lang.String message) Complete/uncomplte review by reviewer
void	completeReview(PermId<ReviewData> reviewDataPermId, boolean complete) Complete/uncomplete review by reviewer
DetailedReviewData	createDetailedReview(DetailedReviewData review) Create a new review from the attributes in a DetailedReviewData instance (similar to createReview(com.atlassian.crucible.spi.data.ReviewData), but also copies the list of Reviewers into the new review.
ReviewData	createReview(ReviewData review) Create a new review from the attributes in a ReviewData instance.
ReviewData	createReviewFromChangeSets(ReviewData review, java.lang.String repository, java.util.List<ChangesetData> changesets) Create a new review from a changesets -- the review will contain all the revisions in the changesets
ReviewData	createReviewFromPatch(ReviewData review, java.lang.String patch) Create a new review from a patch.
ReviewData	createReviewFromPatch(ReviewData review, java.lang.String patch, AnchorData anchorData) Create a new review from a patch, and anchor it to the repository given by AnchorData.getAnchorRepository().
ReviewData	createSnippetReview(ReviewData review, java.lang.String snippet, java.lang.String filename) Create a new snippet review from text
void	deleteReview(PermId<ReviewData> id) Permanently delete a review.
java.util.List<ActionData>	getAllowedActionsForReview(PermId<ReviewData> id) Get a list of the actions which the current user is allowed to perform on the review.
java.util.List<ActionData>	getAllowedTransitionsForReview(PermId<ReviewData> id) Get a list of the actions which the current user can perform on this review, given its current state and the user's permissions.
java.util.Set<ReviewerData>	getAllReviewers(PermId<ReviewData> id) Get the reviewer data of all the reviewers on a review.
java.util.List<ReviewData>	getAllReviews(boolean details) Get a ReviewData instance for each review.
java.util.List<ReviewData>	getAllReviewsForItem(java.lang.String path, java.lang.String repositoryName, boolean details) Finds all reviews that contain at least one revision of the specified file.
java.util.List<VersionedLineCommentData>	getAllRevisionComments(PermId<ReviewData> id) Get a list of the comments on all the review items in a review, i.e., excluding general comments, that are visible to the effective user for a particular review.
java.util.List<VersionedLineCommentData>	getAllRevisionComments(PermId<ReviewData> id, boolean withHtmlMessage) Same as calling getAllRevisionComments(com.atlassian.crucible.spi.PermId).
java.util.List<ReviewData>	getChildReviews(PermId<ReviewData> id) Get the child reviews belonging to a review
java.util.List<ReviewData>	getChildReviews(PermId<ReviewData> id, boolean details) Get the child reviews belonging to a review
CommentData	getComment(PermId<CommentData> id) Get the details of a comment by its id.
CommentData	getComment(PermId<CommentData> id, boolean withHtmlMessage) Get the details of a comment by its id.
java.util.Set<ReviewerData>	getCompletedReviewers(PermId<ReviewData> reviewDataPermId) Get the reviewer data of the reviewers that already completed a review.
java.util.List<ReviewData>	getCustomFilterReviews(CustomFilterData filter, boolean details) Get a list of all the reviews for which the user involved based on predefined criteria.
java.util.List<ReviewData>	getFilteredReviews(java.lang.String filter, boolean details) Get a list of all the reviews for which the user involved based on predefined criteria.
java.util.List<GeneralCommentData>	getGeneralComments(PermId<ReviewData> id) Get a list of the general comments visible to the effective user for a particular review.
java.util.List<GeneralCommentData>	getGeneralComments(PermId<ReviewData> id, boolean withHtmlMessage) Same as getGeneralComments(com.atlassian.crucible.spi.PermId),except if the parameter withHtmlMessage is set to true, CommentDataImpl.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup).
java.util.List<CustomFieldDefData>	getMetrics(int metricsVersion) Get metrics metadata for specified metrics version
java.util.List<GeneralCommentData>	getReplies(PermId<CommentData> commentId) Get a list of the comment replies that are visible to the effective user.
java.util.List<GeneralCommentData>	getReplies(PermId<CommentData> commentId, boolean withHtmlMessage) Same as calling getReplies(com.atlassian.crucible.spi.PermId).
ReviewData	getReview(PermId<ReviewData> id) Gets a single review from its permId.
ReviewData	getReview(PermId<ReviewData> id, boolean details) Deprecated. use the versions without the 'details' parameter
DetailedReviewData	getReviewDetails(PermId<ReviewData> id) Get a single review from its permId.
FisheyeReviewItemData	getReviewItem(PermId<ReviewData> reviewDataPermId, PermId<ReviewItemData> reviewItemDataPermId) Returns detailed information for a specific review item.
java.util.List<ReviewItemData>	getReviewItemsForReview(PermId<ReviewData> id) Get a list of all the items in a review.
java.util.List<ReviewData>	getReviewsInStates(ReviewData.State[] states, boolean details) Retrieves all reviews that are in one of the the specified states.
java.util.Set<ReviewerData>	getUncompletedReviewers(PermId<ReviewData> reviewDataPermId) Get the reviewer data of the reviewers that didn't complete the review.
java.util.List<ReviewData>	getUncompletedReviewsForUser(java.lang.String userName) Get a list of all the reviews for which the user is a reviwer who has not completed the review.
java.util.List<VersionedLineCommentData>	getVersionedComments(PermId<ReviewItemData> id) Get a list of the comments visible to the effective user for a particular review item.
java.util.List<VersionedLineCommentData>	getVersionedComments(PermId<ReviewItemData> id, boolean withHtmlMessage) Same as getVersionedComments(com.atlassian.crucible.spi.PermId), except if the parameter withHtmlMessage is set to true, CommentDataImpl.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup).
VersionInfo	getVersionInfo() Deprecated. Moved to ServerInfoService
boolean	hasPermission(PermId<ReviewData> id, java.lang.String actionName) Does the current user have permission to perform the given action on the given review?
DetailedReviewData	markAllCommentsAsRead(PermId<ReviewData> reviewId) For the effective user, mark all comments in a review as read (except those marked as leave unread).
CommentData	markCommentAsLeaveUnread(PermId<CommentData> commentId) Mark a comment as leave unread for the effective user (even if already marked as leave unread).
CommentData	markCommentAsRead(PermId<CommentData> commentId) Mark a comment as read by the effective user (even if already read).
void	postComment(PermId<CommentData> commentId) Post a comment in draft state (any kind of comment, also reply).
void	postComments(PermId<ReviewData> id) Post all draft comments, including replies, authored by the effective user.
void	removeComment(PermId<CommentData> commentId) Remove a comment, and all of its descendent draft replies, from a review.
void	removeReviewer(PermId<ReviewData> id, java.lang.String userName) Remove reviewers from a review
void	removeReviewItem(PermId<ReviewData> reviewId, PermId<ReviewItemData> itemId) Remove an item from a review.
void	removeReviewItemRevisions(PermId<ReviewData> reviewId, PermId<ReviewItemData> itemId, java.util.List<java.lang.String> revisions) Removes the revisions given from the review item in the review specified by the id.
FisheyeReviewItemData	setReviewItem(PermId<ReviewData> reviewId, PermId<ReviewItemData> itemId, FisheyeReviewItemData reviewItem) sets the review item specified by itemId with the given reviewItem.
void	updateComment(PermId<CommentData> commentId, GeneralCommentData comment) Update the details of a comment.

Method Detail

createReview

ReviewData createReview(ReviewData review)

Create a new review from the attributes in a ReviewData instance.

Parameters:

review - a ReviewData containing the attributes of the review.

Returns:

a ReviewData with the permId attribute set to the id of the review which was just created.

createDetailedReview

DetailedReviewData createDetailedReview(DetailedReviewData review)

Create a new review from the attributes in a DetailedReviewData instance (similar to createReview(com.atlassian.crucible.spi.data.ReviewData), but also copies the list of Reviewers into the new review.

Parameters:

review - a DetailedReviewData containing the attributes of the review.

Returns:

a DetailedReviewData instance with the permId attribute set to the id of the review which was just created.

createReviewFromPatch

ReviewData createReviewFromPatch(ReviewData review,
                                 java.lang.String patch)

Create a new review from a patch. Does not perform anchoring.

Parameters:

review - a ReviewData containing the attributes of the review.

patch - a String containing the patch as a stream of UTF8 characters.

Returns:

a ReviewData with the permId attribute set to the id of the review which was just created.

createReviewFromPatch

ReviewData createReviewFromPatch(ReviewData review,
                                 java.lang.String patch,
                                 AnchorData anchorData)
                                 throws PatchAnchorFailedException

Create a new review from a patch, and anchor it to the repository given by AnchorData.getAnchorRepository().

Parameters:

review - the review data containing the review attributes

patch - a UTF-8 string of the patch

anchorData - a pojo with the anchor info. You can anchor to a particular repository by setting the anchorRepository property to the repository or by calling the constructor AnchorData.AnchorData(String).

To anchor to a particular path (e.g., branches/branch1, instead of trunk), set the anchorPath property to the desired path. Make sure this path exists for the repository given by the anchorRepository property, otherwise, a PatchAnchorFailedException will be thrown. If the patch given has a different path (e.g., it was not produced by svn diff), then you may be required to also set the stripCount property. This property indicates how many path elements (or directories) to strip away from the path, starting from the root directory, before appending to the anchorPath to produce the final path to which anchoring occurs.

For example, given that we wish to anchor the patch to "branches/branch1" in the repository "repo", and the patch contains a file "/root/trunk/dir1/a.txt", , we would set the anchPath property to "branches/branch1", the anchorRepository to "repo", and the stripCount property to 2. We can achieve this by either calling the appropriate setters, or in one go by calling the constructor AnchorData.AnchorData(String, String, Integer).

However, in most cases, simply setting the anchorRepository (leaving the other properties null) should be enough, because crucible will automatically compute the correct anchor path, and the correct stripCount, based on the information provided by the patch.

If anchorData is null, anchoring will not happen.

Returns:

a ReviewData with the permId attribute set to the id of the review which was just created. If the given anchorData is not null, the patch will be anchored to the repository AnchorData.getAnchorRepository().

Throws:

PatchAnchorFailedException - If anchoring fails, e.g., due to the repository not being available, or if patch anchoring fails (e.g, because the anchor path was not found), then a PatchAnchorFailedException will be thrown. The AnchorData passed into this method can be obtained by calling PatchAnchorFailedException.getAnchorData().

createSnippetReview

ReviewData createSnippetReview(ReviewData review,
                               java.lang.String snippet,
                               java.lang.String filename)

Create a new snippet review from text

Parameters:

review - a ReviewData containing the attributes of the review.

snippet - a String containing the snippet (review contents) as a stream of UTF8 characters.

filename - a suggested filename eg "test.java", "test.sql" to indicate syntax highlighting as defined in FISHEYE_HOME/syntax pass in null and we will use "filename.txt" pass in a value with no "." character, eg "java" and we will prefix it with "filename." eg "filename.java" FISHEYE_HOME/syntax an always be update _after_ creating this snippet, if the extension used was not defined

Returns:

a ReviewData with the permId attribute set to the id of the review which was just created.

createReviewFromChangeSets

ReviewData createReviewFromChangeSets(ReviewData review,
                                      java.lang.String repository,
                                      java.util.List<ChangesetData> changesets)

Create a new review from a changesets -- the review will contain all the revisions in the changesets

Parameters:

review - a ReviewData containing the attributes of the review.

repository - a String naming the repository the changesets are from.

changesets - a list of changesets containing the name of the changeset, relative to the repository

Returns:

a ReviewData with the permId attribute set to the id of the review which was just created.

addChangesetsToReview

ReviewData addChangesetsToReview(PermId<ReviewData> id,
                                 java.lang.String repository,
                                 java.util.List<ChangesetData> changesets)

Add a changeset to existing review -- the review will contain all the revisions in the changesets.

If the specified changeset contains newer revisions of files that are already in the review and have comments on them, these files will not be added to the review.

Parameters:

id - an id of review

repository - repository name of added changeset

changesets - a list of changesets containing the name of the changeset, relative to the repo given in the ReviewData

Returns:

a ReviewData with the permId attribute set to the id of the review which was just created.

addReviewRevisions

DetailedReviewData addReviewRevisions(PermId<ReviewData> reviewId,
                                      java.util.List<CrucibleRevisionData> reviewItems)
                                      throws java.lang.IllegalArgumentException,
                                             NotFoundException,
                                             NotPermittedException

Adds a review item for each of the CrucibleRevisionData given.

Parameters:

reviewId - the PermId of the review.

reviewItems - a list of CrucibleRevisionData, each one containing the desired shape of the review item. If the CrucibleRevisionData contains a path that already exists (i.e., an existing review item with the same path is in the review), then the CrucibleRevisionData given here will merge the revisions with the existing review item revisions instead of creating a new review item. The merge is documented in addReviewItemRevisions(com.atlassian.crucible.spi.PermId, com.atlassian.crucible.spi.PermId, java.util.List).

Returns:

a DetailedReviewData object with the added CrucibleRevisionData

Throws:

java.lang.IllegalArgumentException - if the repository does not exist for one or more of the given CrucibleRevisionData, or if one or more of the path does not exist in the repository specified in the CrucibleRevisionData, or if a revision specified in the CrucibleRevisionData does not exist.

NotFoundException - when the review does not exist

NotPermittedException - if the caller does not have permission to modify the review

addReviewItem

FisheyeReviewItemData addReviewItem(PermId<ReviewData> reviewId,
                                    FisheyeReviewItemData reviewItem)
                                    throws java.lang.IllegalArgumentException,
                                           NotFoundException,
                                           NotPermittedException

Adds the given review item to the review. This will always create a new review item, even if there is an existing one with the same data in the review (in which case the existing item will be replaced).

Parameters:

reviewId - a valid review id

reviewItem - a valid review item.

Returns:

the added review item with the permId set.

Throws:

java.lang.IllegalArgumentException - if the review item provided is invalid. An valid review item is one whose paths and revisions exists in the source provided.

NotFoundException - if the reviewId is not found.

NotPermittedException - if the user does not have permission to modify the review.

setReviewItem

FisheyeReviewItemData setReviewItem(PermId<ReviewData> reviewId,
                                    PermId<ReviewItemData> itemId,
                                    FisheyeReviewItemData reviewItem)
                                    throws java.lang.IllegalArgumentException,
                                           NotFoundException,
                                           NotPermittedException

sets the review item specified by itemId with the given reviewItem. The old review item is discarded. Can only perform this operation if the old review item specified by itemId can be deleted. The old review item's permId is not changed.

Parameters:

reviewId - a valid review id

itemId - a valid review item id

reviewItem - a review item to replace the given itemId.

Returns:

the newly created review item, with its itemId set to the new ID.

Throws:

java.lang.IllegalArgumentException - if the FisheyeReviewItemData is invalid. a valid FisheyeReviewItemData is one where the paths and revisions and the source exists.

NotFoundException - if the review does not exist, or if the review item does not exist.

NotPermittedException - if the caller does not have permission to modify the review, or if the given itemId could not be deleted (due to having existing comments).

addReviewItemRevisions

ReviewItemData addReviewItemRevisions(PermId<ReviewData> reviewId,
                                      PermId<ReviewItemData> itemId,
                                      java.util.List<java.lang.String> revisions)
                                      throws java.lang.IllegalArgumentException,
                                             NotFoundException,
                                             NotPermittedException

Adds the given list of revisions to the supplied review item, merging if required. For example, if the review item for a.txt contains revisions 3 to 6, and if:

 

  
revisions to add is 4 and 5, then a.txt will have revisions 3--4--5--6
  
revisions to add is 2 and 7, then a.txt will have revisions 2--3--6--7
  
revisions to add is just 2, then a.txt will have revisions 2--3--6
  
revisions to add is just 7, then a.txt will have revisions 3--6--7
  
revisions to add is 2 and 4, then a.txt will have revisions 2--3--4--6
  
revisions to add is 4 and 7, then a.txt will have revisions 3--4--6--7
 
 

Parameters:

reviewId - the id of the review

itemId - the id of the review item

revisions - a list of revisions to add to the review item, merging if required. If a revision already exists in the given review item, then the given revision is ignored.

Returns:

the review item with the added list of revisions

Throws:

java.lang.IllegalArgumentException - when one or more of the given list of revision does not exist

NotFoundException - if the review does not exist, or if the review item does not exist

NotPermittedException - if the caller does not have permission to modify the review

removeReviewItemRevisions

void removeReviewItemRevisions(PermId<ReviewData> reviewId,
                               PermId<ReviewItemData> itemId,
                               java.util.List<java.lang.String> revisions)
                               throws java.lang.IllegalArgumentException,
                                      NotFoundException,
                                      NotPermittedException

Removes the revisions given from the review item in the review specified by the id. If the review item has no more revisions left, it is automatically deleted.

Parameters:

reviewId - the id of the review

itemId - the id of the review item from which to remove the list of revisions

revisions - a list of revisions to remove. If the revision does not exist in the review item, it is ignored

Throws:

java.lang.IllegalArgumentException - if any of the given list of revisions does not exist, or if any revision could not be deleted due to it having exiting comments.

NotFoundException - when the review does not exist, or when the review item id is invalid

NotPermittedException - if the caller does not have permission to modify the review

addPatchToReview

ReviewData addPatchToReview(PermId<ReviewData> id,
                            java.lang.String patch)

Add a patch to existing review -- the review will contain provied patch

Parameters:

id - an id of review

patch - a String containing the patch as a stream of UTF-8 characters.

Returns:

a ReviewData with the permId attribute set to the id of the review which was just created.

addPatchToReview

ReviewData addPatchToReview(PermId<ReviewData> id,
                            java.lang.String patch,
                            AnchorData anchorData)
                            throws PatchAnchorFailedException

Add a patch to existing review. If the given anchorData is not null, then also anchor the patch to the repository provided by AnchorData.getAnchorRepository().

Parameters:

id - an id of the review

patch - a String containing the patch as a stream of UTF-8 characters.

anchorData - a pojo with the anchor info. see createReviewFromPatch(com.atlassian.crucible.spi.data.ReviewData, String, com.atlassian.crucible.spi.data.AnchorData) for more information.

Returns:

a ReviewData with the permId attribute set to the id of the review which was just created.

Throws:

PatchAnchorFailedException - when anchoring failed. see createReviewFromPatch(ReviewData, String, AnchorData) for more information.

addFileToReview

FisheyeReviewItemData addFileToReview(PermId<ReviewData> id,
                                      FileData file,
                                      FileData diff)

Adds a file to the review, optionally diff'ed to a second file.

Parameters:

id - of the review to add the file to

file - file to include in the review. Required.

diff - when not null, fileToReview gets diff'ed to this file.

Returns:

the newly created FisheyeReviewItemData instance.

getAllReviews

java.util.List<ReviewData> getAllReviews(boolean details)

Get a ReviewData instance for each review.

Parameters:

details - true if details should be fetched for the review. If the details is set, the review data will also contain the html rendered comments. Get them by calling CommentData.getMessageAsHtml(). If this parameter is set to false, then the above call will return null.

Returns:

a List containing all reviews.

getReview

ReviewData getReview(PermId<ReviewData> id,
                     boolean details)

Deprecated. use the versions without the 'details' parameter

getReview

ReviewData getReview(PermId<ReviewData> id)

Gets a single review from its permId. If the review does not exist an exception is thrown.

Parameters:

id - the PermId of the review to return.

Returns:

a ReviewData instance containing the attributes of the review.

Throws:

NotFoundException - if the review could not be found.

getReviewDetails

DetailedReviewData getReviewDetails(PermId<ReviewData> id)

Get a single review from its permId. If the review does not exist an exception is thrown. the review data will also contain the html rendered comments. Get them by calling CommentData.getMessageAsHtml().

Parameters:

id - the PermId of the review to return.

Returns:

a ReviewData instance containing the attributes of the review.

Throws:

NotFoundException - if the review could not be found.

getAllowedActionsForReview

java.util.List<ActionData> getAllowedActionsForReview(PermId<ReviewData> id)

Get a list of the actions which the current user is allowed to perform on the review.

This shows actions the user has permission to perform - the review may not be in a suitable state for all these actions to be performed.

Parameters:

id - the PermId of the checked review

Returns:

a List of allowed actions

getAllowedTransitionsForReview

java.util.List<ActionData> getAllowedTransitionsForReview(PermId<ReviewData> id)

Get a list of the actions which the current user can perform on this review, given its current state and the user's permissions.

Parameters:

id - the PermId of the checked review

Returns:

a List of allowed transitions

getReviewsInStates

java.util.List<ReviewData> getReviewsInStates(ReviewData.State[] states,
                                              boolean details)

Retrieves all reviews that are in one of the the specified states.

Parameters:

states - of reviews to fetch

details - true if details should be fetched for reviews. If true, the review data will also contain the html rendered comments. Get them by calling CommentData.getMessageAsHtml(). If false, the above call will return null.

Returns:

reviews which are in a particular state

getAllReviewers

java.util.Set<ReviewerData> getAllReviewers(PermId<ReviewData> id)

Get the reviewer data of all the reviewers on a review.

Parameters:

id - the PermId of the review.

Returns:

a Set containing the usernames of all the reviewers.

getCompletedReviewers

java.util.Set<ReviewerData> getCompletedReviewers(PermId<ReviewData> reviewDataPermId)

Get the reviewer data of the reviewers that already completed a review.

Parameters:

reviewDataPermId - the PermId of the review.

Returns:

a Set containing the usernames of all the reviewers.

getUncompletedReviewers

java.util.Set<ReviewerData> getUncompletedReviewers(PermId<ReviewData> reviewDataPermId)

Get the reviewer data of the reviewers that didn't complete the review.

Parameters:

reviewDataPermId - the PermId of the review.

Returns:

a Set containing the usernames of all the reviewers.

addReviewers

void addReviewers(PermId<ReviewData> id,
                  java.lang.String[] userNames)

Add reviewers to a review

Parameters:

id - the PermId of the review.

userNames - the set of names of the users to make a reviewer

removeReviewer

void removeReviewer(PermId<ReviewData> id,
                    java.lang.String userName)

Remove reviewers from a review

Parameters:

id - the PermId of the review.

userName - the username of the user to remove a reviewer role

addFisheyeDiff

ReviewItemData addFisheyeDiff(PermId<ReviewData> id,
                              java.lang.String repositoryName,
                              java.lang.String fromPath,
                              java.lang.String fromRevision,
                              java.lang.String toPath,
                              java.lang.String toRevision)

Add the changes between two files in a fisheye repository to the review.

Parameters:

id - the PermId of the review to add the diff to.

repositoryName - a String naming the repository to use.

fromPath - the path of the older version of the file within the repository.

fromRevision - the revision of the older version.

toPath - the path of the newer version of the file within the repository (often the same as fromPath)

toRevision - the revision of the newer version of the file.

Returns:

a ReviewItemData instance containing details of the diff added to the review.

removeReviewItem

void removeReviewItem(PermId<ReviewData> reviewId,
                      PermId<ReviewItemData> itemId)

Remove an item from a review.

Parameters:

reviewId - the PermId of the review to remove the item from.

itemId - the PermId of the item to remove.

getReviewItemsForReview

java.util.List<ReviewItemData> getReviewItemsForReview(PermId<ReviewData> id)

Get a list of all the items in a review.

Parameters:

id - PermId of the review.

Returns:

a List of all the items in the review.

addComment

VersionedLineCommentData addComment(PermId<ReviewItemData> id,
                                    VersionedLineCommentData comment)

Add a comment to a review item.

If no line ranges are specified in the comment a review item level comment is created, otherwise an inline comment is created. When creating an inline comment, if using the deprecated VersionedLineCommentData.getFromLineRange() and VersionedLineCommentData.getToLineRange() (instead of VersionedLineCommentData.getLineRanges()), the comment will be created on the oldest and newest revision of the review item.

Emits a CommentCreatedEvent for the created comment.

Parameters:

id - the PermId<ReviewItemData> of the item to add the comment to.

comment - a VersionedLineCommentData containing the details of the comment.

Returns:

a VersionedLineCommentData with the details of the created comment. The CommentDataImpl.getMessageAsHtml() will contain the comment renderd in html.

Throws:

java.lang.NullPointerException - if any argument is null

NotFoundException - if the specified review item doesn't exist

NotPermittedException - if the effective principal is not permitted to comment on the review

java.lang.IllegalArgumentException - if the comment refers to a non-existent revision of the review item, or is to be made on more than two revisions of the review item

java.lang.IllegalStateException - if the review containing the review item is not open for commenting (see ReviewData.State)

addGeneralComment

GeneralCommentData addGeneralComment(PermId<ReviewData> id,
                                     GeneralCommentData comment)

Add a general comment to a review.

Emits a CommentCreatedEvent for the created comment.

Parameters:

id - the PermId<ReviewData> of the review to add the comment to

comment - a GeneralCommentData containing the details of the comment

Returns:

a GeneralCommentData with the details of the created comment. The CommentDataImpl.getMessageAsHtml() will contain the comment renderd in html.

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the review permId is not well-formed; if replies are specified for the new comment

NotFoundException - if the review does not exist

NotPermittedException - if the effective principal is not permitted to comment on the review

java.lang.IllegalStateException - if the review is not open for commenting (see ReviewData.State)

getComment

CommentData getComment(PermId<CommentData> id)

Get the details of a comment by its id. Same as calling getComment(com.atlassian.crucible.spi.PermId, boolean) with withHtmlMessage set to false.

Parameters:

id - the PermId<CommentData> of the comment to retrieve.

Returns:

a CommentData subclass.

See Also:

getComment(com.atlassian.crucible.spi.PermId , boolean)

getComment

CommentData getComment(PermId<CommentData> id,
                       boolean withHtmlMessage)

Get the details of a comment by its id.

Parameters:

id - the PermId<CommentData> of the comment to retrieve.

withHtmlMessage - If true, the CommentData will also contain the html rendered comment. Get it by calling CommentData.getMessageAsHtml(). If false, the above call will return null.

Returns:

a CommentData subclass.

Throws:

java.lang.NullPointerException - if id is null

java.lang.IllegalArgumentException - if the comment permId is not well-formed

NotFoundException - if the comment doesn't exist

NotPermittedException - if the effective principal is not permitted to view the review containing the comment, or if the comment is a draft and the effective user isn't its author

updateComment

void updateComment(PermId<CommentData> commentId,
                   GeneralCommentData comment)

Update the details of a comment.

Although you can update any type of comment, it's not possible to modify the revisions or line ranges of versioned line comments.

Emits a CommentUpdatedEvent for the updated comment.

Parameters:

commentId - the PermId<CommentData> of the comment to update.

comment - a GeneralCommentData containing the details of the comment.

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the comment permId is not well-formed; if the comment specifies any replies

NotFoundException - if the comment doesn't exist

NotPermittedException - if the effective user is not permitted to comment on the review containing the comment, or if the effective user is not author of the comment

java.lang.IllegalStateException - if the review containing the comment is not open for commenting (see ReviewData.State)

removeComment

void removeComment(PermId<CommentData> commentId)
                   throws NotFoundException

Remove a comment, and all of its descendent draft replies, from a review.

Emits a CommentDeletedEvent for the comment if it wasn't a draft. Note that no event is emitted for removed descendent draft replies.

Parameters:

commentId - the PermId<CommentData> of the comment to remove.

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the comment permId is not well-formed; if the comment has non-draft replies

NotFoundException - if the comment doesn't exist

NotPermittedException - if the effective user is not permitted to comment on the review containing the comment, or if the effective user is not the author of the comment

java.lang.IllegalStateException - if the review containing the comment is not open for commenting (see ReviewData.State)

addReply

GeneralCommentData addReply(PermId<CommentData> commentId,
                            GeneralCommentData comment)

Add a reply to comment in a review.

Emits a CommentCreatedEvent for the added reply.

Parameters:

commentId - the PermId<CommentData> of the comment to add reply to.

comment - a GeneralCommentData containing the details of the reply

Returns:

a GeneralCommentData with the details of the comment added. The CommentDataImpl.getMessageAsHtml() will contain the comment renderd in html.

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the comment permId is not well-formed; if the comment specifies any replies; if you add a non-draft reply to a draft parent comment

NotFoundException - if the parent comment doesn't exist

NotPermittedException - if the effective user is not permitted to comment on the review containing the parent comment

java.lang.IllegalStateException - if the review containing the parent comment is not open for commenting (see ReviewData.State)

postComment

void postComment(PermId<CommentData> commentId)

Post a comment in draft state (any kind of comment, also reply).

Note that once a review is no longer open for comments, e.g., in summary or closed, there are no longer any draft comments.

Emits a CommentUpdatedEvent for the posted comment,

Parameters:

commentId - the PermId<CommentData> of the comment to post.

Throws:

java.lang.NullPointerException - if commentId or commentId.getId() are null

java.lang.IllegalArgumentException - if the comment permId isn't valid, or if the comment isn't a draft, or if posting a draft reply to a draft parent comment

NotFoundException - if the comment doesn't exist

NotPermittedException - if the effective user is not permitted to comment on the review containing the comment, or the effective user is not the author of the comment.

java.lang.IllegalStateException - if the review containing the comment is not open for commenting (see ReviewData.State)

postComments

void postComments(PermId<ReviewData> id)

Post all draft comments, including replies, authored by the effective user.

Emits a CommentCreatedEvent for each draft comment posted.

Parameters:

id - the PermId<ReviewData> of the review to post the comment.

Throws:

java.lang.NullPointerException - if id is null

java.lang.IllegalArgumentException - if id is not a well-formed review PermId

NotFoundException - if the review doesn't exist

NotPermittedException - if the effective user is not permitted to comment on the review

java.lang.IllegalStateException - if the review is not open for commenting (see ReviewData.State)

markAllCommentsAsRead

DetailedReviewData markAllCommentsAsRead(PermId<ReviewData> reviewId)

For the effective user, mark all comments in a review as read (except those marked as leave unread).

Parameters:

reviewId - the PermId<ReviewData> of the review to mark all comments as read.

Returns:

data of the review. The call to CommentData.getMessageAsHtml() contain the comments rendered in html

Throws:

java.lang.NullPointerException - if reviewId is null

java.lang.IllegalArgumentException - if reviewId is not a well-formed review permId

NotFoundException - if the review doesn't exist

NotPermittedException - if the effective user is not permitted to comment on the review

java.lang.IllegalStateException - if the review is not open for commenting (see ReviewData.State)

markCommentAsRead

CommentData markCommentAsRead(PermId<CommentData> commentId)

Mark a comment as read by the effective user (even if already read).

Parameters:

commentId - the PermId<CommentData> of the comment to mark as read.

Returns:

data of the comment marked as read. The call to CommentData.getMessageAsHtml() will return the rendered html.

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the comment permId is not well-formed

NotFoundException - if the comment doesn't exist

NotPermittedException - if the effective user is not permitted to comment on the review

java.lang.IllegalStateException - if the review containing the comment is not open for commenting (see ReviewData.State)

markCommentAsLeaveUnread

CommentData markCommentAsLeaveUnread(PermId<CommentData> commentId)

Mark a comment as leave unread for the effective user (even if already marked as leave unread).

Parameters:

commentId - the PermId<CommentData> to leave unread.

Returns:

data of the comment marked as read.The call to CommentData.getMessageAsHtml() will return the rendered html.

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the comment permId is not well-formed

NotFoundException - if the comment doesn't exist

NotPermittedException - if the effective user is not permitted to comment on the review

java.lang.IllegalStateException - if the review containing the comment is not open for commenting (see ReviewData.State)

completeReview

void completeReview(PermId<ReviewData> reviewDataPermId,
                    boolean complete)

Complete/uncomplete review by reviewer

Parameters:

reviewDataPermId - the PermId of the review to complete.

complete - - true-complete, false - uncomplete

closeReviewWithSummary

ReviewData closeReviewWithSummary(PermId<ReviewData> id,
                                  java.lang.String message)

Complete/uncomplte review by reviewer

Parameters:

id - the PermId of the review to close.

message - summmary message

Returns:

update review data. The call to CommentData.getMessageAsHtml() will *NOT* return the rendered html.

getGeneralComments

java.util.List<GeneralCommentData> getGeneralComments(PermId<ReviewData> id)

Get a list of the general comments visible to the effective user for a particular review.

Note that the list returned by this method only contains the root-level comments and not any replies. The replies to each comment are recursively accessed through the CommentData.getReplies() method.

Note The call to CommentDataImpl.getMessageAsHtml() will *NOT* return the rendered html. Call getGeneralComments(com.atlassian.crucible.spi.PermId, boolean) with the withHtmlMessage flag set to true to do that.

Parameters:

id - the PermId<ReviewData> of the review.

Returns:

a List<GeneralCommentData> containing the comments or an empty list if there are none

Throws:

java.lang.NullPointerException - if id is null

java.lang.IllegalArgumentException - if the review permId is not well-formed

NotPermittedException - if the effective principal is not permitted to view the review

NotFoundException - if the review does not exist

getGeneralComments

java.util.List<GeneralCommentData> getGeneralComments(PermId<ReviewData> id,
                                                      boolean withHtmlMessage)

Same as getGeneralComments(com.atlassian.crucible.spi.PermId),except if the parameter withHtmlMessage is set to true, CommentDataImpl.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup). Otherwise, CommentDataImpl.getMessageAsHtml() will return null.

Parameters:

id - the perma id of the review frin which to get the general comments.

withHtmlMessage - true if the returned comment should have the property 'messageAsHtml' contain the rendered html.

Returns:

a list of general comments for the given review permaid. If withHtmlMessage is set to true, then also wiki render the comments into html.

getVersionedComments

java.util.List<VersionedLineCommentData> getVersionedComments(PermId<ReviewItemData> id)

Get a list of the comments visible to the effective user for a particular review item.

Note that the list returned by this method only contains the root-level comments and not any replies. The replies to each comment are recursively accessed through the CommentData.getReplies() method.

Parameters:

id - the PermId<ReviewItemData> of the item.

Returns:

a List<VersionedLineCommentData> containing the comments or an empty list if there are none

Throws:

java.lang.NullPointerException - if id is null

NotFoundException - if the specified review item doesn't exist

NotPermittedException - if the effective principal is not permitted to view the review containing the review item

getVersionedComments

java.util.List<VersionedLineCommentData> getVersionedComments(PermId<ReviewItemData> id,
                                                              boolean withHtmlMessage)

Same as getVersionedComments(com.atlassian.crucible.spi.PermId), except if the parameter withHtmlMessage is set to true, CommentDataImpl.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup). Otherwise, CommentDataImpl.getMessageAsHtml() will return null.

Parameters:

id - the PermId<ReviewItemData> of the item.

withHtmlMessage - true if the returned comment should have the property 'messageAsHtml' contain the rendered html.

Returns:

a List<VersionedLineCommentData> containing the comments (with the individual comments optionally rendered as HTML, see above) or an empty list if there are none

getAllRevisionComments

java.util.List<VersionedLineCommentData> getAllRevisionComments(PermId<ReviewData> id)

Get a list of the comments on all the review items in a review, i.e., excluding general comments, that are visible to the effective user for a particular review.

Note that the list returned by this method only contains the root-level comments and not any replies. The replies to each comment are recursively accessed through the CommentData.getReplies() method.

Parameters:

id - the PermId<ReviewData> of the review.

Returns:

a List<VersionedLineCommentData> containing the comments or an empty list if there are none

Throws:

java.lang.NullPointerException - if id is null

java.lang.IllegalArgumentException - if the review permId is not well-formed

NotPermittedException - if you are not permitted to view the review

NotFoundException - if the review does not exist

getAllRevisionComments

java.util.List<VersionedLineCommentData> getAllRevisionComments(PermId<ReviewData> id,
                                                                boolean withHtmlMessage)

Same as calling getAllRevisionComments(com.atlassian.crucible.spi.PermId). If 'withHtmlMessage' is true, CommentDataImpl.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup). Otherwise, it will return null.

Parameters:

id - the PermId<ReviewData> of the review.

withHtmlMessage - true if the returned comment should have the property 'messageAsHtml' contain the rendered html.

Returns:

a List<VersionedLineCommentData> containing the comments (with the individual comments optionally rendered as HTML, see above) or an empty list if there are none

getReplies

java.util.List<GeneralCommentData> getReplies(PermId<CommentData> commentId)

Get a list of the comment replies that are visible to the effective user.

Note that the list returned by this method only contains the direct child comments and not any more deeply nested replies. The nested replies to each returned reply are recursively accessed through the CommentData.getReplies() method.

Parameters:

commentId - id of the parent comment

Returns:

a list of the comments or an empty list if there are none

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if the comment permId is not well-formed

NotFoundException - if the comment doesn't exist

NotPermittedException - if the effective principal is not permitted to view the review containing the comment; if the comment is a draft and the effective user isn't its author;

getReplies

java.util.List<GeneralCommentData> getReplies(PermId<CommentData> commentId,
                                              boolean withHtmlMessage)

Same as calling getReplies(com.atlassian.crucible.spi.PermId). If 'withHtmlMessage' is true, CommentDataImpl.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup). Otherwise, CommentDataImpl.getMessageAsHtml() will return null.

Parameters:

commentId - id of the parent comment

withHtmlMessage - true if the returned comment should have the property 'messageAsHtml' contain the rendered html.

Returns:

a list of the comments (with the individual comments optionally rendered as HTML, see above) or an empty list if there are none

getUncompletedReviewsForUser

java.util.List<ReviewData> getUncompletedReviewsForUser(java.lang.String userName)

Get a list of all the reviews for which the user is a reviwer who has not completed the review.

Parameters:

userName - a String naming the user.

Returns:

a List containing the active reviews. Calls to CommentData.getMessageAsHtml() will *not* return the rendered html.

getFilteredReviews

java.util.List<ReviewData> getFilteredReviews(java.lang.String filter,
                                              boolean details)

Get a list of all the reviews for which the user involved based on predefined criteria.

Filter names are:

"allReviews"

All reviews.

"allOpenReviews"

All open reviews.

"allClosedReviews"

All closed reviews.

"draftReviews"

All draft reviews.

"toReview"

Open reviews on which the current user is an incomplete reviewer.

"requireMyApproval"

Reviews waiting to be started on which the current user is the moderator.

"toSummarize"

Reviews with all reviewers complete and where the current user is the moderator.

"outForReview"

Reviews in progress where the current user is the author or the moderator.

"drafts"

Drafts created by the current user.

"open"

Open reviews the current user is involved with as a creator, author, moderator or reviewer.

"closed"

Closed reviews the current user was involved with as a creator, author, moderator or reviewer.

"trash"

Abandoned reviews the current user created.

Parameters:

filter - a predefined filter name

details - true if details should be fetched for the review. If true, then CommentData.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup). Otherwise, CommentData.getMessageAsHtml() will return null.

Returns:

a List containing the filtered reviews.

getCustomFilterReviews

java.util.List<ReviewData> getCustomFilterReviews(CustomFilterData filter,
                                                  boolean details)

Get a list of all the reviews for which the user involved based on predefined criteria.

Parameters:

filter - custom filter definition

details - true if details should be fetched for the review. If true, then CommentData.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup). Otherwise, CommentData.getMessageAsHtml() will return null.

Returns:

a List containing the filtered reviews.

getAllReviewsForItem

java.util.List<ReviewData> getAllReviewsForItem(java.lang.String path,
                                                java.lang.String repositoryName,
                                                boolean details)

Finds all reviews that contain at least one revision of the specified file.

Parameters:

path - path to find in reviews

repositoryName - repository to search for file

details - output format with details when true. If true, then CommentData.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup). Otherwise, CommentData.getMessageAsHtml() will return null.

Returns:

a List containing the specified file.

getReviewItem

FisheyeReviewItemData getReviewItem(PermId<ReviewData> reviewDataPermId,
                                    PermId<ReviewItemData> reviewItemDataPermId)

Returns detailed information for a specific review item.

Parameters:

reviewDataPermId - review id

reviewItemDataPermId - review item id

Returns:

a single item from a review.

getVersionInfo

VersionInfo getVersionInfo()

Deprecated. Moved to ServerInfoService

Get Crucible version info

Returns:

versionInfo

deleteReview

void deleteReview(PermId<ReviewData> id)

Permanently delete a review. The review must have been abandoned.

Parameters:

id - the PermId of the Review to delete.

changeState

ReviewData changeState(PermId<ReviewData> id,
                       java.lang.String action)

Change the state of a review by performing an action on it. If the action is illegal for the current state an exception will be thrown.

Parameters:

id - the PermId of the review to perform the action on

action - the string representation of Action to perform.

Returns:

a ReviewData containing the details of the review, including its new state. Calls to CommentData.getMessageAsHtml() will return null.

changeState

ReviewData changeState(PermId<ReviewData> id,
                       ReviewService.Action action)

Change the state of a review by performing an action on it. If the action is illegal for the current state an exception will be thrown.

Parameters:

id - the PermId of the review to perform the action on

action - the Action to perform.

Returns:

a ReviewData containing the details of the review, including its new state. Calls to CommentData.getMessageAsHtml() will return null.

getChildReviews

java.util.List<ReviewData> getChildReviews(PermId<ReviewData> id)

Get the child reviews belonging to a review

Parameters:

id - the PermId of the review to get children for

Returns:

a List containing the child reviews

getChildReviews

java.util.List<ReviewData> getChildReviews(PermId<ReviewData> id,
                                           boolean details)

Get the child reviews belonging to a review

Parameters:

id - the PermId of the review to get children for

details - true if details should be fetched for the review. If true, then CommentData.getMessageAsHtml() will return the comment rendered as html (respecting wiki markup). Otherwise, CommentData.getMessageAsHtml() will return null.

Returns:

a List containing the child reviews

getMetrics

java.util.List<CustomFieldDefData> getMetrics(int metricsVersion)

Get metrics metadata for specified metrics version

Parameters:

metricsVersion - metric version

Returns:

list of metrics definition

hasPermission

boolean hasPermission(PermId<ReviewData> id,
                      java.lang.String actionName)

Does the current user have permission to perform the given action on the given review?

Parameters:

id - review to check permission agains

actionName - action to be performed

Returns:

true if the user has permission