001/*
002 * (C) Copyright 2007 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Nuxeo - initial API and implementation
016 *
017 * $Id: EJBPlacefulService.java 13110 2007-03-01 17:25:47Z rspivak $
018 */
019package org.nuxeo.ecm.platform.notification.api;
020
021import java.util.List;
022import java.util.Map;
023import java.util.Set;
024
025import org.nuxeo.ecm.core.api.DocumentModel;
026import org.nuxeo.ecm.core.api.NuxeoPrincipal;
027
028/**
029 * @author <a href="mailto:npaslaru@nuxeo.com">Narcis Paslaru</a>
030 */
031public interface NotificationManager {
032
033    /**
034     * Gets the users that subscribed to a notification on a certain document.
035     *
036     * @deprecated since 7.3 use {@link #getSubscribers(String, DocumentModel)}
037     */
038    @Deprecated
039    List<String> getSubscribers(String notification, String docId);
040
041    /**
042     * Gets the users that subscribed to a notification on a certain document.
043     */
044    List<String> getSubscribers(String notification, DocumentModel doc);
045
046    /**
047     * Gets the notifications for which a user subscribed for a certain document.
048     *
049     * @deprecated since 7.3 use {@link #getSubscriptionsForUserOnDocument(String, DocumentModel)}
050     */
051    @Deprecated
052    List<String> getSubscriptionsForUserOnDocument(String username, String docId);
053
054    /**
055     * Gets the notifications for which a user subscribed for a certain document.
056     */
057    List<String> getSubscriptionsForUserOnDocument(String username, DocumentModel doc);
058
059    /**
060     * @deprecated since 7.3 use {@link #getUsersSubscribedToNotificationOnDocument(String, DocumentModel)}
061     */
062    @Deprecated
063    List<String> getUsersSubscribedToNotificationOnDocument(String notification, String docId);
064
065    /**
066     * Gets all users and groups that subscribed to a notification on a document This is used in management of
067     * subscritptions.
068     */
069    List<String> getUsersSubscribedToNotificationOnDocument(String notification, DocumentModel doc);
070
071    /**
072     * Called when a user subscribes to a notification.
073     */
074    void addSubscription(String username, String notification, DocumentModel doc, Boolean sendConfirmationEmail,
075            NuxeoPrincipal principal, String notificationName);
076
077    /**
078     * @since 5.6 Called when a user subscribes to all notifications.
079     */
080    void addSubscriptions(String username, DocumentModel doc, Boolean sendConfirmationEmail, NuxeoPrincipal principal);
081
082    /**
083     * @since 5.6 Called when a user unsubscribes to all notifications.
084     * @deprecated since 7.3 use {@link #removeSubscriptions(String, List, DocumentModel)}
085     */
086    void removeSubscriptions(String username, List<String> notifications, String docId);
087
088    /**
089     * @since 5.6 Called when a user unsubscribes to all notifications.
090     */
091    void removeSubscriptions(String username, List<String> notifications, DocumentModel doc);
092
093    /**
094     * Called when a user cancels his notification.
095     *
096     * @deprecated since 7.3 use {@link #removeSubscription(String, String, DocumentModel)}
097     */
098    void removeSubscription(String username, String notification, String docId);
099
100    /**
101     * Called when a user cancels his notification.
102     */
103    void removeSubscription(String username, String notification, DocumentModel doc);
104
105    /**
106     * Returns the notification manager.
107     *
108     * @deprecated should never have to return the registry : use delegation
109     */
110    @Deprecated
111    NotificationRegistry getNotificationRegistry();
112
113    /**
114     * Returns a notification with all data loaded (label, etc).
115     */
116    Notification getNotificationByName(String selectedNotification);
117
118    /**
119     * Directly sends a notification to the principal, using the data provided in the map
120     * <p>
121     * The map should contain at least the userName of the user calling the method stored under the key "author".
122     * <p>
123     * infoMap should also contain all the variables that should be used to make-up the body of the notifications
124     * message.
125     *
126     * @param notificationName name of notification
127     * @param infoMap data used to compose the notification body
128     * @param userPrincipal recipient used to get the adress(es) to send emails
129     */
130    void sendNotification(String notificationName, Map<String, Object> infoMap, String userPrincipal);
131
132    /**
133     * Sends an e-mail directly.
134     */
135    void sendDocumentByMail(DocumentModel doc, String freemarkerTemplateName, String subject, String comment,
136            NuxeoPrincipal sender, List<String> sendTo);
137
138    List<Notification> getNotificationsForSubscriptions(String parentType);
139
140    List<Notification> getNotificationsForEvents(String eventId);
141
142    /**
143     * Gets the list of event names used by notifications.
144     *
145     * @since 5.4.2
146     */
147    Set<String> getNotificationEventNames();
148
149    /**
150     * Returns the list of live docs the user is subscribed to.
151     * @param prefixedPrincipalName
152     * @return
153     * @since 7.3
154     */
155    List<DocumentModel> getSubscribedDocuments(String prefixedPrincipalName);
156
157}