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.property.complex;
025
026 import microsoft.exchange.webservices.data.core.EwsServiceXmlWriter;
027 import microsoft.exchange.webservices.data.core.EwsUtilities;
028 import microsoft.exchange.webservices.data.core.XmlAttributeNames;
029 import microsoft.exchange.webservices.data.core.XmlElementNames;
030 import microsoft.exchange.webservices.data.core.enumeration.misc.ExchangeVersion;
031 import microsoft.exchange.webservices.data.core.enumeration.property.WellKnownFolderName;
032 import microsoft.exchange.webservices.data.core.exception.service.local.ServiceVersionException;
033 import microsoft.exchange.webservices.data.core.exception.service.local.ServiceXmlSerializationException;
034
035 /**
036 * Represents the Id of a folder.
037 */
038 public final class FolderId extends ServiceId {
039
040 /**
041 * The folder name.
042 */
043 private WellKnownFolderName folderName;
044
045 /**
046 * The mailbox.
047 */
048 private Mailbox mailbox;
049
050 /**
051 * Initializes a new instance.
052 */
053 public FolderId() {
054 super();
055 }
056
057 /**
058 * Initializes a new instance.Use this constructor to link this FolderId to
059 * an existing folder that you have the unique Id of.
060 *
061 * @param uniqueId the unique id
062 * @throws Exception the exception
063 */
064 public FolderId(String uniqueId) throws Exception {
065 super(uniqueId);
066 }
067
068 /**
069 * Initializes a new instance.Use this constructor to link this FolderId to
070 * a well known folder (e.g. Inbox, Calendar or Contacts)
071 *
072 * @param folderName the folder name
073 */
074 public FolderId(WellKnownFolderName folderName) {
075 super();
076 this.folderName = folderName;
077 }
078
079 /**
080 * Initializes a new instance.Use this constructor to link this FolderId to
081 * a well known folder (e.g. Inbox, Calendar or Contacts) in a specific
082 * mailbox.
083 *
084 * @param folderName the folder name
085 * @param mailbox the mailbox
086 */
087 public FolderId(WellKnownFolderName folderName, Mailbox mailbox) {
088 this(folderName);
089 this.mailbox = mailbox;
090 }
091
092 /**
093 * Gets the name of the XML element.
094 *
095 * @return XML element name
096 */
097 public String getXmlElementName() {
098 if (this.getFolderName() != null) {
099 return XmlElementNames.DistinguishedFolderId;
100 } else {
101 return XmlElementNames.FolderId;
102 }
103 }
104
105 /**
106 * Writes attribute to XML.
107 *
108 * @param writer the writer
109 * @throws ServiceXmlSerializationException the service xml serialization exception
110 */
111 public void writeAttributesToXml(EwsServiceXmlWriter writer)
112 throws ServiceXmlSerializationException {
113 if (this.getFolderName() != null) {
114 writer.writeAttributeValue(XmlAttributeNames.Id, this
115 .getFolderName().toString().toLowerCase());
116
117 if (this.mailbox != null) {
118 try {
119 this.mailbox.writeToXml(writer, XmlElementNames.Mailbox);
120 } catch (Exception e) {
121 throw new ServiceXmlSerializationException(e.getMessage());
122 }
123 }
124 } else {
125 super.writeAttributesToXml(writer);
126 }
127 }
128
129 /**
130 * Validates FolderId against a specified request version.
131 *
132 * @param version the version
133 * @throws ServiceVersionException the service version exception
134 */
135 public void validate(ExchangeVersion version)
136 throws ServiceVersionException {
137 // The FolderName property is a WellKnownFolderName, an enumeration
138 // type. If the property
139 // is set, make sure that the value is valid for the request version.
140 if (this.getFolderName() != null) {
141 EwsUtilities
142 .validateEnumVersionValue(this.getFolderName(), version);
143 }
144 }
145
146 /**
147 * Gets the name of the folder associated with the folder Id. Name and Id
148 * are mutually exclusive; if one is set, the other is null.
149 *
150 * @return the folder name
151 */
152 public WellKnownFolderName getFolderName() {
153 return this.folderName;
154 }
155
156 /**
157 * Gets the mailbox of the folder. Mailbox is only set when FolderName is
158 * set.
159 *
160 * @return the mailbox
161 */
162 public Mailbox getMailbox() {
163 return this.mailbox;
164 }
165
166 /**
167 * Defines an implicit conversion between string and FolderId.
168 *
169 * @param uniqueId the unique id
170 * @return A FolderId initialized with the specified unique Id
171 * @throws Exception the exception
172 */
173 public static FolderId getFolderIdFromString(String uniqueId)
174 throws Exception {
175 return new FolderId(uniqueId);
176 }
177
178 /**
179 * Defines an implicit conversion between WellKnownFolderName and FolderId.
180 *
181 * @param folderName the folder name
182 * @return A FolderId initialized with the specified folder name
183 */
184 public static FolderId getFolderIdFromWellKnownFolderName(
185 WellKnownFolderName folderName) {
186 return new FolderId(folderName);
187 }
188
189 /**
190 * True if this instance is valid, false otherwise.
191 *
192 * @return the checks if is valid
193 */
194 protected boolean getIsValid() {
195 if (this.folderName != null) {
196 return (this.mailbox == null) || this.mailbox.isValid();
197 } else {
198 return super.isValid();
199 }
200 }
201
202 /**
203 * Determines whether the specified is equal to the current.
204 *
205 * @param obj the obj
206 * @return true if the specified is equal to the current
207 */
208 @Override
209 public boolean equals(Object obj) {
210 if (obj == this) {
211 return true;
212 } else if (obj instanceof FolderId) {
213 FolderId other = (FolderId) obj;
214
215 if (this.folderName != null) {
216 if (other.folderName != null
217 && this.folderName.equals(other.folderName)) {
218 if (this.mailbox != null) {
219 return this.mailbox.equals(other.mailbox);
220 } else if (other.mailbox == null) {
221 return true;
222 }
223 }
224 } else if (super.equals(other)) {
225 return true;
226 }
227
228 return false;
229 } else {
230 return false;
231 }
232 }
233
234 /**
235 * Serves as a hash function for a particular type.
236 *
237 * @return A hash code for the current
238 */
239 @Override
240 public int hashCode() {
241 int hashCode;
242
243 if (this.folderName != null) {
244 hashCode = this.folderName.hashCode();
245
246 if ((this.mailbox != null) && this.mailbox.isValid()) {
247 hashCode = hashCode ^ this.mailbox.hashCode();
248 }
249 } else {
250 hashCode = super.hashCode();
251 }
252
253 return hashCode;
254 }
255
256 /**
257 * Returns a String that represents the current Object.
258 *
259 * @return the string
260 */
261 public String toString() {
262 if (this.isValid()) {
263 if (this.folderName != null) {
264 if ((this.mailbox != null) && mailbox.isValid()) {
265 return String.format("%s,(%s)", this.folderName,
266 this.mailbox.toString());
267 } else {
268 return this.folderName.toString();
269 }
270 } else {
271 return super.toString();
272 }
273 } else {
274 return "";
275 }
276 }
277 }