001/*
002 * Sonar, open source software quality management tool.
003 * Copyright (C) 2008-2012 SonarSource
004 * mailto:contact AT sonarsource DOT com
005 *
006 * Sonar is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 3 of the License, or (at your option) any later version.
010 *
011 * Sonar is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public
017 * License along with Sonar; if not, write to the Free Software
018 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02
019 */
020package org.sonar.api.notifications;
021
022import org.sonar.api.ServerExtension;
023
024/**
025 * <p>
026 * Plugins should extend this class to provide logic to determine which users are interested in receiving notifications.
027 * It has no knowledge about the way of delivery.
028 * </p>
029 * For example:
030 * <ul>
031 * <li>notify me when someone comments on review created by me</li>
032 * <li>notify me when someone comments on review assigned to me</li>
033 * <li>notify me when someone mentions me in comment for review</li>
034 * <li>send me system notifications (like password reset, account creation, ...)</li>
035 * </ul> 
036 * 
037 * @since 2.10
038 */
039public abstract class NotificationDispatcher implements ServerExtension {
040
041  /**
042   * Additional information related to the notification, which will be used
043   * to know who should receive the notification.
044   */
045  public interface Context {
046    /**
047     * Adds a user that will be notified.
048     * 
049     * @param userLogin the user login
050     */
051    void addUser(String userLogin);
052  }
053
054  /**
055   * Returns the unique key of this dispatcher. 
056   * 
057   * @return the key
058   */
059  public String getKey() {
060    return getClass().getSimpleName();
061  }
062
063  /**
064   * <p>
065   * Implements the logic that defines which users will receive the notification.
066   * </p>
067   * 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.
068   * 
069   * @param notification the notification that will be sent
070   * @param the context linked to this notification
071   */
072  public abstract void dispatch(Notification notification, Context context);
073
074  @Override
075  public String toString() {
076    return getKey();
077  }
078
079}