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

Nested Classes

Modifier and Type	Interface and Description
static class	ReviewService.Action The actions which can be performed on a review, changing its state.

Method Summary

Modifier and Type	Method and Description
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 provided patch
ReviewData	addPatchToReview(PermId<ReviewData> id, java.lang.String patch, AnchorData anchorData) Add a patch to existing review.
ReviewData	addPatchToReview(PermId<ReviewData> id, java.lang.String patch, AnchorData anchorData, java.lang.String source) 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, ReviewService.Action action, boolean skipWarnings) 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	changeState(PermId<ReviewData> id, java.lang.String action, boolean skipWarnings) Change the state of a review by performing an action on it.
void	checkChangesetSizeAcceptable(java.util.List<ChangesetData> changesets, java.lang.String repository) Allows to check if the size of changesets does not exceed allowed limit so they can be added to a review.
ReviewData	closeReviewWithSummary(PermId<ReviewData> id, java.lang.String message) Closes review with message summary, skips transition warnings.
ReviewData	closeReviewWithSummary(PermId<ReviewData> id, java.lang.String message, boolean skipWarnings) Closes review with message summary
void	completeReview(PermId<ReviewData> reviewDataPermId, boolean complete) Complete/uncomplete review by reviewer, skips transition validation warnings.
void	completeReview(PermId<ReviewData> reviewDataPermId, boolean complete, boolean skipWarnings) 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.lang.String	extractReviewTitle(java.lang.String text)
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.
CommentResolutionData	getCommentResolution(PermId<CommentData> commentId) Gets comment resolution data.
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<PatchGroupData>	getReviewPatches(PermId<ReviewData> id) Get the list of patches in the 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.
java.util.List<UserData>	remindIncompleteReviewers(PermId<ReviewData> id) Send a reminder message to incomplete reviewers about finishing this review.
java.util.List<UserData>	remindIncompleteReviewers(PermId<ReviewData> id, java.util.Set<java.lang.String> recipients, java.lang.String message) Send a reminder message to incomplete reviewers about finishing this review.
void	removeComment(PermId<CommentData> commentId) Remove a comment, and all of its descendent draft replies, from a review.
java.util.List<PatchGroupData>	removePatchFromReview(PermId<ReviewData> reviewPermaId, int patchId) Removes the patch with a given id from the 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.
void	setCommentResolution(PermId<CommentData> commentId, CommentResolutionStatus commentResolutionStatus) Sets resolution status of a comment.
FisheyeReviewItemData	setReviewItem(PermId<ReviewData> reviewId, PermId<ReviewItemData> itemId, FisheyeReviewItemData reviewItem) sets the review item specified by itemId with the given reviewItem.
default ReviewData	setState(PermId<ReviewData> id, java.lang.String state)
void	tryAutomaticJiraLinking(PermId<ReviewData> id) Try to link the given review to existing Jira issues.
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)
                          throws ChangeSetContentTooLargeException

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.

Throws:

ChangeSetContentTooLargeException - if the given patch is too large (contains too many files) for a single review

createReviewFromPatch

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

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(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(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().

ChangeSetContentTooLargeException - if the given patch is too large (contains too many files) for a single review

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)
                               throws ChangeSetContentTooLargeException

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 key of 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.

Throws:

ChangeSetContentTooLargeException - if the total size of aggregated changesets exceeds allowed limit

addChangesetsToReview

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

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 - the key of the repository 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.

Throws:

ChangeSetContentTooLargeException - if the total size of aggregated changesets exceeds allowed limit

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

addReviewRevisions

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

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.data.ReviewData>, com.atlassian.crucible.spi.PermId<com.atlassian.crucible.spi.data.ReviewItemData>, java.util.List<java.lang.String>).

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 or the caller does not have permission to access it

ChangeSetContentTooLargeException - if the total size of aggregated changesets exceeds allowed limit

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

addReviewItem

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

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 - when the review does not exist or the caller does not have permission to access it

ChangeSetContentTooLargeException - if the total size of aggregated changesets exceeds allowed limit

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

setReviewItem

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

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 - when the review does not exist or the caller does not have permission to access it

ChangeSetContentTooLargeException - if the total size of aggregated changesets exceeds allowed limit

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

addReviewItemRevisions

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

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 - when the review does not exist or the caller does not have permission to access it

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

removeReviewItemRevisions

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

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 the caller does not have permission to access it

addPatchToReview

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

Add a patch to existing review -- the review will contain provided 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.

Throws:

ChangeSetContentTooLargeException - if the given patch is too large (contains too many files) for a single review

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

addPatchToReview

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

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.

ChangeSetContentTooLargeException - if the given patch is too large (contains too many files) for a single review

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

addPatchToReview

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

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.

source - the patch to source to add to, must be anchored to the same repository as the patch being added

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.

ChangeSetContentTooLargeException - if the given patch is too large (contains too many files) for a single review

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

removePatchFromReview

java.util.List<PatchGroupData> removePatchFromReview(PermId<ReviewData> reviewPermaId,
                                                     int patchId)

Removes the patch with a given id from the review. All the file revisions that were added from that patch will be removed as well.

Parameters:

reviewPermaId - the review permaid

patchId - the id of the patch, as returned in PatchData

Returns:

the list of patches in the review after the deletion

Throws:

java.lang.IllegalArgumentException - if a patch with a given id doesn't exist or doesn't belong to the specified review

java.lang.IllegalStateException - if the patch cannot be removed from the review. This usually occurs because some of the patch revisions have comments that also would be removed.

See Also:

PatchData, getReviewPatches(PermId)

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.

Throws:

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

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)
              throws NotFoundException

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 - when the review does not exist or the caller does not have permission to access it

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

remindIncompleteReviewers

java.util.List<UserData> remindIncompleteReviewers(PermId<ReviewData> id)

Send a reminder message to incomplete reviewers about finishing this review.

Parameters:

id - the PermId of the review.

remindIncompleteReviewers

java.util.List<UserData> remindIncompleteReviewers(PermId<ReviewData> id,
                                                   java.util.Set<java.lang.String> recipients,
                                                   java.lang.String message)

Send a reminder message to incomplete reviewers about finishing this review.

Parameters:

id - the PermId of the review.

recipients - the usernames to notify

message - a message to send to the recipients about this review

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)
                       throws ReviewContentTooLargeException

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 - the key of the repository

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.

Throws:

ReviewContentTooLargeException - if the review is at or over allowed content size limit so new changes cannot be added until some other content is removed from review first.

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.

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 - when the review does not exist or the caller does not have permission to access it

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 - when the review does not exist or the caller does not have permission to access it

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.

Throws:

NotFoundException - if the comment doesn't exist

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)

setCommentResolution

void setCommentResolution(PermId<CommentData> commentId,
                          CommentResolutionStatus commentResolutionStatus)

Sets resolution status of a comment.

There are three states: unset, UNRESOLVED and RESOLVED. Once a resolution status has been set, it cannot be unset. It can only be changed to a different set value. Setting RESOLVED requires setting UNRESOLVED first.

The resolution is performed by the effective user.

Parameters:

commentId - id of the comment on which the resolution status is to be changed

commentResolutionStatus - new resolution status to be set

Throws:

java.lang.IllegalArgumentException - if commentResolutionStatus is RESOLVED and current status is not UNRESOLVED

NotFoundException - if no comment with commentId exists

NotPermittedException - if the effective user is not allowed to request resolution/resolve a comment

getCommentResolution

CommentResolutionData getCommentResolution(PermId<CommentData> commentId)

Gets comment resolution data.

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, skips transition validation warnings.

Parameters:

reviewDataPermId - the PermId of the review to complete.

complete - - true-complete, false - uncomplete

Throws:

WorkflowConditionValidationException - if workflow conditions module is enabled and given action is illegal for current transition

completeReview

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

Complete/uncomplete review by reviewer

Parameters:

reviewDataPermId - the PermId of the review to complete.

complete - - true-complete, false - uncomplete

skipWarnings - if true all transition validation warnings will be ignored

Throws:

WorkflowConditionValidationException - if workflow conditions module is enabled and given action is illegal for current transition

closeReviewWithSummary

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

Closes review with message summary, skips transition warnings.

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.

Throws:

WorkflowConditionValidationException - if workflow conditions module is enabled and given action is illegal for current transition

closeReviewWithSummary

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

Closes review with message summary

Parameters:

id - the PermId of the review to close.

message - summmary message

skipWarnings - if true all transition validation warnings will be ignored

Returns:

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

Throws:

WorkflowConditionValidationException - if workflow conditions module is enabled and given action is illegal for current transition

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

NotFoundException - when the review does not exist or the caller does not have permission to access it

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 - when the review does not exist or the caller does not have permission to access it

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

NotFoundException - when the review does not exist or the caller does not have permission to access it

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 - key of the 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.

tryAutomaticJiraLinking

void tryAutomaticJiraLinking(PermId<ReviewData> id)

Try to link the given review to existing Jira issues.

• If an issue key is not found by calling Review#getSuggestedJiraIssueKeys no issue is linked.
• If an issue key is found, and no such issue exists in any linked Jira servers, then no issue is linked.

Parameters:

id - the id of the review to try and link a Jira issue key to

getReviewPatches

java.util.List<PatchGroupData> getReviewPatches(PermId<ReviewData> id)

Get the list of patches in the review

Parameters:

id - the review id to get the patch list for

Returns:

the list of patches, grouped by iteration

setState

default ReviewData setState(PermId<ReviewData> id,
                            java.lang.String state)

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. Skips transition warnings.

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.

Throws:

WorkflowConditionValidationException - if workflow conditions module is enabled and given action is illegal for current transition

changeState

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

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.

skipWarnings - if true all transition conditions warnings will be ignored

Returns:

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

Throws:

WorkflowConditionValidationException - if workflow conditions module is enabled and given action is illegal for current transition

changeState

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

Change the state of a review by performing an action on it. Skips transition warnings.

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.

Throws:

WorkflowConditionValidationException - if workflow conditions module is enabled and given action is illegal for current transition

changeState

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

Change the state of a review by performing an action on it.

Parameters:

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

action - the Action to perform.

skipWarnings - if true all transition validation warnings will be ignored

Returns:

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

Throws:

WorkflowConditionValidationException - if workflow conditions module is enabled and given action is illegal for current transition

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)
               throws NotFoundException

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

Throws:

NotFoundException

extractReviewTitle

java.lang.String extractReviewTitle(java.lang.String text)

Returns:

a review title extracted from the supplied text. Removes newlines and truncates to the maximum title length.

checkChangesetSizeAcceptable

void checkChangesetSizeAcceptable(java.util.List<ChangesetData> changesets,
                                  java.lang.String repository)
                           throws ChangeSetContentTooLargeException

Allows to check if the size of changesets does not exceed allowed limit so they can be added to a review. Please do note there is also a limit on review content size, so although this method would advise if input changesets can be added to empty review, the attempt to add them to existent review with some content may still fail.

Parameters:

changesets - list of changesets to be analysed

repository - key of the repository changesets refer to.

Throws:

ChangeSetContentTooLargeException - if the total size of aggregated changesets exceeds allowed limit