# InfoLetterService.java

    /*
     * Copyright (C) 2000 - 2024 Silverpeas
     *
     * This program is free software: you can redistribute it and/or modify
     * it under the terms of the GNU Affero General Public License as
     * published by the Free Software Foundation, either version 3 of the
     * License, or (at your option) any later version.
     *
     * As a special exception to the terms and conditions of version 3.0 of
     * the GPL, you may redistribute this Program in connection with Free/Libre
     * Open Source Software ("FLOSS") applications as described in Silverpeas's
     * FLOSS exception. You should have received a copy of the text describing
     * the FLOSS exception, and it is also available here:
     * "https://www.silverpeas.org/legal/floss_exception.html"
     *
     * This program is distributed in the hope that it will be useful,
     * but WITHOUT ANY WARRANTY; without even the implied warranty of
     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
     * GNU Affero General Public License for more details.
     *
     * You should have received a copy of the GNU Affero General Public License
     * along with this program. If not, see <https://www.gnu.org/licenses/>.
     */
    package org.silverpeas.components.infoletter.model;

    import org.silverpeas.core.ApplicationService;
    import org.silverpeas.core.WAPrimaryKey;
    import org.silverpeas.core.admin.user.model.Group;
    import org.silverpeas.core.admin.user.model.UserDetail;
    import org.silverpeas.core.subscription.util.SubscriptionSubscriberList;
    import org.silverpeas.core.util.ServiceProvider;

    import java.util.List;
    import java.util.Set;

    /**
     * Contract to access info letter data
     * @author
     */
    public interface InfoLetterService extends ApplicationService {

      static InfoLetterService get() {
        return ServiceProvider.getService(InfoLetterService.class);
      }

      /**
       * Create information letter
       * @param il the information letter to create
       */
      void createInfoLetter(InfoLetter il);

      /**
       * Update information letter
       * @param il the information letter to update
       */
      void updateInfoLetter(InfoLetter il);

      /**
       * Retrieve information letters
       * @param applicationId the application identifier
       * @return the information letters of the current application identifier given in parameter
       */
      List<InfoLetter> getInfoLetters(String applicationId);

      /**
       * Retrieve information letter publications
       * @param letterPK the information letter primary key
       * @return the list of information letter publications of an information letter
       */
      List<InfoLetterPublication> getInfoLetterPublications(WAPrimaryKey letterPK);

      /**
       * Create information letter publication
       * @param ilp the information letter publication pdc to create
       * @param userId the creator user identifier
       */
      void createInfoLetterPublication(InfoLetterPublicationPdC ilp, String userId);

      /**
       * Delete information letter publication
       * @param pk the information letter publication primary key
       * @param componentId the component identifier
       */
      void deleteInfoLetterPublication(WAPrimaryKey pk, String componentId);

      /**
       * Update information letter publication
       * @param ilp the information letter publication to update
       */
      void updateInfoLetterPublication(InfoLetterPublicationPdC ilp);

      /**
       * Retrieve an information letter from his primary key
       * @param letterPK the letter primary key
       * @return the infirmation letter
       */
      InfoLetter getInfoLetter(WAPrimaryKey letterPK);

      /**
       * Retrieve information letter publication from his key
       * @param publiPK the information letter publication primary key
       * @return an Information Letter Publication PdC
       */
      InfoLetterPublicationPdC getInfoLetterPublication(WAPrimaryKey publiPK);

      /**
       * Create a default Info Letter when instanciated
       * @param componentId the component identifier
       * @return a default Info Letter
       */
      InfoLetter createDefaultLetter(String componentId);

      /**
       * Deletes all the info letters (and then all the publications and external subscribers) in the
       * specified component instance.
       * @param componentId the unique identifier of the InfoLetter instance.
       */
      void deleteAllInfoLetters(String componentId);

      /**
       * @param componentId componentId component instance id
       * @return map of subscriber ids indexed by type of subscriber
       */
      SubscriptionSubscriberList getInternalSuscribers(String componentId);

      /**
       * Update internal user subscribers list
       * @param componentId componentId component instance id
       * @param users an array of User detail
       * @param groups an array of Group
       */
      void setInternalSuscribers(String componentId, UserDetail[] users, Group[] groups);

      /**
       * Retrieve external emails address
       * @param letterPK the info letter identifier (letter primary key)
       * @return a set of external emails
       */
      Set<String> getEmailsExternalsSuscribers(WAPrimaryKey letterPK);

      /**
       * Save external subscriber emails address
       * @param letterPK the letter primary key
       * @param emails the list of external emails to save
       */
      void setEmailsExternalsSubscribers(WAPrimaryKey letterPK, Set<String> emails);

      /**
       * Toggle subscription unsubscription of a user to the news letter
       * @param userId the user identifier
       * @param componentId the info letter component instance identifier
       * @param isUserSubscribing true if user is subscribing, false else if
       */
      void toggleSuscriber(String userId, String componentId, boolean isUserSubscribing);

      /**
       * Check if use is an internal subscriber of the information letter
       * @param userId the user identifier
       * @param componentId the info letter component instance identifier
       * @return true if user is a subscriber, false else if
       */
      boolean isUserSuscribed(String userId, String componentId);

      /**
       * Initialize template
       * @param componentId the info letter component instance identifier
       * @param letterPK the info letter identifier
       * @param userId the user identifier
       */
      void initTemplate(String componentId, WAPrimaryKey letterPK, String userId);

      int getSilverObjectId(String pubId, String componentId);

      /**
       * Send letter by mail
       * @param il the template
       * @param mimeMultipart please have a look to https://en.wikipedia.org/wiki/MIME#Multipart_subtypes
       * @param listEmailDest list of email
       * @param subject subject of email
       * @param emailFrom sender of email
       * @return list of emails in error
       */
      Set<String> sendTemplateByMail(InfoLetter il, String mimeMultipart,
          Set<String> listEmailDest, String subject, String emailFrom);

      /**
       * Send letter by mail
       * @param ilp the information letter
       * @param mimeMultipart please have a look to https://en.wikipedia.org/wiki/MIME#Multipart_subtypes
       * @param listEmailDest list of email
       * @param subject subject of email
       * @param emailFrom sender of email
       * @return list of emails in error
       */
      Set<String> sendLetterByMail(InfoLetterPublicationPdC ilp, String mimeMultipart,
          Set<String> listEmailDest, String subject, String emailFrom);

      /**
       * Indexes all info letter indexable data.
       * @param componentId the identifier of the concerned component instance.
       */
      void indexInfoLetter(String componentId);
    }