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.util.Date;
019import java.util.List;
020import java.util.Map;
021import java.util.Set;
022
023import org.apache.avalon.framework.component.Component;
024
025import org.ametys.core.user.UserIdentity;
026import org.ametys.core.userpref.UserPreferencesException;
027import org.ametys.plugins.explorer.calendars.EventRecurrenceTypeEnum;
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, Date startDate, Date endDate, EventRecurrenceTypeEnum recurrenceType, Date 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, Date startDate, Date endDate, EventRecurrenceTypeEnum recurrenceType, Date 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     * @return True if the service is configured to ask for user credential
180     */
181    public abstract boolean userCredentialNeeded();
182    
183    /**
184     * Check if a user credential should be saved
185     * @return true if this implementation supports user credential (and is configured to use them)
186     */
187    public abstract boolean supportUserCredential();
188
189    /**
190     * Set a new password for the user
191     * @param userIdentity user that have a password change
192     * @param password new password
193     * @throws UserPreferencesException An exception occured while saving the password
194     * @throws MessagingConnectorException Thrown when the messaging connector does not support user credentials
195     */
196    public void setUserPassword(UserIdentity userIdentity, String password) throws UserPreferencesException, MessagingConnectorException;
197    
198    /**
199     * Enum for free/busy status
200     *
201     */
202    public enum FreeBusyStatus
203    {
204        /**
205         * The attendee is busy
206         */
207        Busy,
208        /**
209         * The attendee is free
210         */
211        Free,
212        /**
213         * We don't know if the attendee is busy or free
214         */
215        Unknown;
216    }
217    
218    /**
219     * Enum for answer status
220     *
221     */
222    public enum ResponseType
223    {
224        /**
225         * The attendee accepts the invitation
226         */
227        Accept,
228        /**
229         * The attendee declines the invitation
230         */
231        Decline,
232        /**
233         * The attendee says maybe to the event
234         */
235        Maybe,
236        /**
237         * We don't know the answer of the attendee
238         */
239        Unknown;
240    }
241    
242    /**
243     * Internal class for attendee information
244     *
245     */
246    public class AttendeeInformation
247    {
248        private boolean _mandatory;
249        private ResponseType _responseType;
250        
251        /**
252         * Constructor for an attendee information
253         * @param mandatory mandatory
254         * @param responseType the answer type
255         */
256        public AttendeeInformation (boolean mandatory, ResponseType responseType)
257        {
258            _mandatory = mandatory;
259            _responseType = responseType;
260        }
261        
262        /**
263         * True if the attendee is mandatory
264         * @return true if the attendee is mandatory
265         */
266        public boolean isMandatory ()
267        {
268            return _mandatory;
269        }
270        
271        /**
272         * Get the response type
273         * @return the response type
274         */
275        public ResponseType getResponseType ()
276        {
277            return _responseType;
278        }
279    }
280}