001    /*
002     * SonarQube, open source software quality management tool.
003     * Copyright (C) 2008-2014 SonarSource
004     * mailto:contact AT sonarsource DOT com
005     *
006     * SonarQube 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     * SonarQube 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 License
017     * along with this program; if not, write to the Free Software Foundation,
018     * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019     */
020    package org.sonar.api.notifications;
021    
022    import org.apache.commons.lang.StringUtils;
023    import org.sonar.api.ServerExtension;
024    
025    /**
026     * <p>
027     * Plugins should extend this class to provide logic to determine which users are interested in receiving notifications,
028     * along with which delivery channels they selected.
029     * </p>
030     * For example:
031     * <ul>
032     * <li>notify me by email when someone comments an issue reported by me</li>
033     * <li>notify me by twitter when someone comments an issue assigned to me</li>
034     * <li>notify me by Jabber when someone mentions me in an issue comment</li>
035     * <li>send me by SMS when there are system notifications (like password reset, account creation, ...)</li>
036     * </ul> 
037     * 
038     * @since 2.10
039     */
040    public abstract class NotificationDispatcher implements ServerExtension {
041    
042      private String notificationType;
043    
044      /**
045       * Additional information related to the notification, which will be used
046       * to know who should receive the notification.
047       */
048      public interface Context {
049        /**
050         * This method is not used any longer. Calling it will result in an {@link UnsupportedOperationException}.
051         * 
052         * @deprecated Use {@link #addUser(String, NotificationChannel)} instead.
053         */
054        @Deprecated
055        void addUser(String userLogin);
056    
057        /**
058         * Adds a user that will be notified through the given notification channel.
059         * 
060         * @param userLogin the user login
061         * @param notificationChannel the notification channel to use for this user
062         */
063        void addUser(String userLogin, NotificationChannel notificationChannel);
064      }
065    
066      /**
067       * Creates a new dispatcher for notifications of the given type.
068       * 
069       * @param notificationType the type of notifications handled by this dispatcher
070       */
071      public NotificationDispatcher(String notificationType) {
072        this.notificationType = notificationType;
073      }
074    
075      /**
076       * Creates a new generic dispatcher, used for any kind of notification. 
077       * <p/>
078       * Should be avoided and replaced by the other constructor - as it is easier to understand that a
079       * dispatcher listens for a specific type of notification.
080       */
081      public NotificationDispatcher() {
082        this("");
083      }
084    
085      /**
086       * The unique key of this dispatcher. By default it's the class name without the package prefix.
087       * <p/>
088       * The related label in l10n bundles is 'notification.dispatcher.<key>', for example 'notification.dispatcher.NewFalsePositive'.
089       */
090      public String getKey() {
091        return getClass().getSimpleName();
092      }
093    
094      /**
095       * <p>
096       * Performs the dispatch.
097       * </p>
098       */
099      public final void performDispatch(Notification notification, Context context) {
100        if (StringUtils.equals(notification.getType(), notificationType) || StringUtils.equals("", notificationType)) {
101          dispatch(notification, context);
102        }
103      }
104    
105      /**
106       * <p>
107       * Implements the logic that defines which users will receive the notification.
108       * </p>
109       * 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.
110       */
111      public abstract void dispatch(Notification notification, Context context);
112    
113      @Override
114      public String toString() {
115        return getKey();
116      }
117    
118    }