001/**
002 * Copyright 2005-2015 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.ken.service;
017
018import org.kuali.rice.core.api.util.xml.XmlException;
019import org.kuali.rice.ken.bo.NotificationBo;
020import org.kuali.rice.ken.bo.NotificationResponseBo;
021
022import java.io.IOException;
023import java.util.Collection;
024
025/**
026 * The NotificationService class is responsible for processing notification messages 
027 * that come into the system.  It also is able to retrieve notifications that have 
028 * already been entered/processed by the system.
029 * 
030 * @author Kuali Rice Team (rice.collab@kuali.org)
031 */
032public interface NotificationService {
033    /**
034     * This method allows consumers to send notification messages.  This particular service 
035     * accepts the XML format of the notification and then marshals it out into the actual 
036     * business object construct, for further processing.  The response is also sent back as 
037     * a String of XML.
038     * @param notificationMessageAsXml
039     * @return NotificationResponse response object
040     */
041    public NotificationResponseBo sendNotification(String notificationMessageAsXml) throws IOException, XmlException;
042    
043    /**
044     * This method allows consumers to send notification messages.  This particular service 
045     * accepts the actual business object.
046     * @param notification
047     * @return NotificationResponse
048     */
049    public NotificationResponseBo sendNotification(NotificationBo notification);
050    
051    /**
052     * This method will retrieve a Notification object from the system, given the id of the 
053     * actual notification record.
054     * @param id
055     * @return Notification
056     */
057    public NotificationBo getNotification(Long id);
058    
059    /**
060     * This method will retrieve a collection of notifications given a contentTypeName and recipientId.
061     * @param contentTypeName the name of the content type
062     * @param recipientId the recipient id
063     * @return Collection of notifications
064     */
065    public Collection<NotificationBo> getNotificationsForRecipientByType(String contentTypeName, String recipientId);
066    
067    /**
068     * This method will "dismiss"/remove a NotificationMessageDelivery with the specified cause.
069     * @param id the id of the NotificationMessageDelivery that was acted upon
070     * @param user the user or entity that performed the dismissal
071     * @param cause the cause of the dismissal (e.g. an end user action or auto-removal by the system)
072     */
073    public void dismissNotificationMessageDelivery(Long id, String user, String cause);
074    
075    
076    /**
077     * This method is responsible for atomically finding all untaken, unresolved notifications that are ready to be sent,
078     * marking them as taken and returning them to the caller for processing.
079     * NOTE: it is important that this method execute in a SEPARATE dedicated transaction; either the caller should
080     * NOT be wrapped by Spring declarative transaction and this service should be wrapped (which is the case), or
081     * the caller should arrange to invoke this from within a newly created transaction).
082     * @return a list of notifications to be resolved that have been marked as taken by the caller
083     */
084    public Collection<NotificationBo> takeNotificationsForResolution();
085    
086    /**
087     * Unlocks specified notification
088     * @param notification the notification object to unlock
089     */
090    public void unlockNotification(NotificationBo notification);
091}