001/*
002 *  Copyright 2017 Anyware Services
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 */
016package org.ametys.plugins.messagingconnector;
017
018import java.time.ZonedDateTime;
019import java.util.Date;
020import java.util.List;
021import java.util.Map;
022import java.util.Set;
023
024import org.apache.avalon.framework.component.Component;
025
026import org.ametys.core.user.UserIdentity;
027import org.ametys.core.userpref.UserPreferencesException;
028
029/**
030 * This interface describe the methods used by the different mail servers.
031 *
032 */
033public interface MessagingConnector extends Component
034{
035    /** The avalon role */
036    public static final String ROLE = MessagingConnector.class.getName();
037
038    /**
039     * Get the list of population id allowed to the messaging connector
040     * @return the list of population id allowed to the messaging connector
041     */
042    public List<String> getAllowedPopulationIds();
043    
044    /**
045     * Get the list of upcoming events from now for a given user
046     * @param userIdentity the owner of the events
047     * @param maxDays The maximum number of days to search for from now 
048     * @param maxEvents the maximum number of events to retrieve
049     * @return the next events
050     * @throws MessagingConnectorException if failed to get events
051     */
052    public List<CalendarEvent> getEvents(UserIdentity userIdentity, int maxDays, int maxEvents) throws MessagingConnectorException;
053
054    /**
055     * Return the number of upcoming events
056     * @param userIdentity the owner of the events
057     * @param maxDays The maximum number of days to search for from now 
058     * @return the number of upcoming events
059     * @throws MessagingConnectorException if failed to get events' count
060     */
061    public int getEventsCount(UserIdentity userIdentity, int maxDays) throws MessagingConnectorException;
062
063    /**
064     * Return the unread emails for a given user
065     * 
066     * @param userIdentity the recipient of the mails
067     * @param maxEmails The max number of emails to return
068     * @return a mail messsages
069     * @throws MessagingConnectorException if failed to get mails
070     */
071    public List<EmailMessage> getUnreadEmails(UserIdentity userIdentity, int maxEmails) throws MessagingConnectorException;
072
073    /**
074     * Return the number of unread mails for a given user
075     * @param userIdentity the receiver of the mails
076     * @return the number of unread mails
077     * @throws MessagingConnectorException if failed to get unread mails ' count
078     */
079    public int getUnreadEmailCount(UserIdentity userIdentity) throws MessagingConnectorException;
080    
081    /**
082     * Tell if the messaging connector supports event invitation
083     * @return true if the messaging connector supports event invitation
084     * @throws MessagingConnectorException if failed to get events from server
085     */
086    public abstract boolean supportInvitation() throws MessagingConnectorException;
087    
088    /**
089     * True if the event exist in the messaging connector
090     * @param eventId the event id
091     * @param organiser the organiser
092     * @return true if the event exist
093     * @throws MessagingConnectorException if an error occurred
094     */
095    public abstract boolean isEventExist(String eventId, UserIdentity organiser) throws MessagingConnectorException;
096    
097    /**
098     * Create an event
099     * @param title the event title
100     * @param description the event description
101     * @param place the event place
102     * @param isAllDay if the event is all day
103     * @param startDate the event start date
104     * @param endDate the event end date
105     * @param recurrenceType recurrence type
106     * @param untilDate until date of the recurring event
107     * @param attendees the map of attendees (email -&gt; optional or requested) to set
108     * @param organiser the event organiser
109     * @return the id of the event created
110     * @throws MessagingConnectorException if failed to get events from server
111     */
112    public abstract String createEvent(String title, String description, String place, boolean isAllDay, ZonedDateTime startDate, ZonedDateTime endDate, EventRecurrenceTypeEnum recurrenceType, ZonedDateTime untilDate, Map<String, Boolean> attendees, UserIdentity organiser) throws MessagingConnectorException;
113    
114    /**
115     * Update an event
116     * @param eventId the event id to delete
117     * @param title the event title
118     * @param description the event description
119     * @param place the event place
120     * @param isAllDay if the event is all day
121     * @param startDate the event start date
122     * @param endDate the event end date
123     * @param recurrenceType recurrence type
124     * @param untilDate until date of the recurring event
125     * @param attendees the map of attendees (email -&gt; optional or requested) to set
126     * @param organiser the event organiser
127     * @throws MessagingConnectorException if failed to get events from server
128     */
129    public abstract void updateEvent(String eventId, String title, String description, String place, boolean isAllDay, ZonedDateTime startDate, ZonedDateTime endDate, EventRecurrenceTypeEnum recurrenceType, ZonedDateTime untilDate, Map<String, Boolean> attendees, UserIdentity organiser) throws MessagingConnectorException;
130    
131    /**
132     * Delete an event
133     * @param eventId the event id to delete
134     * @param organiser the event organiser
135     * @throws MessagingConnectorException if failed to get events from server
136     */
137    public abstract void deleteEvent(String eventId, UserIdentity organiser) throws MessagingConnectorException;
138    
139    /**
140     * Get the map of attendees for an event
141     * @param eventId the event id
142     * @param organiser the event organiser
143     * @return the map of attendees (email -&gt; attendee information)
144     * @throws MessagingConnectorException if failed to get events from server
145     */
146    public abstract Map<String, AttendeeInformation> getAttendees(String eventId, UserIdentity organiser) throws MessagingConnectorException;
147    
148    /**
149     * Set attendees for an event
150     * @param eventId the event id
151     * @param attendees the map of attendees (email -&gt; optional or requested) to set
152     * @param organiser the event organiser
153     * @throws MessagingConnectorException if failed to get events from server
154     */
155    public abstract void setAttendees(String eventId, Map<String, Boolean> attendees, UserIdentity organiser) throws MessagingConnectorException;
156    
157    /**
158     * Get free/busy status for attendees for a time window
159     * @param startDate the start date
160     * @param endDate the end date
161     * @param isAllDay true if is an allday event
162     * @param attendees the list of attendees email
163     * @param organiser the event organiser
164     * @return the map of attendees (email -&gt; freeBusy status)
165     * @throws MessagingConnectorException if failed to get events from server
166     */
167    public abstract Map<String, FreeBusyStatus> getFreeBusy(Date startDate, Date endDate, boolean isAllDay, Set<String> attendees, UserIdentity organiser) throws MessagingConnectorException;
168    
169    /**
170     * True if the user exist
171     * @param userIdentity the user identity
172     * @return true if the user exist
173     * @throws MessagingConnectorException if failed to get events from server
174     */
175    public abstract boolean isUserExist(UserIdentity userIdentity) throws MessagingConnectorException;
176    
177    /**
178     * Check if the service needs user credential (some implementation can use a central API key or impersonation, some don't)
179     * @param userIdentity The useridentity involved in the demand
180     * @return True if the service is configured to ask for user credential
181     */
182    public abstract boolean userCredentialNeeded(UserIdentity userIdentity);
183    
184    /**
185     * Check if a user credential should be saved
186     * @param userIdentity The useridentity involved in the demand
187     * @return true if this implementation supports user credential (and is configured to use them)
188     */
189    public abstract boolean supportUserCredential(UserIdentity userIdentity);
190
191    /**
192     * Set a new password for the user
193     * @param userIdentity user that have a password change
194     * @param password new password
195     * @throws UserPreferencesException An exception occured while saving the password
196     * @throws MessagingConnectorException Thrown when the messaging connector does not support user credentials
197     */
198    public void setUserPassword(UserIdentity userIdentity, String password) throws UserPreferencesException, MessagingConnectorException;
199    
200    /**
201     * Enum for free/busy status
202     *
203     */
204    public enum FreeBusyStatus
205    {
206        /**
207         * The attendee is busy
208         */
209        Busy,
210        /**
211         * The attendee is free
212         */
213        Free,
214        /**
215         * We don't know if the attendee is busy or free
216         */
217        Unknown;
218    }
219    
220    /**
221     * Enum for answer status
222     *
223     */
224    public enum ResponseType
225    {
226        /**
227         * The attendee accepts the invitation
228         */
229        Accept,
230        /**
231         * The attendee declines the invitation
232         */
233        Decline,
234        /**
235         * The attendee says maybe to the event
236         */
237        Maybe,
238        /**
239         * We don't know the answer of the attendee
240         */
241        Unknown;
242    }
243    
244    /**
245     * Internal class for attendee information
246     *
247     */
248    public class AttendeeInformation
249    {
250        private boolean _mandatory;
251        private ResponseType _responseType;
252        
253        /**
254         * Constructor for an attendee information
255         * @param mandatory mandatory
256         * @param responseType the answer type
257         */
258        public AttendeeInformation (boolean mandatory, ResponseType responseType)
259        {
260            _mandatory = mandatory;
261            _responseType = responseType;
262        }
263        
264        /**
265         * True if the attendee is mandatory
266         * @return true if the attendee is mandatory
267         */
268        public boolean isMandatory ()
269        {
270            return _mandatory;
271        }
272        
273        /**
274         * Get the response type
275         * @return the response type
276         */
277        public ResponseType getResponseType ()
278        {
279            return _responseType;
280        }
281    }
282}