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
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);
}
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<ReviewAction> 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);
}
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
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<String, Map<String, String>> propertiesMap) {
ReviewContext context = new ReviewContext();
if (propertiesMap.get(PROJECT_KEY) != null) {
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);
}
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<String, ReviewCommand> 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<ReviewCommand> getAvailableCommandsFor(ReviewContext reviewContext) {
Preconditions.checkNotNull(reviewContext, "The review context must not be NULL when searching for available commands.");
List<ReviewCommand> commands = Lists.newArrayList();
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<ReviewCommand> filterCommands(Collection<ReviewCommand> initialCommands, ReviewContext reviewContext, String interfaceName) {
Preconditions.checkNotNull(initialCommands, "The list of review commands must not be NULL when filtering commands.");
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);
}
}
+ /**
+ * 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);
}
# 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]
# - :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]})
projects / sonarqube.git / commitdiff