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.EwsServiceXmlReader;
027 import microsoft.exchange.webservices.data.core.EwsServiceXmlWriter;
028 import microsoft.exchange.webservices.data.core.EwsUtilities;
029 import microsoft.exchange.webservices.data.core.XmlElementNames;
030 import microsoft.exchange.webservices.data.core.enumeration.property.MailboxType;
031 import microsoft.exchange.webservices.data.core.enumeration.misc.XmlNamespace;
032 import org.apache.commons.logging.Log;
033 import org.apache.commons.logging.LogFactory;
034
035 /**
036 * Represents an e-mail address.
037 */
038 public class EmailAddress extends ComplexProperty implements ISearchStringProvider {
039
040 private static final Log LOG = LogFactory.getLog(EmailAddress.class);
041
042 // SMTP routing type.
043 /**
044 * The Constant SmtpRoutingType.
045 */
046 protected final static String SmtpRoutingType = "SMTP";
047
048 // / Display name.
049 /**
050 * The name.
051 */
052 private String name;
053
054 // / Email address.
055 /**
056 * The address.
057 */
058 private String address;
059
060 // / Routing type.
061 /**
062 * The routing type.
063 */
064 private String routingType;
065
066 // / Mailbox type.
067 /**
068 * The mailbox type.
069 */
070 private MailboxType mailboxType;
071
072 // / ItemId - Contact or PDL.
073 /**
074 * The id.
075 */
076 private ItemId id;
077
078 /**
079 * Initializes a new instance.
080 */
081 public EmailAddress() {
082 super();
083 }
084
085 /**
086 * Initializes a new instance.
087 *
088 * @param smtpAddress The SMTP address used to initialize the EmailAddress.
089 */
090 public EmailAddress(String smtpAddress) {
091 this();
092 this.address = smtpAddress;
093 }
094
095 /**
096 * Initializes a new instance.
097 *
098 * @param name The name used to initialize the EmailAddress.
099 * @param smtpAddress The SMTP address used to initialize the EmailAddress.
100 */
101 public EmailAddress(String name, String smtpAddress) {
102 this(smtpAddress);
103 this.name = name;
104 }
105
106 /**
107 * Initializes a new instance.
108 *
109 * @param name The name used to initialize the EmailAddress.
110 * @param address The address used to initialize the EmailAddress.
111 * @param routingType The routing type used to initialize the EmailAddress.
112 */
113 public EmailAddress(String name, String address, String routingType) {
114 this(name, address);
115 this.routingType = routingType;
116 }
117
118 /**
119 * Initializes a new instance.
120 *
121 * @param name The name used to initialize the EmailAddress.
122 * @param address The address used to initialize the EmailAddress.
123 * @param routingType The routing type used to initialize the EmailAddress.
124 * @param mailboxType Mailbox type of the participant.
125 */
126 protected EmailAddress(String name, String address, String routingType,
127 MailboxType mailboxType) {
128 this(name, address, routingType);
129 this.mailboxType = mailboxType;
130 }
131
132 /**
133 * Initializes a new instance.
134 *
135 * @param name The name used to initialize the EmailAddress.
136 * @param address The address used to initialize the EmailAddress.
137 * @param routingType The routing type used to initialize the EmailAddress.
138 * @param mailboxType Mailbox type of the participant.
139 * @param id ItemId of a Contact or PDL.
140 */
141 protected EmailAddress(String name, String address, String routingType,
142 MailboxType mailboxType, ItemId id) {
143 this(name, address, routingType);
144 this.mailboxType = mailboxType;
145 this.id = id;
146 }
147
148 /**
149 * Initializes a new instance from another EmailAddress instance.
150 *
151 * @param mailbox EMailAddress instance to copy.
152 * @throws Exception the exception
153 */
154 protected EmailAddress(EmailAddress mailbox) throws Exception {
155 this();
156 EwsUtilities.validateParam(mailbox, "mailbox");
157 this.name = mailbox.getName();
158 this.address = mailbox.getAddress();
159 this.routingType = mailbox.getRoutingType();
160 this.mailboxType = mailbox.getMailboxType();
161 this.setId(mailbox.getId());
162
163 }
164
165 /**
166 * Gets the name associated with the e-mail address.
167 *
168 * @return the name
169 */
170 public String getName() {
171 return name;
172 }
173
174 /**
175 * Sets the name associated with the e-mail address.
176 *
177 * @param name the new name
178 */
179 public void setName(String name) {
180 if (this.canSetFieldValue(this.name, name)) {
181 this.name = name;
182 this.changed();
183 }
184 }
185
186 /**
187 * Gets the actual address associated with the e-mail address.
188 *
189 * @return address associated with the e-mail address.
190 */
191 public String getAddress() {
192 return address;
193 }
194
195 /**
196 * Sets the actual address associated with the e-mail address. The type of
197 * the Address property must match the specified routing type. If
198 * RoutingType is not set, Address is assumed to be an SMTP address.
199 *
200 * @param address address associated with the e-mail address.
201 */
202 public void setAddress(String address) {
203
204 if (this.canSetFieldValue(this.address, address)) {
205 this.address = address;
206 this.changed();
207 }
208
209 }
210
211 /**
212 * Gets the routing type associated with the e-mail address.
213 *
214 * @return the routing type
215 */
216 public String getRoutingType() {
217 return routingType;
218 }
219
220 /**
221 * Sets the routing type associated with the e-mail address. If RoutingType
222 * is not set, Address is assumed to be an SMTP address.
223 *
224 * @param routingType routing type associated with the e-mail address.
225 */
226 public void setRoutingType(String routingType) {
227 if (this.canSetFieldValue(this.routingType, routingType)) {
228 this.routingType = routingType;
229 this.changed();
230 }
231 }
232
233 /**
234 * Gets the type of the e-mail address.
235 *
236 * @return type of the e-mail address.
237 */
238 public MailboxType getMailboxType() {
239 return mailboxType;
240 }
241
242 /**
243 * Sets the type of the e-mail address.
244 *
245 * @param mailboxType the new mailbox type
246 */
247 public void setMailboxType(MailboxType mailboxType) {
248 if (this.canSetFieldValue(this.mailboxType, mailboxType)) {
249 this.mailboxType = mailboxType;
250 this.changed();
251 }
252 }
253
254 /**
255 * Gets the Id of the contact the e-mail address represents.
256 *
257 * @return the id
258 */
259 public ItemId getId() {
260 return id;
261 }
262
263 /**
264 * Sets the Id of the contact the e-mail address represents. When Id is
265 * specified, Address should be set to null.
266 *
267 * @param id the new id
268 */
269 public void setId(ItemId id) {
270
271 if (this.canSetFieldValue(this.id, id)) {
272 this.id = id;
273 this.changed();
274 }
275 }
276
277 /**
278 * Defines an implicit conversion between a string representing an SMTP
279 * address and EmailAddress.
280 *
281 * @param smtpAddress The SMTP address to convert to EmailAddress.
282 * @return An EmailAddress initialized with the specified SMTP address.
283 */
284 public static EmailAddress getEmailAddressFromString(String smtpAddress) {
285 return new EmailAddress(smtpAddress);
286 }
287
288 /**
289 * Try read element from xml.
290 *
291 * @param reader accepts EwsServiceXmlReader
292 * @return true
293 * @throws Exception throws Exception
294 */
295 public boolean tryReadElementFromXml(EwsServiceXmlReader reader)
296 throws Exception {
297 try {
298 if (reader.getLocalName().equals(XmlElementNames.Name)) {
299 this.name = reader.readElementValue();
300 return true;
301 } else if (reader.getLocalName().equals(
302 XmlElementNames.EmailAddress)) {
303 this.address = reader.readElementValue();
304 return true;
305 } else if (reader.getLocalName()
306 .equals(XmlElementNames.RoutingType)) {
307 this.routingType = reader.readElementValue();
308 return true;
309 } else if (reader.getLocalName()
310 .equals(XmlElementNames.MailboxType)) {
311 this.mailboxType = reader.readElementValue(MailboxType.class);
312 return true;
313 } else if (reader.getLocalName().equals(XmlElementNames.ItemId)) {
314 this.id = new ItemId();
315 this.id.loadFromXml(reader, reader.getLocalName());
316 return true;
317 } else {
318 return false;
319 }
320 } catch (Exception e) {
321 LOG.error(e);
322 return false;
323 }
324 }
325
326 /**
327 * Writes elements to XML.
328 *
329 * @param writer The writer.
330 * @throws Exception the exception
331 */
332 @Override
333 public void writeElementsToXml(EwsServiceXmlWriter writer)
334 throws Exception {
335 writer.writeElementValue(XmlNamespace.Types, XmlElementNames.Name, this
336 .getName());
337 writer.writeElementValue(XmlNamespace.Types,
338 XmlElementNames.EmailAddress, this.getAddress());
339 writer.writeElementValue(XmlNamespace.Types,
340 XmlElementNames.RoutingType, this.getRoutingType());
341 writer.writeElementValue(XmlNamespace.Types,
342 XmlElementNames.MailboxType, this.getMailboxType());
343
344 if (this.getId() != null) {
345 this.getId().writeToXml(writer, XmlElementNames.ItemId);
346 }
347
348 }
349
350 /**
351 * Get a string representation for using this instance in a search filter.
352 *
353 * @return String representation of instance.
354 */
355 @Override
356 public String getSearchString() {
357 return this.getAddress();
358 }
359
360 /**
361 * Returns string that represents the current instance.
362 *
363 * @return String representation of instance.
364 */
365 @Override
366 public String toString() {
367 String addressPart;
368
369 if (null == this.getAddress() || this.getAddress().isEmpty()) {
370 return "";
371 }
372
373 if (null != this.getRoutingType() && this.getRoutingType().isEmpty()) {
374 addressPart = this.getRoutingType() + ":" + this.getAddress();
375 } else {
376 addressPart = this.getAddress();
377 }
378
379 if (null != this.getName() && !this.getName().isEmpty()) {
380 return this.getName() + " <" + addressPart + ">";
381 } else {
382 return addressPart;
383 }
384 }
385
386 /**
387 * Gets the routing type.
388 *
389 * @return SMTP Routing type
390 */
391 protected String getSmtpRoutingType() {
392 return SmtpRoutingType;
393 }
394
395 }