From ee368b839c08103857e0791c8957f9179e40f058 Mon Sep 17 00:00:00 2001 From: Fabrice Bellingard Date: Fri, 3 Feb 2012 18:30:22 +0100 Subject: Sonar API - Try to improve documentation of notifications --- .../org/sonar/api/notifications/Notification.java | 42 +++++++++++++++++++--- .../api/notifications/NotificationChannel.java | 16 +++++++-- .../api/notifications/NotificationDispatcher.java | 29 ++++++++++++--- .../api/notifications/NotificationManager.java | 13 +++++++ 4 files changed, 88 insertions(+), 12 deletions(-) (limited to 'sonar-plugin-api') diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/Notification.java b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/Notification.java index de1b5cd9075..c69cc777d3f 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/Notification.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/Notification.java @@ -19,35 +19,69 @@ */ package org.sonar.api.notifications; -import com.google.common.collect.Maps; +import java.io.Serializable; +import java.util.HashMap; + import org.apache.commons.lang.builder.ReflectionToStringBuilder; import org.apache.commons.lang.builder.ToStringStyle; -import java.io.Serializable; -import java.util.HashMap; +import com.google.common.collect.Maps; /** + *

+ * This class represents a notification that will be delivered to users. This is a general concept and it has no + * knowledge of the possible ways to be delivered (see {@link NotificationChannel}) or of the users who should + * receive it (see {@link NotificationDispatcher}). + *

+ * * @since 2.10 */ public class Notification implements Serializable { private String type; - private HashMap fields = Maps.newHashMap(); // NOSONAR false-positive due to serialization : usage of HashMap instead of Map + private HashMap fields = Maps.newHashMap(); // NOSONAR false-positive due to serialization : usage of HashMap instead of + // Map + /** + *

+ * Create a new {@link Notification} of the given type. + *

+ * Example: type = "new-violations" + * + * @param type the type of notification + */ public Notification(String type) { this.type = type; } + /** + * Returns the type of the notification + * + * @return the type + */ public String getType() { return type; } + /** + * Adds a field (kind of property) to the notification + * + * @param field the name of the field (= the key) + * @param value the value of the field + * @return the notification itself + */ public Notification setFieldValue(String field, String value) { fields.put(field, value); return this; } + /** + * Returns the value of a field. + * + * @param field the field + * @return the value of the field + */ public String getFieldValue(String field) { return fields.get(field); } diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationChannel.java b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationChannel.java index cef007a3f65..a187218b087 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationChannel.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationChannel.java @@ -22,7 +22,9 @@ package org.sonar.api.notifications; import org.sonar.api.ServerExtension; /** - * Provides logic to deliver notification. + *

+ * Plugins should extend this class to provide implementation on a specific way to deliver notifications. + *

* For example: *
    *
  • email - sends email as soon as possible
    • @@ -35,13 +37,21 @@ import org.sonar.api.ServerExtension; public abstract class NotificationChannel implements ServerExtension { /** - * @return unique key of this channel + * Returns the unique key of this channel. + * + * @return the key */ public String getKey() { return getClass().getSimpleName(); } - public abstract void deliver(Notification notification, String username); + /** + * Implements the delivery of the given notification to the given user. + * + * @param notification the notification to deliver + * @param userlogin the login of the user who should receive the notification + */ + public abstract void deliver(Notification notification, String userlogin); @Override public String toString() { diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationDispatcher.java b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationDispatcher.java index f905fd5ef52..0516215729a 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationDispatcher.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationDispatcher.java @@ -22,8 +22,10 @@ package org.sonar.api.notifications; import org.sonar.api.ServerExtension; /** - * Provides logic to determine which users are interested in receiving notification. - * Has no knowledge about the way of delivery. + *

    + * Plugins should extend this class to provide logic to determine which users are interested in receiving notifications. + * It has no knowledge about the way of delivery. + *

    * For example: *
      *
    • notify me when someone comments on review created by me
      • @@ -36,19 +38,36 @@ import org.sonar.api.ServerExtension; */ public abstract class NotificationDispatcher implements ServerExtension { + /** + * Additional information related to the notification, which will be used + * to know who should receive the notification. + */ public interface Context { - void addUser(String username); + /** + * Adds a user that will be notified. + * + * @param userLogin the user login + */ + void addUser(String userLogin); } /** - * @return unique key of this dispatcher + * Returns the unique key of this dispatcher. + * + * @return the key */ public String getKey() { return getClass().getSimpleName(); } /** - * @return recipients + *

      + * Implements the logic that defines which users will receive the notification. + *

      + * The purpose of this method is to populate the context object with users, based on the type of notification and the content of the notification. + * + * @param notification the notification that will be sent + * @param the context linked to this notification */ public abstract void dispatch(Notification notification, Context context); diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationManager.java b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationManager.java index 834c990fdb8..10879bf19de 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationManager.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationManager.java @@ -23,10 +23,23 @@ import org.sonar.api.BatchComponent; import org.sonar.api.ServerComponent; /** + *

      + * The notification manager receives notifications and is in charge of storing them so that they are processed by the notification service. + *

      + *

      + * Pico provides an instance of this class, and plugins just need to create notifications and pass them to this manager with + * the {@link NotificationManager#scheduleForSending(Notification)} method. + *

      + * * @since 2.10 */ public interface NotificationManager extends ServerComponent, BatchComponent { + /** + * Receives a notification and stores it so that it is processed by the notification service. + * + * @param notification the notification. + */ void scheduleForSending(Notification notification); } -- cgit v1.2.3