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.EwsUtilities;
027 import microsoft.exchange.webservices.data.core.XmlElementNames;
028
029 import java.util.Iterator;
030
031 /**
032 * Represents a collection of e-mail addresses.
033 */
034 public final class EmailAddressCollection extends ComplexPropertyCollection<EmailAddress> {
035
036 //XML element name
037 private String collectionItemXmlElementName;
038
039 /**
040 * Initializes a new instance.
041 */
042 public EmailAddressCollection() {
043 this(XmlElementNames.Mailbox);
044 }
045
046 /**
047 * Initializes a new instance of the EmailAddressCollection class.
048 *
049 * @param collectionItemXmlElementName Name of the collection item XML element.
050 */
051 protected EmailAddressCollection(String collectionItemXmlElementName) {
052 super();
053 this.collectionItemXmlElementName = collectionItemXmlElementName;
054 }
055
056 /**
057 * Adds an e-mail address to the collection.
058 *
059 * @param emailAddress The e-mail address to add.
060 */
061 public void add(EmailAddress emailAddress) {
062 this.internalAdd(emailAddress);
063 }
064
065 /**
066 * Adds multiple e-mail addresses to the collection.
067 *
068 * @param emailAddresses The e-mail addresses to add.
069 */
070 public void addEmailRange(Iterator<EmailAddress> emailAddresses) {
071 if (null != emailAddresses) {
072 while (emailAddresses.hasNext()) {
073 this.add(emailAddresses.next());
074 }
075 }
076 }
077
078 /**
079 * Adds an e-mail address to the collection.
080 *
081 * @param smtpAddress The SMTP address used to initialize the e-mail address.
082 * @return An EmailAddress object initialized with the provided SMTP
083 * address.
084 */
085 public EmailAddress add(String smtpAddress) {
086 EmailAddress emailAddress = new EmailAddress(smtpAddress);
087 this.add(emailAddress);
088 return emailAddress;
089 }
090
091 /**
092 * Adds multiple e-mail addresses to the collection.
093 *
094 * @param smtpAddresses The SMTP addresses used to initialize the e-mail addresses.
095 */
096 public void addSmtpAddressRange(Iterator<String> smtpAddresses) {
097 if (null != smtpAddresses) {
098 while (smtpAddresses.hasNext()) {
099 this.add(smtpAddresses.next());
100 }
101 }
102 }
103
104 /**
105 * Adds an e-mail address to the collection.
106 *
107 * @param name The name used to initialize the e-mail address.
108 * @param smtpAddress The SMTP address used to initialize the e-mail address.
109 * @return An EmailAddress object initialized with the provided SMTP
110 * address.
111 */
112 public EmailAddress add(String name, String smtpAddress) {
113 EmailAddress emailAddress = new EmailAddress(name, smtpAddress);
114 this.add(emailAddress);
115 return emailAddress;
116 }
117
118 /**
119 * Clears the collection.
120 */
121 public void clear() {
122 this.internalClear();
123 }
124
125 /**
126 * Removes an e-mail address from the collection.
127 *
128 * @param index The index of the e-mail address to remove.
129 */
130 public void removeAt(int index) {
131 if (index < 0 || index >= this.getCount()) {
132 throw new IllegalArgumentException(
133 String.format("index %d is out of range [0..%d[.", index, this.getCount())
134 );
135 }
136
137 this.internalRemoveAt(index);
138 }
139
140 /**
141 * Removes an e-mail address from the collection.
142 *
143 * @param emailAddress The e-mail address to remove.
144 * @return True if the email address was successfully removed from the
145 * collection, false otherwise.
146 * @throws Exception the exception
147 */
148 public boolean remove(EmailAddress emailAddress) throws Exception {
149 EwsUtilities.validateParam(emailAddress, "emailAddress");
150 return this.internalRemove(emailAddress);
151 }
152
153 /**
154 * Creates an EmailAddress object from an XML element name.
155 *
156 * @param xmlElementName The XML element name from which to create the e-mail address.
157 * @return An EmailAddress object.
158 */
159 @Override
160 protected EmailAddress createComplexProperty(String xmlElementName) {
161 if (xmlElementName.equals(this.collectionItemXmlElementName)) {
162 return new EmailAddress();
163 } else {
164 return null;
165 }
166 }
167
168 /**
169 * Retrieves the XML element name corresponding to the provided EmailAddress
170 * object.
171 *
172 * @param complexProperty The EmailAddress object from which to determine the XML
173 * element name.
174 * @return The XML element name corresponding to the provided EmailAddress
175 * object.
176 */
177 @Override
178 protected String getCollectionItemXmlElementName(
179 EmailAddress complexProperty) {
180 return this.collectionItemXmlElementName;
181 }
182
183 /**
184 * Determine whether we should write collection to XML or not.
185 *
186 * @return Always true, even if the collection is empty.
187 */
188 @Override
189 public boolean shouldWriteToXml() {
190 return true;
191 }
192 }