001 /**
002 * Copyright 2005-2012 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 */
016 package org.kuali.rice.ken.service;
017
018 import org.kuali.rice.core.api.util.xml.XmlException;
019 import org.kuali.rice.ken.bo.Notification;
020 import org.kuali.rice.ken.bo.NotificationResponse;
021
022 import java.io.IOException;
023 import 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 */
032 public 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 NotificationResponse 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 NotificationResponse sendNotification(Notification 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 Notification 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<Notification> 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<Notification> takeNotificationsForResolution();
085
086 /**
087 * Unlocks specified notification
088 * @param notification the notification object to unlock
089 */
090 public void unlockNotification(Notification notification);
091 }