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