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 }