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.request;
025
026 import microsoft.exchange.webservices.data.core.EwsServiceXmlWriter;
027 import microsoft.exchange.webservices.data.core.EwsUtilities;
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.enumeration.service.error.ServiceErrorHandling;
032 import microsoft.exchange.webservices.data.core.response.SyncFolderItemsResponse;
033 import microsoft.exchange.webservices.data.core.enumeration.misc.ExchangeVersion;
034 import microsoft.exchange.webservices.data.core.enumeration.service.ServiceObjectType;
035 import microsoft.exchange.webservices.data.core.enumeration.service.SyncFolderItemsScope;
036 import microsoft.exchange.webservices.data.core.enumeration.misc.XmlNamespace;
037 import microsoft.exchange.webservices.data.core.exception.misc.ArgumentException;
038 import microsoft.exchange.webservices.data.core.exception.service.local.ServiceVersionException;
039 import microsoft.exchange.webservices.data.misc.ItemIdWrapperList;
040 import microsoft.exchange.webservices.data.property.complex.FolderId;
041
042 /**
043 * Represents a SyncFolderItems request.
044 */
045 public 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. <value>The property set.</value>
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. <value>The sync folder id.</value>
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. <value>The scope of the
251 * sync.</value>
252 *
253 * @return the sync scope
254 */
255 public SyncFolderItemsScope getSyncScope() {
256 return this.syncScope;
257 }
258
259 /**
260 * Sets the sync scope.
261 *
262 * @param syncScope the new sync scope
263 */
264 public void setSyncScope(SyncFolderItemsScope syncScope) {
265 this.syncScope = syncScope;
266 }
267
268 /**
269 * Gets the state of the sync. <value>The state of the
270 * sync.</value>
271 *
272 * @return the sync state
273 */
274 public String getSyncState() {
275 return this.syncState;
276 }
277
278 /**
279 * Sets the sync state.
280 *
281 * @param syncState the new sync state
282 */
283 public void setSyncState(String syncState) {
284 this.syncState = syncState;
285 }
286
287 /**
288 * Gets the list of ignored item ids. <value>The ignored item ids.</value>
289 *
290 * @return the ignored item ids
291 */
292 public ItemIdWrapperList getIgnoredItemIds() {
293 return this.ignoredItemIds;
294 }
295
296 /**
297 * Gets the maximum number of changes returned by SyncFolderItems.
298 * Values must be between 1 and 512. Default is 100.
299 *
300 * @return the max changes returned
301 */
302 public int getMaxChangesReturned() {
303
304 return this.maxChangesReturned;
305 }
306
307 /**
308 * Sets the max changes returned.
309 *
310 * @param maxChangesReturned the new max changes returned
311 * @throws ArgumentException the argument exception
312 */
313 public void setMaxChangesReturned(int maxChangesReturned)
314 throws ArgumentException {
315 if (maxChangesReturned >= 1 && maxChangesReturned <= 512) {
316 this.maxChangesReturned = maxChangesReturned;
317 } else {
318 throw new ArgumentException("MaxChangesReturned must be between 1 and 512.");
319 }
320 }
321
322 }