From e325a17e17b8c42ede953545ab8d7c4ae0c02caf Mon Sep 17 00:00:00 2001 From: Fabrice Bellingard Date: Mon, 14 May 2012 12:25:56 +0200 Subject: [PATCH] SONAR-2706 Add documentation --- .../sonar/api/reviews/LinkReviewCommand.java | 2 ++ .../org/sonar/api/reviews/ReviewAction.java | 12 +++++++ .../org/sonar/api/reviews/ReviewCommand.java | 23 ++++++++++++ .../org/sonar/api/reviews/ReviewContext.java | 32 +++++++++++++++++ .../sonar/server/reviews/ReviewManager.java | 35 +++++++++++++++++++ .../WEB-INF/app/models/api/review_context.rb | 13 +++++++ .../main/webapp/WEB-INF/app/models/review.rb | 3 +- 7 files changed, 118 insertions(+), 2 deletions(-) diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/reviews/LinkReviewCommand.java b/sonar-plugin-api/src/main/java/org/sonar/api/reviews/LinkReviewCommand.java index 1e3bc0bf1c7..3b14a0cad3b 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/reviews/LinkReviewCommand.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/reviews/LinkReviewCommand.java @@ -22,6 +22,8 @@ package org.sonar.api.reviews; import com.google.common.annotations.Beta; /** + * A special {@link ReviewCommand} that will allow to create links from a review to an external system like JIRA. + * * @since 3.1 */ @Beta diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewAction.java b/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewAction.java index ca4bc54f32c..11a2358ba08 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewAction.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewAction.java @@ -23,13 +23,25 @@ import com.google.common.annotations.Beta; import org.sonar.api.ServerExtension; /** + * Represents an action that can be executed when a {@link ReviewCommand} has been triggered. + * * @since 3.1 */ @Beta public abstract class ReviewAction implements ServerExtension { + /** + * Returns the ID of the action. + * + * @return the ID + */ public abstract String getId(); + /** + * Executes the action, using the given review context. + * + * @param reviewContext the context + */ public abstract void execute(ReviewContext reviewContext); } diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewCommand.java b/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewCommand.java index 14e8098daee..3748ae82e95 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewCommand.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewCommand.java @@ -25,17 +25,40 @@ import org.sonar.api.ServerExtension; import java.util.Collection; /** + * Represents a command that can be displayed for a review. + * * @since 3.1 */ @Beta public abstract class ReviewCommand implements ServerExtension { + /** + * Returns the ID of the command. + * + * @return the ID + */ public abstract String getId(); + /** + * Returns the name of the command. + * + * @return the name + */ public abstract String getName(); + /** + * Returns the {@link ReviewAction} linked to this command. + * + * @return the list of actions + */ public abstract Collection getActions(); + /** + * Tells is the command is available in the given review context. + * + * @param reviewContext the context of the review + * @return true if the command is available, false otherwise + */ public abstract boolean isAvailableFor(ReviewContext reviewContext); } diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewContext.java index b0d3ca6d147..df12ff78f5f 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewContext.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/reviews/ReviewContext.java @@ -26,6 +26,8 @@ import org.apache.commons.lang.builder.ToStringBuilder; import java.util.Map; /** + * Context of a review, used by {@link ReviewCommand} to tell if a command is available, and by {@link ReviewAction} to execute an action based on it. + * * @since 3.1 */ @Beta @@ -44,6 +46,12 @@ public final class ReviewContext { private ReviewContext() { } + /** + * Creates a {@link ReviewContext} based on a string-based map (which will come from Ruby side). + * + * @param propertiesMap the map of properties + * @return the review context + */ public static ReviewContext createFromMap(Map> propertiesMap) { ReviewContext context = new ReviewContext(); if (propertiesMap.get(PROJECT_KEY) != null) { @@ -61,18 +69,42 @@ public final class ReviewContext { return context; } + /** + * Returns the property of the "project" + * + * @param propertyKey + * @return + */ public String getProjectProperty(String propertyKey) { return projectProps.get(propertyKey); } + /** + * Returns the property of the "review" + * + * @param propertyKey + * @return + */ public String getReviewProperty(String propertyKey) { return reviewProps.get(propertyKey); } + /** + * Returns the property of the "user" + * + * @param propertyKey + * @return + */ public String getUserProperty(String propertyKey) { return userProps.get(propertyKey); } + /** + * Returns the value of a parameter of the context (generally, user input). + * + * @param propertyKey + * @return + */ public String getParamValue(String paramKey) { return paramsProps.get(paramKey); } diff --git a/sonar-server/src/main/java/org/sonar/server/reviews/ReviewManager.java b/sonar-server/src/main/java/org/sonar/server/reviews/ReviewManager.java index d6ee862db3e..2c8c9f4da13 100644 --- a/sonar-server/src/main/java/org/sonar/server/reviews/ReviewManager.java +++ b/sonar-server/src/main/java/org/sonar/server/reviews/ReviewManager.java @@ -32,22 +32,37 @@ import java.util.List; import java.util.Map; /** + * This class helps handling {@link ReviewCommand} and {@link ReviewAction}, based on a {@link ReviewContext}. + * * @since 3.1 */ public class ReviewManager { private Map idToCommand = Maps.newLinkedHashMap(); + /** + * Creates a {@link ReviewManager} + * @param reviewCommands + */ public ReviewManager(ReviewCommand[] reviewCommands) { for (ReviewCommand reviewCommand : reviewCommands) { idToCommand.put(reviewCommand.getId(), reviewCommand); } } + /** + * Creates a {@link ReviewManager} + */ public ReviewManager() { this(new ReviewCommand[0]); } + /** + * Returns the available commands based on the given context. + * + * @param reviewContext the review context + * @return the list of available commands for this context + */ public Collection getAvailableCommandsFor(ReviewContext reviewContext) { Preconditions.checkNotNull(reviewContext, "The review context must not be NULL when searching for available commands."); List commands = Lists.newArrayList(); @@ -59,6 +74,14 @@ public class ReviewManager { return commands; } + /** + * Filter the given command collection based on the review context and on the name of the interface that the command must implement. + * + * @param initialCommands the initial list of commands + * @param reviewContext the review context + * @param interfaceName the name of the interface + * @return the filtered list of commands + */ @SuppressWarnings({"unchecked", "rawtypes"}) public Collection filterCommands(Collection initialCommands, ReviewContext reviewContext, String interfaceName) { Preconditions.checkNotNull(initialCommands, "The list of review commands must not be NULL when filtering commands."); @@ -80,6 +103,12 @@ public class ReviewManager { return commands; } + /** + * Executes the actions linked to the command which ID is passed as a paramter. + * + * @param commandId the command ID + * @param reviewContext the review context that will be passed to the actions + */ public void executeCommandActions(String commandId, ReviewContext reviewContext) { Preconditions.checkNotNull(reviewContext, "The review context must not be NULL when executing the actions of a command."); ReviewCommand command = getCommand(commandId); @@ -90,6 +119,12 @@ public class ReviewManager { } } + /** + * Returns the command corresponding to the given ID. + * + * @param commandId the command ID + * @return the command corresponding to the given ID, or null if none matches. + */ public ReviewCommand getCommand(String commandId) { return idToCommand.get(commandId); } diff --git a/sonar-server/src/main/webapp/WEB-INF/app/models/api/review_context.rb b/sonar-server/src/main/webapp/WEB-INF/app/models/api/review_context.rb index cb46e1df612..54b68249b94 100644 --- a/sonar-server/src/main/webapp/WEB-INF/app/models/api/review_context.rb +++ b/sonar-server/src/main/webapp/WEB-INF/app/models/api/review_context.rb @@ -18,7 +18,20 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02 # +# +# Class used to more easily handle the context of a review when it needs to be passed to the Java side +# +# - to create a context: (example) +# +# review_context = Api::ReviewContext.new(:review => myReview, :user => current_user, :params => {"comment.text" => comment_values[:text]}) +# +# - when it needs to be passed to the Java side, it needs to be transformed into a 'string-only' hash: +# +# review_context.to_string_map +# + class Api::ReviewContext + def initialize(options={}) @review = options[:review] @project = options[:project] diff --git a/sonar-server/src/main/webapp/WEB-INF/app/models/review.rb b/sonar-server/src/main/webapp/WEB-INF/app/models/review.rb index e8eab79d0e5..3ff214a893e 100644 --- a/sonar-server/src/main/webapp/WEB-INF/app/models/review.rb +++ b/sonar-server/src/main/webapp/WEB-INF/app/models/review.rb @@ -75,8 +75,7 @@ class Review < ActiveRecord::Base # - :user # - :text # - # param review_command_id is optional (=> specifies which command was - # triggered instead of creating a simple comment) + # Note: 'review_command_id' is optional (=> specifies which command was triggered instead of creating a simple comment) def create_comment(comment_values={}, review_command_id=nil) if review_command_id review_context = Api::ReviewContext.new(:review => self, :user => User.new(:login => comment_values[:user].login), :params => {"comment.text" => comment_values[:text]}) -- 2.39.5