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