1 /**
2 * Copyright 2005-2012 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.ken.service;
17
18 import org.kuali.rice.core.api.util.xml.XmlException;
19 import org.kuali.rice.ken.bo.NotificationBo;
20 import org.kuali.rice.ken.bo.NotificationResponseBo;
21
22 import java.io.IOException;
23 import java.util.Collection;
24
25 /**
26 * The NotificationService class is responsible for processing notification messages
27 * that come into the system. It also is able to retrieve notifications that have
28 * already been entered/processed by the system.
29 *
30 * @author Kuali Rice Team (rice.collab@kuali.org)
31 */
32 public interface NotificationService {
33 /**
34 * This method allows consumers to send notification messages. This particular service
35 * accepts the XML format of the notification and then marshals it out into the actual
36 * business object construct, for further processing. The response is also sent back as
37 * a String of XML.
38 * @param notificationMessageAsXml
39 * @return NotificationResponse response object
40 */
41 public NotificationResponseBo sendNotification(String notificationMessageAsXml) throws IOException, XmlException;
42
43 /**
44 * This method allows consumers to send notification messages. This particular service
45 * accepts the actual business object.
46 * @param notification
47 * @return NotificationResponse
48 */
49 public NotificationResponseBo sendNotification(NotificationBo notification);
50
51 /**
52 * This method will retrieve a Notification object from the system, given the id of the
53 * actual notification record.
54 * @param id
55 * @return Notification
56 */
57 public NotificationBo getNotification(Long id);
58
59 /**
60 * This method will retrieve a collection of notifications given a contentTypeName and recipientId.
61 * @param contentTypeName the name of the content type
62 * @param recipientId the recipient id
63 * @return Collection of notifications
64 */
65 public Collection<NotificationBo> getNotificationsForRecipientByType(String contentTypeName, String recipientId);
66
67 /**
68 * This method will "dismiss"/remove a NotificationMessageDelivery with the specified cause.
69 * @param id the id of the NotificationMessageDelivery that was acted upon
70 * @param user the user or entity that performed the dismissal
71 * @param cause the cause of the dismissal (e.g. an end user action or auto-removal by the system)
72 */
73 public void dismissNotificationMessageDelivery(Long id, String user, String cause);
74
75
76 /**
77 * This method is responsible for atomically finding all untaken, unresolved notifications that are ready to be sent,
78 * marking them as taken and returning them to the caller for processing.
79 * NOTE: it is important that this method execute in a SEPARATE dedicated transaction; either the caller should
80 * NOT be wrapped by Spring declarative transaction and this service should be wrapped (which is the case), or
81 * the caller should arrange to invoke this from within a newly created transaction).
82 * @return a list of notifications to be resolved that have been marked as taken by the caller
83 */
84 public Collection<NotificationBo> takeNotificationsForResolution();
85
86 /**
87 * Unlocks specified notification
88 * @param notification the notification object to unlock
89 */
90 public void unlockNotification(NotificationBo notification);
91 }