*/
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;
/**
+ * <p>
+ * 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}).
+ * </p>
+ *
* @since 2.10
*/
public class Notification implements Serializable {
private String type;
- private HashMap<String, String> fields = Maps.newHashMap(); // NOSONAR false-positive due to serialization : usage of HashMap instead of Map
+ private HashMap<String, String> fields = Maps.newHashMap(); // NOSONAR false-positive due to serialization : usage of HashMap instead of
+ // Map
+ /**
+ * <p>
+ * Create a new {@link Notification} of the given type.
+ * </p>
+ * 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);
}
import org.sonar.api.ServerExtension;
/**
- * Provides logic to deliver notification.
+ * <p>
+ * Plugins should extend this class to provide implementation on a specific way to deliver notifications.
+ * </p>
* For example:
* <ul>
* <li>email - sends email as soon as possible</li>
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() {
import org.sonar.api.ServerExtension;
/**
- * Provides logic to determine which users are interested in receiving notification.
- * Has no knowledge about the way of delivery.
+ * <p>
+ * 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.
+ * </p>
* For example:
* <ul>
* <li>notify me when someone comments on review created by me</li>
*/
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
+ * <p>
+ * Implements the logic that defines which users will receive the notification.
+ * </p>
+ * 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);
import org.sonar.api.ServerComponent;
/**
+ * <p>
+ * The notification manager receives notifications and is in charge of storing them so that they are processed by the notification service.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ *
* @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);
}
projects / sonarqube.git / commitdiff