001/*
002 * (C) Copyright 2007-2016 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 */
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;
027import org.nuxeo.ecm.core.api.repository.RepositoryManager;
028import org.nuxeo.runtime.api.Framework;
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    List<String> getSubscribers(String notification, DocumentModel doc);
039
040    /**
041     * Gets the notifications for which a user subscribed for a certain document.
042     */
043    List<String> getSubscriptionsForUserOnDocument(String username, DocumentModel doc);
044
045    /**
046     * Gets all users and groups that subscribed to a notification on a document This is used in management of
047     * subscritptions.
048     */
049    List<String> getUsersSubscribedToNotificationOnDocument(String notification, DocumentModel doc);
050
051    /**
052     * Called when a user subscribes to a notification.
053     */
054    void addSubscription(String username, String notification, DocumentModel doc, Boolean sendConfirmationEmail,
055            NuxeoPrincipal principal, String notificationName);
056
057    /**
058     * @since 5.6 Called when a user subscribes to all notifications.
059     */
060    void addSubscriptions(String username, DocumentModel doc, Boolean sendConfirmationEmail, NuxeoPrincipal principal);
061
062    /**
063     * @since 5.6 Called when a user unsubscribes to all notifications.
064     */
065    void removeSubscriptions(String username, List<String> notifications, DocumentModel doc);
066
067    /**
068     * Called when a user cancels his notification.
069     */
070    void removeSubscription(String username, String notification, DocumentModel doc);
071
072    /**
073     * Returns a notification with all data loaded (label, etc).
074     */
075    Notification getNotificationByName(String selectedNotification);
076
077    /**
078     * Directly sends a notification to the principal, using the data provided in the map
079     * <p>
080     * The map should contain at least the userName of the user calling the method stored under the key "author".
081     * <p>
082     * infoMap should also contain all the variables that should be used to make-up the body of the notifications
083     * message.
084     *
085     * @param notificationName name of notification
086     * @param infoMap data used to compose the notification body
087     * @param userPrincipal recipient used to get the adress(es) to send emails
088     */
089    void sendNotification(String notificationName, Map<String, Object> infoMap, String userPrincipal);
090
091    /**
092     * Sends an e-mail directly.
093     */
094    void sendDocumentByMail(DocumentModel doc, String freemarkerTemplateName, String subject, String comment,
095            NuxeoPrincipal sender, List<String> sendTo);
096
097    List<Notification> getNotificationsForSubscriptions(String parentType);
098
099    List<Notification> getNotificationsForEvents(String eventId);
100
101    /**
102     * Gets the list of event names used by notifications.
103     *
104     * @since 5.4.2
105     */
106    Set<String> getNotificationEventNames();
107
108    /**
109     * Returns the list of live docs the user is subscribed to.
110     *
111     * @since 7.3
112     * @deprecated since 9.1, use {@link #getSubscribedDocuments(String, String)} instead
113     */
114    @Deprecated
115    default List<DocumentModel> getSubscribedDocuments(String prefixedPrincipalName) {
116        return getSubscribedDocuments(prefixedPrincipalName,
117                Framework.getService(RepositoryManager.class).getDefaultRepositoryName());
118    }
119
120    /**
121     * Returns the list of live docs the user is subscribed to in the given repository .
122     *
123     * @since 9.1
124     */
125    List<DocumentModel> getSubscribedDocuments(String prefixedPrincipalName, String respositoryName);
126
127}