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 java.util.Collection;
019    
020    import org.kuali.rice.ken.bo.NotificationBo;
021    import 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     */
028    public 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    }