001/**
002 * Copyright 2005-2017 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.rice.kcb.deliverer;
017
018import java.util.HashMap;
019import java.util.LinkedHashMap;
020
021import org.kuali.rice.kcb.bo.MessageDelivery;
022import org.kuali.rice.kcb.exception.ErrorList;
023import org.kuali.rice.kcb.api.exception.MessageDeliveryException;
024import org.kuali.rice.kcb.api.exception.MessageDismissalException;
025
026
027/**
028 * This class represents the different types of Notification Delivery Types that the system can handle.  
029 * For example, an instance of delivery type could be "ActionList" or "Email" or "SMS".  Any deliverer implementation 
030 * adhering to this interface can be plugged into the system and will be automatically available for use.
031 * @author Kuali Rice Team (rice.collab@kuali.org)
032 */
033public interface MessageDeliverer {
034    /**
035     * This method is responsible for returning a list of preference key names along with their corresponding labels that get 
036     * rendered in the UI.  For example, if you were creating a NotificationEmailDeliverer class, one of the key preferences 
037     * that this method would return back would be "email_address" and the label would be "Email Address".
038     * @return LinkedHashMap
039     */
040    public LinkedHashMap<String, String> getPreferenceKeys();
041    
042    /**
043     * This method is responsible for validating preference values when a person saves their preferences for the particular
044     * NotificationMessageDeliverer.  For example, if "phoneNumber" is one of the preferences for an SMS deliverer, 
045     * then this method would be responsible for validating the value entered by a particular user such that it was properly 
046     * constructed with hyphens or not, etc.  Errors would be constructed and added to the ErrorList instance and be thrown from 
047     * the method if any occurred.
048     * @throws ErrorList
049     */
050    public void validatePreferenceValues(HashMap<String, String> prefs) throws ErrorList;
051    
052    /**
053     * This method returns the human readable name of the plugin.  This name is the 
054     * key for this message delivery type. It must be unique and not contain
055     * any spaces.
056     * @return String
057     */
058    public String getName();
059    
060    /**
061     * This method returns the human readable Title of the plugin.  This name is the 
062     * string used for identifying the plugin in the UI. It may contain
063     * spaces characters.
064     * @return String
065     */
066    public String getTitle();
067    
068    /**
069     * This method returns the human readable description for this plugin.
070     * @return String
071     */
072    public String getDescription();
073    
074    /**
075     * This method is responsible for delivering the passed in messageDelivery record.
076     * @param messageDelivery The messageDelivery to process
077     * @throws MessageDeliveryException
078     */
079    public void deliver(MessageDelivery messageDelivery) throws MessageDeliveryException;
080    
081    /**
082     * This method handles auto removing a message delivery from a person's list of notifications.
083     * @param messageDelivery The messageDelivery to auto remove
084     * @throws NotificationAutoRemoveException
085     */
086    //public void autoRemoveMessageDelivery(MessageDelivery messageDelivery) /*throws NotificationAutoRemoveException*/;
087    
088    /**
089     * This method dismisses/removes the NotificationMessageDelivery so that it is no longer being presented to the user
090     * via this deliverer.  Note, whether this action is meaningful is dependent on the deliverer implementation.  If the
091     * deliverer cannot control the presentation of the message, then this method need not do anything. 
092     * @param messageDelivery the messageDelivery to dismiss
093     * @param the user that caused the dismissal; in the case of end-user actions, this will most likely be the user to
094     *        which the message was delivered (user recipient in the NotificationMessageDelivery object)
095     * @param cause the reason the message was dismissed
096     */
097    public void dismiss(MessageDelivery messageDelivery, String user, String cause) throws MessageDismissalException;
098}