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.request;
025
026import microsoft.exchange.webservices.data.core.EwsServiceXmlWriter;
027import microsoft.exchange.webservices.data.core.EwsUtilities;
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.enumeration.service.error.ServiceErrorHandling;
032import microsoft.exchange.webservices.data.core.response.SyncFolderItemsResponse;
033import microsoft.exchange.webservices.data.core.enumeration.misc.ExchangeVersion;
034import microsoft.exchange.webservices.data.core.enumeration.service.ServiceObjectType;
035import microsoft.exchange.webservices.data.core.enumeration.service.SyncFolderItemsScope;
036import microsoft.exchange.webservices.data.core.enumeration.misc.XmlNamespace;
037import microsoft.exchange.webservices.data.core.exception.misc.ArgumentException;
038import microsoft.exchange.webservices.data.core.exception.service.local.ServiceVersionException;
039import microsoft.exchange.webservices.data.misc.ItemIdWrapperList;
040import microsoft.exchange.webservices.data.property.complex.FolderId;
041
042/**
043 * Represents a SyncFolderItems request.
044 */
045public class SyncFolderItemsRequest extends
046    MultiResponseServiceRequest<SyncFolderItemsResponse> {
047
048  /**
049   * The property set.
050   */
051  private PropertySet propertySet;
052
053  /**
054   * The sync folder id.
055   */
056  private FolderId syncFolderId;
057
058  /**
059   * The sync scope.
060   */
061  private SyncFolderItemsScope syncScope;
062
063  /**
064   * The sync state.
065   */
066  private String syncState;
067
068  /**
069   * The ignored item ids.
070   */
071  private ItemIdWrapperList ignoredItemIds = new ItemIdWrapperList();
072
073  /**
074   * The max changes returned.
075   */
076  private int maxChangesReturned = 100;
077
078  /**
079   * Initializes a new instance of the class.
080   *
081   * @param service the service
082   * @throws Exception
083   */
084  public SyncFolderItemsRequest(ExchangeService service)
085      throws Exception {
086    super(service, ServiceErrorHandling.ThrowOnError);
087  }
088
089  /**
090   * Creates service response.
091   *
092   * @param service       the service
093   * @param responseIndex the response index
094   * @return Service response
095   */
096  @Override
097  protected SyncFolderItemsResponse createServiceResponse(
098      ExchangeService service, int responseIndex) {
099    return new SyncFolderItemsResponse(this.getPropertySet());
100  }
101
102  /**
103   * Gets the expected response message count.
104   *
105   * @return Number of expected response messages.
106   */
107  @Override
108  protected int getExpectedResponseMessageCount() {
109    return 1;
110  }
111
112  /**
113   * Gets the name of the XML element.
114   *
115   * @return XML element name
116   */
117  @Override public String getXmlElementName() {
118    return XmlElementNames.SyncFolderItems;
119  }
120
121  /**
122   * Gets the name of the response XML element.
123   *
124   * @return XML element name
125   */
126  @Override
127  protected String getResponseXmlElementName() {
128    return XmlElementNames.SyncFolderItemsResponse;
129  }
130
131  /**
132   * Gets the name of the response message XML element.
133   *
134   * @return XML element name
135   */
136  @Override
137  protected String getResponseMessageXmlElementName() {
138    return XmlElementNames.SyncFolderItemsResponseMessage;
139  }
140
141  /**
142   * Validates request.
143   *
144   * @throws Exception the exception
145   */
146  @Override
147  protected void validate() throws Exception {
148    super.validate();
149    EwsUtilities.validateParam(this.getPropertySet(), "PropertySet");
150    EwsUtilities.validateParam(this.getSyncFolderId(), "SyncFolderId");
151    this.getSyncFolderId().validate(
152        this.getService().getRequestedServerVersion());
153
154    // SyncFolderItemsScope enum was introduced with Exchange2010. Only
155    // value NormalItems is valid with previous server versions.
156    if (this.getService().getRequestedServerVersion().compareTo(
157        ExchangeVersion.Exchange2010) < 0 &&
158        this.syncScope != SyncFolderItemsScope.NormalItems) {
159      throw new ServiceVersionException(String.format(
160          "Enumeration value %s in enumeration type %s is only valid for Exchange version %s or later.", this
161              .getSyncScope().toString(), this.getSyncScope()
162              .name(), ExchangeVersion.Exchange2010));
163    }
164
165    // SyncFolderItems can only handle summary property
166    this.getPropertySet()
167        .validateForRequest(this, true /* summaryPropertiesOnly */);
168  }
169
170  /**
171   * Writes XML elements.
172   *
173   * @param writer the writer
174   * @throws Exception the exception
175   */
176  @Override
177  protected void writeElementsToXml(EwsServiceXmlWriter writer)
178      throws Exception {
179    this.getPropertySet().writeToXml(writer, ServiceObjectType.Item);
180
181    writer.writeStartElement(XmlNamespace.Messages,
182        XmlElementNames.SyncFolderId);
183    this.getSyncFolderId().writeToXml(writer);
184    writer.writeEndElement();
185
186    writer.writeElementValue(XmlNamespace.Messages,
187        XmlElementNames.SyncState, this.getSyncState());
188
189    this.getIgnoredItemIds().writeToXml(writer, XmlNamespace.Messages,
190        XmlElementNames.Ignore);
191
192    writer.writeElementValue(XmlNamespace.Messages,
193        XmlElementNames.MaxChangesReturned, this
194            .getMaxChangesReturned());
195
196    if (this.getService().getRequestedServerVersion().compareTo(
197        ExchangeVersion.Exchange2010) >= 0) {
198      writer.writeElementValue(XmlNamespace.Messages,
199          XmlElementNames.SyncScope, this.syncScope);
200    }
201  }
202
203  /**
204   * Gets the request version.
205   *
206   * @return Earliest Exchange version in which this request is supported.
207   */
208  @Override
209  protected ExchangeVersion getMinimumRequiredServerVersion() {
210    return ExchangeVersion.Exchange2007_SP1;
211  }
212
213  /**
214   * Gets or sets the property set. 
215   *
216   * @return the property set
217   */
218  public PropertySet getPropertySet() {
219    return this.propertySet;
220  }
221
222  /**
223   * Sets the property set.
224   *
225   * @param propertySet the new property set
226   */
227  public void setPropertySet(PropertySet propertySet) {
228    this.propertySet = propertySet;
229  }
230
231  /**
232   * Gets the sync folder id. 
233   *
234   * @return the sync folder id
235   */
236  public FolderId getSyncFolderId() {
237    return this.syncFolderId;
238  }
239
240  /**
241   * Sets the sync folder id.
242   *
243   * @param syncFolderId the new sync folder id
244   */
245  public void setSyncFolderId(FolderId syncFolderId) {
246    this.syncFolderId = syncFolderId;
247  }
248
249  /**
250   * Gets the scope of the sync.
251   *
252   * @return the sync scope
253   */
254  public SyncFolderItemsScope getSyncScope() {
255    return this.syncScope;
256  }
257
258  /**
259   * Sets the sync scope.
260   *
261   * @param syncScope the new sync scope
262   */
263  public void setSyncScope(SyncFolderItemsScope syncScope) {
264    this.syncScope = syncScope;
265  }
266
267  /**
268   * Gets the state of the sync.
269   *
270   * @return the sync state
271   */
272  public String getSyncState() {
273    return this.syncState;
274  }
275
276  /**
277   * Sets the sync state.
278   *
279   * @param syncState the new sync state
280   */
281  public void setSyncState(String syncState) {
282    this.syncState = syncState;
283  }
284
285  /**
286   * Gets the list of ignored item ids. 
287   *
288   * @return the ignored item ids
289   */
290  public ItemIdWrapperList getIgnoredItemIds() {
291    return this.ignoredItemIds;
292  }
293
294  /**
295   * Gets the maximum number of changes returned by SyncFolderItems.
296   * Values must be between 1 and 512. Default is 100.
297   *
298   * @return the max changes returned
299   */
300  public int getMaxChangesReturned() {
301
302    return this.maxChangesReturned;
303  }
304
305  /**
306   * Sets the max changes returned.
307   *
308   * @param maxChangesReturned the new max changes returned
309   * @throws ArgumentException the argument exception
310   */
311  public void setMaxChangesReturned(int maxChangesReturned)
312      throws ArgumentException {
313    if (maxChangesReturned >= 1 && maxChangesReturned <= 512) {
314      this.maxChangesReturned = maxChangesReturned;
315    } else {
316      throw new ArgumentException("MaxChangesReturned must be between 1 and 512.");
317    }
318  }
319
320}