1 /**
2 * Copyright 2005-2016 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.kcb.deliverer;
17
18 import java.util.HashMap;
19 import java.util.LinkedHashMap;
20
21 import org.kuali.rice.kcb.bo.MessageDelivery;
22 import org.kuali.rice.kcb.exception.ErrorList;
23 import org.kuali.rice.kcb.api.exception.MessageDeliveryException;
24 import org.kuali.rice.kcb.api.exception.MessageDismissalException;
25
26
27 /**
28 * This class represents the different types of Notification Delivery Types that the system can handle.
29 * For example, an instance of delivery type could be "ActionList" or "Email" or "SMS". Any deliverer implementation
30 * adhering to this interface can be plugged into the system and will be automatically available for use.
31 * @author Kuali Rice Team (rice.collab@kuali.org)
32 */
33 public interface MessageDeliverer {
34 /**
35 * This method is responsible for returning a list of preference key names along with their corresponding labels that get
36 * rendered in the UI. For example, if you were creating a NotificationEmailDeliverer class, one of the key preferences
37 * that this method would return back would be "email_address" and the label would be "Email Address".
38 * @return LinkedHashMap
39 */
40 public LinkedHashMap<String, String> getPreferenceKeys();
41
42 /**
43 * This method is responsible for validating preference values when a person saves their preferences for the particular
44 * NotificationMessageDeliverer. For example, if "phoneNumber" is one of the preferences for an SMS deliverer,
45 * then this method would be responsible for validating the value entered by a particular user such that it was properly
46 * constructed with hyphens or not, etc. Errors would be constructed and added to the ErrorList instance and be thrown from
47 * the method if any occurred.
48 * @throws ErrorList
49 */
50 public void validatePreferenceValues(HashMap<String, String> prefs) throws ErrorList;
51
52 /**
53 * This method returns the human readable name of the plugin. This name is the
54 * key for this message delivery type. It must be unique and not contain
55 * any spaces.
56 * @return String
57 */
58 public String getName();
59
60 /**
61 * This method returns the human readable Title of the plugin. This name is the
62 * string used for identifying the plugin in the UI. It may contain
63 * spaces characters.
64 * @return String
65 */
66 public String getTitle();
67
68 /**
69 * This method returns the human readable description for this plugin.
70 * @return String
71 */
72 public String getDescription();
73
74 /**
75 * This method is responsible for delivering the passed in messageDelivery record.
76 * @param messageDelivery The messageDelivery to process
77 * @throws MessageDeliveryException
78 */
79 public void deliver(MessageDelivery messageDelivery) throws MessageDeliveryException;
80
81 /**
82 * This method handles auto removing a message delivery from a person's list of notifications.
83 * @param messageDelivery The messageDelivery to auto remove
84 * @throws NotificationAutoRemoveException
85 */
86 //public void autoRemoveMessageDelivery(MessageDelivery messageDelivery) /*throws NotificationAutoRemoveException*/;
87
88 /**
89 * This method dismisses/removes the NotificationMessageDelivery so that it is no longer being presented to the user
90 * via this deliverer. Note, whether this action is meaningful is dependent on the deliverer implementation. If the
91 * deliverer cannot control the presentation of the message, then this method need not do anything.
92 * @param messageDelivery the messageDelivery to dismiss
93 * @param the user that caused the dismissal; in the case of end-user actions, this will most likely be the user to
94 * which the message was delivered (user recipient in the NotificationMessageDelivery object)
95 * @param cause the reason the message was dismissed
96 */
97 public void dismiss(MessageDelivery messageDelivery, String user, String cause) throws MessageDismissalException;
98 }