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.core.service.item;
025
026 import microsoft.exchange.webservices.data.attribute.Attachable;
027 import microsoft.exchange.webservices.data.attribute.ServiceObjectDefinition;
028 import microsoft.exchange.webservices.data.core.ExchangeService;
029 import microsoft.exchange.webservices.data.core.PropertySet;
030 import microsoft.exchange.webservices.data.core.XmlElementNames;
031 import microsoft.exchange.webservices.data.core.service.schema.ServiceObjectSchema;
032 import microsoft.exchange.webservices.data.core.service.schema.TaskSchema;
033 import microsoft.exchange.webservices.data.core.enumeration.service.calendar.AffectedTaskOccurrence;
034 import microsoft.exchange.webservices.data.core.enumeration.service.ConflictResolutionMode;
035 import microsoft.exchange.webservices.data.core.enumeration.service.DeleteMode;
036 import microsoft.exchange.webservices.data.core.enumeration.misc.ExchangeVersion;
037 import microsoft.exchange.webservices.data.core.enumeration.service.MessageDisposition;
038 import microsoft.exchange.webservices.data.core.enumeration.property.TaskDelegationState;
039 import microsoft.exchange.webservices.data.core.enumeration.service.TaskMode;
040 import microsoft.exchange.webservices.data.core.enumeration.service.TaskStatus;
041 import microsoft.exchange.webservices.data.core.exception.service.local.ServiceLocalException;
042 import microsoft.exchange.webservices.data.core.exception.service.remote.ServiceResponseException;
043 import microsoft.exchange.webservices.data.property.complex.ItemAttachment;
044 import microsoft.exchange.webservices.data.property.complex.ItemId;
045 import microsoft.exchange.webservices.data.property.complex.StringList;
046 import microsoft.exchange.webservices.data.property.complex.recurrence.pattern.Recurrence;
047
048 import java.util.Date;
049
050 /**
051 * Represents a Task item. Properties available on tasks are defined in the
052 * TaskSchema class.
053 */
054 @Attachable
055 @ServiceObjectDefinition(xmlElementName = XmlElementNames.Task)
056 public class Task extends Item {
057
058 private static final double PERCENT_MIN = 0.0D;
059 private static final double PERCENT_MAX = 100.0D;
060
061
062 /**
063 * Initializes an unsaved local instance of Task.To bind to an existing
064 * task, use Task.Bind() instead.
065 *
066 * @param service the service
067 * @throws Exception the exception
068 */
069 public Task(ExchangeService service) throws Exception {
070 super(service);
071 }
072
073 /**
074 * Initializes a new instance of the class.
075 *
076 * @param parentAttachment the parent attachment
077 * @throws Exception the exception
078 */
079 public Task(ItemAttachment parentAttachment) throws Exception {
080 super(parentAttachment);
081 }
082
083 /**
084 * Binds to an existing task and loads the specified set of property.
085 * Calling this method results in a call to EWS.
086 *
087 * @param service the service
088 * @param id the id
089 * @param propertySet the property set
090 * @return A Task instance representing the task corresponding to the
091 * specified Id.
092 * @throws Exception the exception
093 */
094 public static Task bind(ExchangeService service, ItemId id,
095 PropertySet propertySet) throws Exception {
096 return service.bindToItem(Task.class, id, propertySet);
097 }
098
099 /**
100 * Binds to an existing task and loads its first class property. Calling
101 * this method results in a call to EWS.
102 *
103 * @param service the service
104 * @param id the id
105 * @return A Task instance representing the task corresponding to the
106 * specified Id.
107 * @throws Exception the exception
108 */
109 public static Task bind(ExchangeService service, ItemId id)
110 throws Exception {
111 return Task.bind(service, id, PropertySet.getFirstClassProperties());
112 }
113
114 /**
115 * Internal method to return the schema associated with this type of object.
116 *
117 * @return The schema associated with this type of object.
118 */
119 @Override public ServiceObjectSchema getSchema() {
120 return TaskSchema.Instance;
121 }
122
123 /**
124 * Gets the minimum required server version.
125 *
126 * @return Earliest Exchange version in which this service object type is
127 * supported.
128 */
129 @Override public ExchangeVersion getMinimumRequiredServerVersion() {
130 return ExchangeVersion.Exchange2007_SP1;
131 }
132
133 /**
134 * Gets a value indicating whether a time zone SOAP header should be
135 * emitted in a CreateItem or UpdateItem request so this item can be
136 * property saved or updated.
137 *
138 * @param isUpdateOperation the is update operation
139 * @return if a time zone SOAP header should be emitted; otherwise, .
140 */
141 @Override public boolean getIsTimeZoneHeaderRequired(boolean isUpdateOperation) {
142 return true;
143 }
144
145 /**
146 * Deletes the current occurrence of a recurring task. After the current
147 * occurrence isdeleted, the task represents the next occurrence. Developers
148 * should call Load to retrieve the new property values of the task. Calling
149 * this method results in a call to EWS.
150 *
151 * @param deleteMode the delete mode
152 * @throws ServiceLocalException the service local exception
153 * @throws Exception the exception
154 */
155 public void deleteCurrentOccurrence(DeleteMode deleteMode)
156 throws ServiceLocalException, Exception {
157 this.internalDelete(deleteMode, null,
158 AffectedTaskOccurrence.SpecifiedOccurrenceOnly);
159 }
160
161 /**
162 * Applies the local changes that have been made to this task. Calling
163 * this method results in at least one call to EWS. Mutliple calls to EWS
164 * might be made if attachments have been added or removed.
165 *
166 * @param conflictResolutionMode the conflict resolution mode
167 * @return A Task object representing the completed occurrence if the task
168 * is recurring and the update marks it as completed; or a Task
169 * object representing the current occurrence if the task is
170 * recurring and the uypdate changed its recurrence pattern; or null
171 * in every other case.
172 * @throws ServiceResponseException the service response exception
173 * @throws Exception the exception
174 */
175 public Task updateTask(ConflictResolutionMode conflictResolutionMode)
176 throws ServiceResponseException, Exception {
177 return (Task) this.internalUpdate(null /* parentFolder */,
178 conflictResolutionMode, MessageDisposition.SaveOnly, null);
179 }
180
181 // Properties
182
183 /**
184 * Gets the actual amount of time that is spent on the task.
185 *
186 * @return the actual work
187 * @throws ServiceLocalException the service local exception
188 */
189 public Integer getActualWork() throws ServiceLocalException {
190 return getPropertyBag().getObjectFromPropertyDefinition(
191 TaskSchema.ActualWork);
192 }
193
194 /**
195 * Sets the checks if is read.
196 *
197 * @param value the new checks if is read
198 * @throws Exception the exception
199 */
200 public void setActualWork(Integer value) throws Exception {
201 this.getPropertyBag().setObjectFromPropertyDefinition(
202 TaskSchema.ActualWork, value);
203 }
204
205 /**
206 * Gets the date and time the task was assigned.
207 *
208 * @return the assigned time
209 * @throws ServiceLocalException the service local exception
210 */
211 public Date getAssignedTime() throws ServiceLocalException {
212 return getPropertyBag().getObjectFromPropertyDefinition(
213 TaskSchema.AssignedTime);
214 }
215
216 /**
217 * Gets the billing information of the task.
218 *
219 * @return the billing information
220 * @throws ServiceLocalException the service local exception
221 */
222 public String getBillingInformation() throws ServiceLocalException {
223 return getPropertyBag().getObjectFromPropertyDefinition(
224 TaskSchema.BillingInformation);
225 }
226
227 /**
228 * Sets the billing information.
229 *
230 * @param value the new billing information
231 * @throws Exception the exception
232 */
233 public void setBillingInformation(String value) throws Exception {
234 this.getPropertyBag().setObjectFromPropertyDefinition(
235 TaskSchema.BillingInformation, value);
236 }
237
238 /**
239 * Gets the number of times the task has changed since it was created.
240 *
241 * @return the change count
242 * @throws ServiceLocalException the service local exception
243 */
244 public Integer getChangeCount() throws ServiceLocalException {
245 return getPropertyBag().getObjectFromPropertyDefinition(
246 TaskSchema.ChangeCount);
247 }
248
249 /**
250 * Gets a list of companies associated with the task.
251 *
252 * @return the companies
253 * @throws ServiceLocalException the service local exception
254 */
255 public StringList getCompanies() throws ServiceLocalException {
256 return getPropertyBag().getObjectFromPropertyDefinition(
257 TaskSchema.Companies);
258 }
259
260 /**
261 * Sets the companies.
262 *
263 * @param value the new companies
264 * @throws Exception the exception
265 */
266 public void setCompanies(StringList value) throws Exception {
267 this.getPropertyBag().setObjectFromPropertyDefinition(
268 TaskSchema.Companies, value);
269 }
270
271 /**
272 * Gets the date and time on which the task was completed.
273 *
274 * @return the complete date
275 * @throws ServiceLocalException the service local exception
276 */
277 public Date getCompleteDate() throws ServiceLocalException {
278 return getPropertyBag().getObjectFromPropertyDefinition(
279 TaskSchema.CompleteDate);
280 }
281
282 /**
283 * Sets the complete date.
284 *
285 * @param value the new complete date
286 * @throws Exception the exception
287 */
288 public void setCompleteDate(Date value) throws Exception {
289 this.getPropertyBag().setObjectFromPropertyDefinition(
290 TaskSchema.CompleteDate, value);
291 }
292
293 /**
294 * Gets a list of contacts associated with the task.
295 *
296 * @return the contacts
297 * @throws ServiceLocalException the service local exception
298 */
299 public StringList getContacts() throws ServiceLocalException {
300 return getPropertyBag().getObjectFromPropertyDefinition(
301 TaskSchema.Contacts);
302 }
303
304 /**
305 * Sets the contacts.
306 *
307 * @param value the new contacts
308 * @throws Exception the exception
309 */
310 public void setContacts(StringList value) throws Exception {
311 this.getPropertyBag().setObjectFromPropertyDefinition(
312 TaskSchema.Contacts, value);
313 }
314
315 /**
316 * Gets the current delegation state of the task.
317 *
318 * @return the delegation state
319 * @throws ServiceLocalException the service local exception
320 */
321 public TaskDelegationState getDelegationState()
322 throws ServiceLocalException {
323 return getPropertyBag().getObjectFromPropertyDefinition(
324 TaskSchema.DelegationState);
325 }
326
327 /**
328 * Gets the name of the delegator of this task.
329 *
330 * @return the delegator
331 * @throws ServiceLocalException the service local exception
332 */
333 public String getDelegator() throws ServiceLocalException {
334 return getPropertyBag().getObjectFromPropertyDefinition(
335 TaskSchema.Delegator);
336 }
337
338 /**
339 * Gets a list of contacts associated with the task.
340 *
341 * @return the due date
342 * @throws ServiceLocalException the service local exception
343 */
344 public Date getDueDate() throws ServiceLocalException {
345 return getPropertyBag().getObjectFromPropertyDefinition(
346 TaskSchema.DueDate);
347 }
348
349 /**
350 * Sets the due date.
351 *
352 * @param value the new due date
353 * @throws Exception the exception
354 */
355 public void setDueDate(Date value) throws Exception {
356 this.getPropertyBag().setObjectFromPropertyDefinition(
357 TaskSchema.DueDate, value);
358 }
359
360 /**
361 * Gets a value indicating the mode of the task.
362 *
363 * @return the mode
364 * @throws ServiceLocalException the service local exception
365 */
366 public TaskMode getMode() throws ServiceLocalException {
367 return getPropertyBag().getObjectFromPropertyDefinition(TaskSchema.Mode);
368 }
369
370 /**
371 * Gets a value indicating whether the task is complete.
372 *
373 * @return the checks if is complete
374 * @throws ServiceLocalException the service local exception
375 */
376 public Boolean getIsComplete() throws ServiceLocalException {
377 return getPropertyBag().getObjectFromPropertyDefinition(
378 TaskSchema.IsComplete);
379 }
380
381 /**
382 * Gets a value indicating whether the task is recurring.
383 *
384 * @return the checks if is recurring
385 * @throws ServiceLocalException the service local exception
386 */
387 public Boolean getIsRecurring() throws ServiceLocalException {
388 return getPropertyBag().getObjectFromPropertyDefinition(
389 TaskSchema.IsRecurring);
390 }
391
392 /**
393 * Gets a value indicating whether the task is a team task.
394 *
395 * @return the checks if is team task
396 * @throws ServiceLocalException the service local exception
397 */
398 public Boolean getIsTeamTask() throws ServiceLocalException {
399 return getPropertyBag().getObjectFromPropertyDefinition(
400 TaskSchema.IsTeamTask);
401 }
402
403 /**
404 * Gets the mileage of the task.
405 *
406 * @return the mileage
407 * @throws ServiceLocalException the service local exception
408 */
409 public String getMileage() throws ServiceLocalException {
410 return getPropertyBag().getObjectFromPropertyDefinition(
411 TaskSchema.Mileage);
412 }
413
414 /**
415 * Sets the mileage.
416 *
417 * @param value the new mileage
418 * @throws Exception the exception
419 */
420 public void setMileage(String value) throws Exception {
421 this.getPropertyBag().setObjectFromPropertyDefinition(
422 TaskSchema.Mileage, value);
423 }
424
425 /**
426 * Gets the name of the owner of the task.
427 *
428 * @return the owner
429 * @throws ServiceLocalException the service local exception
430 */
431 public String getOwner() throws ServiceLocalException {
432 return getPropertyBag().getObjectFromPropertyDefinition(
433 TaskSchema.Owner);
434 }
435
436 /**
437 * Gets the completion percentage of the task.
438 * PercentComplete must be between
439 * 0 and 100.
440 *
441 * @return the percent complete
442 * @throws ServiceLocalException the service local exception
443 */
444 public Double getPercentComplete() throws ServiceLocalException {
445 return getPropertyBag().getObjectFromPropertyDefinition(
446 TaskSchema.PercentComplete);
447 }
448
449 /**
450 * Sets the completion percentage of the task.
451 * PercentComplete must be between
452 * 0.0 and 100.0 .
453 *
454 * @param value the new percent complete
455 * @throws Exception the exception
456 * @deprecated use Double parameter instead
457 */
458 @Deprecated
459 public void setPercentComplete(String value) throws Exception {
460 setPercentComplete(Double.valueOf(value));
461 }
462
463 /**
464 * Sets the completion percentage of the task.
465 * PercentComplete must be between
466 * 0.0 and 100.0 .
467 *
468 * @param value the new percent complete
469 * @throws Exception the exception
470 */
471 public void setPercentComplete(Double value) throws Exception {
472 if (value == null || Double.isNaN(value) || value < PERCENT_MIN || value > PERCENT_MAX) {
473 throw new IllegalArgumentException(
474 String.format("%s must be between %f and %f",
475 String.valueOf(value), PERCENT_MIN, PERCENT_MAX));
476 }
477 this.getPropertyBag().setObjectFromPropertyDefinition(
478 TaskSchema.PercentComplete, value);
479 }
480
481 /**
482 * Gets the recurrence pattern for this task. Available recurrence
483 * pattern classes include Recurrence.DailyPattern,
484 * Recurrence.MonthlyPattern and Recurrence.YearlyPattern.
485 *
486 * @return the recurrence
487 * @throws ServiceLocalException the service local exception
488 */
489 public Recurrence getRecurrence() throws ServiceLocalException {
490 return getPropertyBag().getObjectFromPropertyDefinition(
491 TaskSchema.Recurrence);
492 }
493
494 /**
495 * Sets the recurrence.
496 *
497 * @param value the new recurrence
498 * @throws Exception the exception
499 */
500 public void setRecurrence(Recurrence value) throws Exception {
501 this.getPropertyBag().setObjectFromPropertyDefinition(
502 TaskSchema.Recurrence, value);
503 }
504
505 /**
506 * Gets the date and time on which the task starts.
507 *
508 * @return the start date
509 * @throws ServiceLocalException the service local exception
510 */
511 public Date getStartDate() throws ServiceLocalException {
512 return getPropertyBag().getObjectFromPropertyDefinition(
513 TaskSchema.StartDate);
514 }
515
516 /**
517 * Sets the start date.
518 *
519 * @param value the new start date
520 * @throws Exception the exception
521 */
522 public void setStartDate(Date value) throws Exception {
523 this.getPropertyBag().setObjectFromPropertyDefinition(
524 TaskSchema.StartDate, value);
525 }
526
527 /**
528 * Gets the status of the task.
529 *
530 * @return the status
531 * @throws ServiceLocalException the service local exception
532 */
533 public TaskStatus getStatus() throws ServiceLocalException {
534 return getPropertyBag().getObjectFromPropertyDefinition(TaskSchema.Status);
535 }
536
537 /**
538 * Sets the status.
539 *
540 * @param value the new status
541 * @throws Exception the exception
542 */
543 public void setStatus(TaskStatus value) throws Exception {
544 this.getPropertyBag().setObjectFromPropertyDefinition(
545 TaskSchema.Status, value);
546 }
547
548 /**
549 * Gets a string representing the status of the task, localized according to
550 * the PreferredCulture property of the ExchangeService object the task is
551 * bound to.
552 *
553 * @return the status description
554 * @throws ServiceLocalException the service local exception
555 */
556 public String getStatusDescription() throws ServiceLocalException {
557 return getPropertyBag().getObjectFromPropertyDefinition(
558 TaskSchema.StatusDescription);
559 }
560
561 /**
562 * Gets the total amount of work spent on the task.
563 *
564 * @return the total work
565 * @throws ServiceLocalException the service local exception
566 */
567 public Integer getTotalWork() throws ServiceLocalException {
568 return getPropertyBag().getObjectFromPropertyDefinition(
569 TaskSchema.TotalWork);
570 }
571
572 /**
573 * Sets the total work.
574 *
575 * @param value the new total work
576 * @throws Exception the exception
577 */
578 public void setTotalWork(Integer value) throws Exception {
579 this.getPropertyBag().setObjectFromPropertyDefinition(
580 TaskSchema.TotalWork, value);
581 }
582
583 /**
584 * Gets the default setting for how to treat affected task occurrences on
585 * Delete. <value>AffectedTaskOccurrence.AllOccurrences: All affected Task
586 * occurrences will be deleted.</value>
587 *
588 * @return the default affected task occurrences
589 */
590 @Override
591 protected AffectedTaskOccurrence getDefaultAffectedTaskOccurrences() {
592 return AffectedTaskOccurrence.AllOccurrences;
593 }
594
595 }