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.ametys.core.user.UserIdentity;
024import org.ametys.plugins.explorer.calendars.EventRecurrenceTypeEnum;
025import org.apache.avalon.framework.component.Component;
026
027/**
028 * This interface describe the methods used by the different mail servers.
029 *
030 */
031public interface MessagingConnector extends Component
032{
033    /** The avalon role */
034    public static final String ROLE = MessagingConnector.class.getName();
035
036    /**
037     * Get the list of population id allowed to the messaging connector
038     * @return the list of population id allowed to the messaging connector
039     */
040    public List<String> getAllowedPopulationIds();
041    
042    /**
043     * Get the list of events betweend two dates for a given user
044     * @param userIdentity the owner of the events
045     * @param fromDate The start date of search
046     * @param untilDate The end date of search
047     * @param maxEvents the maximum number of events to retrieve
048     * @return the next events
049     * @throws MessagingConnectorException if failed to get events
050     */
051    public List<CalendarEvent> getEvents(UserIdentity userIdentity, Date fromDate, Date untilDate, int maxEvents) throws MessagingConnectorException;
052
053    /**
054     * Return the number of upcoming events
055     * @param userIdentity the owner of the events
056     * @param fromDate The start date of search
057     * @param untilDate The end date of search
058     * @return the number of upcoming events
059     * @throws MessagingConnectorException if failed to get events' count
060     */
061    public int getEventsCount(UserIdentity userIdentity, Date fromDate, Date untilDate) 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     * Enum for free/busy status
179     *
180     */
181    public enum FreeBusyStatus
182    {
183        /**
184         * The attendee is busy
185         */
186        Busy,
187        /**
188         * The attendee is free
189         */
190        Free,
191        /**
192         * We don't know if the attendee is busy or free
193         */
194        Unknown;
195    }
196    
197    /**
198     * Enum for answer status
199     *
200     */
201    public enum ResponseType
202    {
203        /**
204         * The attendee accepts the invitation
205         */
206        Accept,
207        /**
208         * The attendee declines the invitation
209         */
210        Decline,
211        /**
212         * The attendee says maybe to the event
213         */
214        Maybe,
215        /**
216         * We don't know the answer of the attendee
217         */
218        Unknown;
219    }
220    
221    /**
222     * Internal class for attendee information
223     *
224     */
225    public class AttendeeInformation
226    {
227        private boolean _mandatory;
228        private ResponseType _responseType;
229        
230        /**
231         * Constructor for an attendee information
232         * @param mandatory mandatory
233         * @param responseType the answer type
234         */
235        public AttendeeInformation (boolean mandatory, ResponseType responseType)
236        {
237            _mandatory = mandatory;
238            _responseType = responseType;
239        }
240        
241        /**
242         * True if the attendee is mandatory
243         * @return true if the attendee is mandatory
244         */
245        public boolean isMandatory ()
246        {
247            return _mandatory;
248        }
249        
250        /**
251         * Get the response type
252         * @return the response type
253         */
254        public ResponseType getResponseType ()
255        {
256            return _responseType;
257        }
258    }
259}