001/**
002 * Copyright 2005-2016 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 java.util.Collection;
019
020import org.kuali.rice.ken.bo.NotificationBo;
021import org.kuali.rice.ken.bo.NotificationMessageDelivery;
022
023/**
024 * The NotificationMessageDeliveryService class is responsible various functions regarding the 
025 * NotificationMessageDelivery records that exist within the system.
026 * @author Kuali Rice Team (rice.collab@kuali.org)
027 */
028public interface NotificationMessageDeliveryService {
029    /**
030     * This method will retrieve a NotificationMessageDelivery object from the system, given the id of the 
031     * actual record.
032     * @param id
033     * @return NotificationMessageDelivery
034     */
035    public NotificationMessageDelivery getNotificationMessageDelivery(Long id);
036
037    /**
038     * This method will retrieve a NotificationMessageDelivery object from the system, given the external deliverer system id
039     * registered with the NotificationMessageDelivery.
040     * @param id the external deliverer system id
041     * @return NotificationMessageDelivery
042     */
043    public NotificationMessageDelivery getNotificationMessageDeliveryByDelivererId(String id);
044
045    /**
046     * This method will return all NotificationMessageDelivery objects in the system 
047     * actual record.
048     * @return List<NotificationMessageDelivery> list of NotificationMessageDelivery objects in the system
049     */
050    public Collection<NotificationMessageDelivery> getNotificationMessageDeliveries();
051    
052    /**
053     * This method will return all NotificationMessageDelievery objects generated for the given Notification for the given user
054     * @param notification the notification which generated the message deliveries
055     * @param userRecipientId the id of the user whose message deliveries to obtain
056     * @return collection of NotificationMessageDelivery objects generated for the given Notification for the given user
057     */
058    public Collection<NotificationMessageDelivery> getNotificationMessageDeliveries(NotificationBo notification, String userRecipientId);
059    
060    /**
061     * This method is responsible for atomically finding all untaken, undelivered message deliveries, marking them as taken
062     * and returning them to the caller for processing.
063     * NOTE: it is important that this method execute in a SEPARATE dedicated transaction; either the caller should
064     * NOT be wrapped by Spring declarative transaction and this service should be wrapped (which is the case), or
065     * the caller should arrange to invoke this from within a newly created transaction).
066     * @return a list of available message deliveries that have been marked as taken by the caller
067     */
068    public Collection<NotificationMessageDelivery> takeMessageDeliveriesForDispatch();
069    
070    /**
071     * This method is responsible for atomically finding all untaken message deliveries that are ready to be autoremoved,
072     * marking them as taken and returning them to the caller for processing.
073     * NOTE: it is important that this method execute in a SEPARATE dedicated transaction; either the caller should
074     * NOT be wrapped by Spring declarative transaction and this service should be wrapped (which is the case), or
075     * the caller should arrange to invoke this from within a newly created transaction).
076     * @return a list of notifications to be autoremoved that have been marked as taken by the caller
077     */
078    public Collection<NotificationMessageDelivery> takeMessageDeliveriesForAutoRemoval();
079    
080    /**
081     * Unlocks the specified messageDelivery object
082     * @param messageDelivery the message delivery to unlock
083     */
084    public void unlockMessageDelivery(NotificationMessageDelivery messageDelivery);
085}