001    /**
002     * Copyright 2005-2011 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    import org.xml.sax.SAXException;
022    
023    import javax.xml.parsers.ParserConfigurationException;
024    import java.io.IOException;
025    import java.io.InputStream;
026    
027    /**
028     * Notification Message Content service - handles parsing the notification XML message and also marshalling out BOs for the response.
029     * @see <a href="http://wiki.library.cornell.edu/wiki/display/notsys/Hi-Level+Service+Interface+Definitions#Hi-LevelServiceInterfaceDefinitions-NotificationMessageContentService">NotificationMessageContentService</a>
030     * @author Kuali Rice Team (rice.collab@kuali.org)
031     */
032    public interface NotificationMessageContentService {
033        /**
034         * Parses a Notification request message into business objects.  Performs syntactic and semantic validation.  
035         * This method takes an InputStream.
036         * @param stream request message stream
037         * @return Notification business object
038         * @throws SAXException
039         * @throws ParserConfigurationException
040         * @throws IOException
041         * @throws XmlException
042         */
043        public Notification parseNotificationRequestMessage(InputStream stream) throws IOException, XmlException;
044        
045        /**
046         * Parses a Notification request message into business objects.  Performs syntactic and semantic validation.  
047         * This method takes a String of XML.
048         * @param notificationMessageAsXml
049         * @return
050         * @throws IOException
051         * @throws XmlException
052         */
053        public Notification parseNotificationRequestMessage(String notificationMessageAsXml) throws IOException, XmlException;
054        
055        /**
056         * Generates a Notification response message
057         * @param response
058         * @return String XML representation of a Notification response object
059         */
060        public String generateNotificationResponseMessage(NotificationResponse response);
061    
062        /**
063         * This method is responsible for marshalling out the passed in Notification object in and XML representation. 
064         * @param notification
065         * @return String of XML.
066         */
067        public String generateNotificationMessage(Notification notification);
068        
069        /**
070         * This method is responsible for marshalling out the passed in Notification object in and XML representation, with 
071         * the addition of adding the specific recipient to the recipients list and removing the others. 
072         * @param notification
073         * @param userRecipientId
074         * @return String of XML.
075         */
076        public String generateNotificationMessage(Notification notification, String userRecipientId);
077        
078        /**
079         * This method parses out the serialized XML version of Notification BO and populates a Notification BO with it.
080         * @param xmlAsBytes
081         * @return Notification
082         * @throws Exception
083         */
084        public Notification parseSerializedNotificationXml(byte[] xmlAsBytes) throws Exception;
085    }