001 /*
002 * The MIT License
003 * Copyright (c) 2012 Microsoft Corporation
004 *
005 * Permission is hereby granted, free of charge, to any person obtaining a copy
006 * of this software and associated documentation files (the "Software"), to deal
007 * in the Software without restriction, including without limitation the rights
008 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
009 * copies of the Software, and to permit persons to whom the Software is
010 * furnished to do so, subject to the following conditions:
011 *
012 * The above copyright notice and this permission notice shall be included in
013 * all copies or substantial portions of the Software.
014 *
015 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
016 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
017 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
018 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
019 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
020 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
021 * THE SOFTWARE.
022 */
023
024 package microsoft.exchange.webservices.data.misc.availability;
025
026 import microsoft.exchange.webservices.data.core.EwsServiceXmlWriter;
027 import microsoft.exchange.webservices.data.core.EwsUtilities;
028 import microsoft.exchange.webservices.data.core.XmlElementNames;
029 import microsoft.exchange.webservices.data.core.request.GetUserAvailabilityRequest;
030 import microsoft.exchange.webservices.data.core.enumeration.availability.FreeBusyViewType;
031 import microsoft.exchange.webservices.data.core.enumeration.availability.SuggestionQuality;
032 import microsoft.exchange.webservices.data.core.enumeration.misc.XmlNamespace;
033
034 import java.util.Date;
035
036 /**
037 * Represents the options of a GetAvailability request.
038 */
039 public final class AvailabilityOptions {
040
041 /**
042 * The merged free busy interval.
043 */
044 private int mergedFreeBusyInterval = 30;
045
046 /**
047 * The requested free busy view.
048 */
049 private FreeBusyViewType requestedFreeBusyView = FreeBusyViewType.Detailed;
050
051 /**
052 * The good suggestion threshold.
053 */
054 private int goodSuggestionThreshold = 25;
055
056 /**
057 * The maximum suggestions per day.
058 */
059 private int maximumSuggestionsPerDay = 10;
060
061 /**
062 * The maximum non work hours suggestions per day.
063 */
064 private int maximumNonWorkHoursSuggestionsPerDay = 0;
065
066 /**
067 * The meeting duration.
068 */
069 private int meetingDuration = 60;
070
071 /**
072 * The minimum suggestion quality.
073 */
074 private SuggestionQuality minimumSuggestionQuality = SuggestionQuality.Fair;
075
076 /**
077 * The detailed suggestions window.
078 */
079 private TimeWindow detailedSuggestionsWindow;
080
081 /**
082 * The current meeting time.
083 */
084 private Date currentMeetingTime;
085
086 /**
087 * The global object id.
088 */
089 private String globalObjectId;
090
091 /**
092 * Validates this instance against the specified time window.
093 *
094 * @param timeWindow the time window
095 * @throws Exception the exception
096 */
097 public void validate(long timeWindow) throws Exception {
098 if (this.mergedFreeBusyInterval > timeWindow) {
099 throw new IllegalArgumentException(
100 "MergedFreeBusyInterval must be smaller than the specified time window.");
101 }
102
103 EwsUtilities.validateParamAllowNull(this.detailedSuggestionsWindow, "DetailedSuggestionsWindow");
104 }
105
106 /**
107 * Writes to XML.
108 *
109 * @param writer the writer
110 * @param request the request
111 * @throws Exception the exception
112 */
113 public void writeToXml(EwsServiceXmlWriter writer, GetUserAvailabilityRequest request) throws Exception {
114 if (request.isFreeBusyViewRequested()) {
115 writer.writeStartElement(XmlNamespace.Types,
116 XmlElementNames.FreeBusyViewOptions);
117
118 request.getTimeWindow().writeToXmlUnscopedDatesOnly(writer,
119 XmlElementNames.TimeWindow);
120
121 writer.writeElementValue(XmlNamespace.Types,
122 XmlElementNames.MergedFreeBusyIntervalInMinutes,
123 this.mergedFreeBusyInterval);
124
125 writer.writeElementValue(XmlNamespace.Types,
126 XmlElementNames.RequestedView, this.requestedFreeBusyView);
127
128 writer.writeEndElement(); // FreeBusyViewOptions
129 }
130
131 if (request.isSuggestionsViewRequested()) {
132 writer.writeStartElement(XmlNamespace.Types,
133 XmlElementNames.SuggestionsViewOptions);
134
135 writer
136 .writeElementValue(XmlNamespace.Types,
137 XmlElementNames.GoodThreshold,
138 this.goodSuggestionThreshold);
139
140 writer.writeElementValue(XmlNamespace.Types,
141 XmlElementNames.MaximumResultsByDay,
142 this.maximumSuggestionsPerDay);
143
144 writer.writeElementValue(XmlNamespace.Types,
145 XmlElementNames.MaximumNonWorkHourResultsByDay,
146 this.maximumNonWorkHoursSuggestionsPerDay);
147
148 writer.writeElementValue(XmlNamespace.Types,
149 XmlElementNames.MeetingDurationInMinutes,
150 this.meetingDuration);
151
152 writer.writeElementValue(XmlNamespace.Types,
153 XmlElementNames.MinimumSuggestionQuality,
154 this.minimumSuggestionQuality);
155
156 TimeWindow timeWindowToSerialize =
157 this.detailedSuggestionsWindow == null ? request
158 .getTimeWindow() :
159 this.detailedSuggestionsWindow;
160
161 timeWindowToSerialize.writeToXmlUnscopedDatesOnly(writer,
162 XmlElementNames.DetailedSuggestionsWindow);
163
164 if (this.currentMeetingTime != null) {
165 writer.writeElementValue(XmlNamespace.Types,
166 XmlElementNames.CurrentMeetingTime,
167 this.currentMeetingTime);
168 }
169
170 writer.writeElementValue(XmlNamespace.Types,
171 XmlElementNames.GlobalObjectId, this.globalObjectId);
172
173 writer.writeEndElement(); // SuggestionsViewOptions
174 }
175 }
176
177 /**
178 * Initializes a new instance of the AvailabilityOptions class.
179 */
180 public AvailabilityOptions() {
181 }
182
183 /**
184 * Gets the time difference between two successive slots in a
185 * FreeBusyMerged view. MergedFreeBusyInterval must be between 5 and 1440.
186 * The default value is 30.
187 *
188 * @return the merged free busy interval
189 */
190 public int getMergedFreeBusyInterval() {
191 return this.mergedFreeBusyInterval;
192 }
193
194 /**
195 * Sets the merged free busy interval.
196 *
197 * @param value the new merged free busy interval
198 */
199 public void setMergedFreeBusyInterval(int value) {
200 if (value < 5 || value > 1440) {
201 throw new IllegalArgumentException(String.format("%s,%s,%s,%s", "%s must be between %d and %d.",
202 "MergedFreeBusyInterval", 5, 1440));
203 }
204
205 this.mergedFreeBusyInterval = value;
206 }
207
208 /**
209 * Gets the requested type of free/busy view. The default value is
210 * FreeBusyViewType.Detailed.
211 *
212 * @return the requested free busy view
213 */
214 public FreeBusyViewType getRequestedFreeBusyView() {
215 return this.requestedFreeBusyView;
216 }
217
218 /**
219 * Sets the requested free busy view.
220 *
221 * @param value the new requested free busy view
222 */
223 public void setRequestedFreeBusyView(FreeBusyViewType value) {
224 this.requestedFreeBusyView = value;
225 }
226
227 /**
228 * Gets the percentage of attendees that must have the time period
229 * open for the time period to qualify as a good suggested meeting time.
230 * GoodSuggestionThreshold must be between 1 and 49. The default value is
231 * 25.
232 *
233 * @return the good suggestion threshold
234 */
235 public int getGoodSuggestionThreshold() {
236 return this.goodSuggestionThreshold;
237 }
238
239 /**
240 * Sets the good suggestion threshold.
241 *
242 * @param value the new good suggestion threshold
243 */
244 public void setGoodSuggestionThreshold(int value) {
245 if (value < 1 || value > 49) {
246 throw new IllegalArgumentException(String.format("%s must be between %d and %d.",
247 "GoodSuggestionThreshold", 1, 49));
248 }
249
250 this.goodSuggestionThreshold = value;
251 }
252
253 /**
254 * Gets the number of suggested meeting times that should be
255 * returned per day. MaximumSuggestionsPerDay must be between 0 and 48. The
256 * default value is 10.
257 *
258 * @return the maximum suggestions per day
259 */
260 public int getMaximumSuggestionsPerDay() {
261 return this.maximumSuggestionsPerDay;
262 }
263
264 /**
265 * Sets the maximum suggestions per day.
266 *
267 * @param value the new maximum suggestions per day
268 */
269 public void setMaximumSuggestionsPerDay(int value) {
270 if (value < 0 || value > 48) {
271 throw new IllegalArgumentException(String.format("%s,%s,%s,%s", "%s must be between %d and %d.",
272 "MaximumSuggestionsPerDay", 0, 48));
273 }
274
275 this.maximumSuggestionsPerDay = value;
276 }
277
278 /**
279 * Gets the number of suggested meeting times outside regular
280 * working hours per day. MaximumNonWorkHoursSuggestionsPerDay must be
281 * between 0 and 48. The default value is 0.
282 *
283 * @return the maximum non work hours suggestions per day
284 */
285 public int getMaximumNonWorkHoursSuggestionsPerDay() {
286 return this.maximumNonWorkHoursSuggestionsPerDay;
287 }
288
289 /**
290 * Sets the maximum non work hours suggestions per day.
291 *
292 * @param value the new maximum non work hours suggestions per day
293 */
294 public void setMaximumNonWorkHoursSuggestionsPerDay(int value) {
295 if (value < 0 || value > 48) {
296 throw new IllegalArgumentException(String.format("%s must be between %d and %d.",
297 "MaximumNonWorkHoursSuggestionsPerDay", 0, 48));
298 }
299
300 this.maximumNonWorkHoursSuggestionsPerDay = value;
301 }
302
303 /**
304 * Gets the duration, in minutes, of the meeting for which to obtain
305 * suggestions. MeetingDuration must be between 30 and 1440. The default
306 * value is 60.
307 *
308 * @return the meeting duration
309 */
310 public int getMeetingDuration() {
311 return this.meetingDuration;
312 }
313
314 /**
315 * Sets the meeting duration.
316 *
317 * @param value the new meeting duration
318 */
319 public void setMeetingDuration(int value) {
320 if (value < 30 || value > 1440) {
321 throw new IllegalArgumentException(String.format("%s,%s,%s,%s", "%s must be between %d and %d.", "MeetingDuration",
322 30, 1440));
323 }
324
325 this.meetingDuration = value;
326 }
327
328 /**
329 * Gets the minimum quality of suggestions that should be returned.
330 * The default is SuggestionQuality.Fair.
331 *
332 * @return the minimum suggestion quality
333 */
334 public SuggestionQuality getMinimumSuggestionQuality() {
335 return this.minimumSuggestionQuality;
336 }
337
338 /**
339 * Sets the minimum suggestion quality.
340 *
341 * @param value the new minimum suggestion quality
342 */
343 public void setMinimumSuggestionQuality(SuggestionQuality value) {
344 this.minimumSuggestionQuality = value;
345 }
346
347 /**
348 * Gets the time window for which detailed information about
349 * suggested meeting times should be returned.
350 *
351 * @return the detailed suggestions window
352 */
353 public TimeWindow getDetailedSuggestionsWindow() {
354 return this.detailedSuggestionsWindow;
355 }
356
357 /**
358 * Sets the detailed suggestions window.
359 *
360 * @param value the new detailed suggestions window
361 */
362 public void setDetailedSuggestionsWindow(TimeWindow value) {
363 this.detailedSuggestionsWindow = value;
364 }
365
366 /**
367 * Gets the start time of a meeting that you want to update with the
368 * suggested meeting times.
369 *
370 * @return the current meeting time
371 */
372 public Date getCurrentMeetingTime() {
373 return this.currentMeetingTime;
374 }
375
376 /**
377 * Sets the current meeting time.
378 *
379 * @param value the new current meeting time
380 */
381 public void setCurrentMeetingTime(Date value) {
382 this.currentMeetingTime = value;
383 }
384
385 /**
386 * Gets the global object Id of a meeting that will be modified
387 * based on the data returned by GetUserAvailability.
388 *
389 * @return the global object id
390 */
391 public String getGlobalObjectId() {
392 return this.globalObjectId;
393 }
394
395 /**
396 * Sets the global object id.
397 *
398 * @param value the new global object id
399 */
400 public void setGlobalObjectId(String value) {
401 this.globalObjectId = value;
402 }
403 }