Source code

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
024package microsoft.exchange.webservices.data.core.service.item;
025
026import microsoft.exchange.webservices.data.attribute.Attachable;
027import microsoft.exchange.webservices.data.attribute.ServiceObjectDefinition;
028import microsoft.exchange.webservices.data.core.ExchangeService;
029import microsoft.exchange.webservices.data.core.PropertySet;
030import microsoft.exchange.webservices.data.core.XmlElementNames;
031import microsoft.exchange.webservices.data.core.service.schema.ServiceObjectSchema;
032import microsoft.exchange.webservices.data.core.service.schema.TaskSchema;
033import microsoft.exchange.webservices.data.core.enumeration.service.calendar.AffectedTaskOccurrence;
034import microsoft.exchange.webservices.data.core.enumeration.service.ConflictResolutionMode;
035import microsoft.exchange.webservices.data.core.enumeration.service.DeleteMode;
036import microsoft.exchange.webservices.data.core.enumeration.misc.ExchangeVersion;
037import microsoft.exchange.webservices.data.core.enumeration.service.MessageDisposition;
038import microsoft.exchange.webservices.data.core.enumeration.property.TaskDelegationState;
039import microsoft.exchange.webservices.data.core.enumeration.service.TaskMode;
040import microsoft.exchange.webservices.data.core.enumeration.service.TaskStatus;
041import microsoft.exchange.webservices.data.core.exception.service.local.ServiceLocalException;
042import microsoft.exchange.webservices.data.core.exception.service.remote.ServiceResponseException;
043import microsoft.exchange.webservices.data.property.complex.ItemAttachment;
044import microsoft.exchange.webservices.data.property.complex.ItemId;
045import microsoft.exchange.webservices.data.property.complex.StringList;
046import microsoft.exchange.webservices.data.property.complex.recurrence.pattern.Recurrence;
047
048import 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)
056public 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.
586   *
587   * @return the default affected task occurrences
588   */
589  @Override
590  protected AffectedTaskOccurrence getDefaultAffectedTaskOccurrences() {
591    return AffectedTaskOccurrence.AllOccurrences;
592  }
593
594}