001 package ezvcard.property;
002
003 import java.util.HashSet;
004 import java.util.List;
005 import java.util.Set;
006
007 import ezvcard.VCard;
008 import ezvcard.VCardVersion;
009 import ezvcard.Warning;
010 import ezvcard.parameter.AddressType;
011 import ezvcard.parameter.VCardParameters;
012
013 /*
014 Copyright (c) 2013, Michael Angstadt
015 All rights reserved.
016
017 Redistribution and use in source and binary forms, with or without
018 modification, are permitted provided that the following conditions are met:
019
020 1. Redistributions of source code must retain the above copyright notice, this
021 list of conditions and the following disclaimer.
022 2. Redistributions in binary form must reproduce the above copyright notice,
023 this list of conditions and the following disclaimer in the documentation
024 and/or other materials provided with the distribution.
025
026 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
027 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
028 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
029 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
030 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
031 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
032 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
033 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
034 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
035 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
036
037 The views and conclusions contained in the software and documentation are those
038 of the authors and should not be interpreted as representing official policies,
039 either expressed or implied, of the FreeBSD Project.
040 */
041
042 /**
043 * A mailing address.
044 *
045 * <p>
046 * <b>Adding an address</b>
047 * </p>
048 *
049 * <pre class="brush:java">
050 * VCard vcard = new VCard();
051 * Address adr = new Address();
052 * adr.setStreetAddress("123 Main St.");
053 * adr.setLocality("Austin");
054 * adr.setRegion("TX");
055 * adr.setPostalCode("12345");
056 * adr.setCountry("USA");
057 * adr.addType(AddressType.WORK);
058 * adr.addType(AddressType.DOM);
059 *
060 * //optionally, provide the exact text to print out on the mailing label
061 * adr.setLabel("123 Main St.\nAustin, Tx 12345\nUSA");
062 *
063 * vcard.addAddress(adr);
064 * </pre>
065 *
066 * <p>
067 * <b>Getting the addresses</b>
068 * </p>
069 *
070 * <pre class="brush:java">
071 * VCard vcard = ...
072 * for (Address adr : vcard.getAddresses()){
073 * ...
074 * }
075 * </pre>
076 *
077 * <p>
078 * <b>Property name:</b> {@code ADR}
079 * </p>
080 * <p>
081 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
082 * </p>
083 * @author Michael Angstadt
084 */
085 public class Address extends VCardProperty implements HasAltId {
086 private String poBox;
087 private String extendedAddress;
088 private String streetAddress;
089 private String locality;
090 private String region;
091 private String postalCode;
092 private String country;
093
094 /**
095 * Gets the P.O. (post office) box.
096 * @return the P.O. box or null if not set
097 */
098 public String getPoBox() {
099 return poBox;
100 }
101
102 /**
103 * Sets the P.O. (post office) box.
104 * @param poBox the P.O. box or null to remove
105 */
106 public void setPoBox(String poBox) {
107 this.poBox = poBox;
108 }
109
110 /**
111 * Gets the extended address.
112 * @return the extended address (e.g. "Suite 200") or null if not set
113 */
114 public String getExtendedAddress() {
115 return extendedAddress;
116 }
117
118 /**
119 * Sets the extended address.
120 * @param extendedAddress the extended address (e.g. "Suite 200") or null to
121 * remove
122 */
123 public void setExtendedAddress(String extendedAddress) {
124 this.extendedAddress = extendedAddress;
125 }
126
127 /**
128 * Gets the street address
129 * @return the street address (e.g. "123 Main St")
130 */
131 public String getStreetAddress() {
132 return streetAddress;
133 }
134
135 /**
136 * Sets the street address.
137 * @param streetAddress the street address (e.g. "123 Main St") or null to
138 * remove
139 */
140 public void setStreetAddress(String streetAddress) {
141 this.streetAddress = streetAddress;
142 }
143
144 /**
145 * Gets the locality (city)
146 * @return the locality (e.g. "Boston") or null if not set
147 */
148 public String getLocality() {
149 return locality;
150 }
151
152 /**
153 * Sets the locality (city).
154 * @param locality the locality or null to remove
155 */
156 public void setLocality(String locality) {
157 this.locality = locality;
158 }
159
160 /**
161 * Gets the region.
162 * @return the region (e.g. "Texas") or null if not set
163 */
164 public String getRegion() {
165 return region;
166 }
167
168 /**
169 * Sets the region.
170 * @param region the region (e.g. "Texas") or null to remove
171 */
172 public void setRegion(String region) {
173 this.region = region;
174 }
175
176 /**
177 * Gets the postal code.
178 * @return the postal code (e.g. "90210") or null if not set
179 */
180 public String getPostalCode() {
181 return postalCode;
182 }
183
184 /**
185 * Sets the postal code.
186 * @param postalCode the postal code (e.g. "90210") or null to remove
187 */
188 public void setPostalCode(String postalCode) {
189 this.postalCode = postalCode;
190 }
191
192 /**
193 * Gets the country.
194 * @return the country (e.g. "USA") or null if not set
195 */
196 public String getCountry() {
197 return country;
198 }
199
200 /**
201 * Sets the country.
202 * @param country the country (e.g. "USA") or null to remove
203 */
204 public void setCountry(String country) {
205 this.country = country;
206 }
207
208 /**
209 * Gets all the TYPE parameters.
210 * @return the TYPE parameters or empty set if there are none
211 */
212 public Set<AddressType> getTypes() {
213 Set<String> values = parameters.getTypes();
214 Set<AddressType> types = new HashSet<AddressType>(values.size());
215 for (String value : values) {
216 types.add(AddressType.get(value));
217 }
218 return types;
219 }
220
221 /**
222 * Adds a TYPE parameter.
223 * @param type the TYPE parameter to add
224 */
225 public void addType(AddressType type) {
226 parameters.addType(type.getValue());
227 }
228
229 /**
230 * Removes a TYPE parameter.
231 * @param type the TYPE parameter to remove
232 */
233 public void removeType(AddressType type) {
234 parameters.removeType(type.getValue());
235 }
236
237 @Override
238 public String getLanguage() {
239 return super.getLanguage();
240 }
241
242 @Override
243 public void setLanguage(String language) {
244 super.setLanguage(language);
245 }
246
247 /**
248 * Gets the label of the address.
249 * @return the label or null if it doesn't have one
250 */
251 public String getLabel() {
252 return parameters.getLabel();
253 }
254
255 /**
256 * Sets the label of the address.
257 * @param label the label or null to remove
258 */
259 public void setLabel(String label) {
260 parameters.setLabel(label);
261 }
262
263 /**
264 * Gets the global positioning coordinates that are associated with this
265 * address.
266 * <p>
267 * <b>Supported versions:</b> {@code 4.0}
268 * </p>
269 * @return the latitude (index 0) and longitude (index 1) or null if not set
270 * or null if the parameter value was in an incorrect format
271 * @see VCardParameters#getGeo
272 */
273 public double[] getGeo() {
274 return parameters.getGeo();
275 }
276
277 /**
278 * Sets the global positioning coordinates that are associated with this
279 * address.
280 * <p>
281 * <b>Supported versions:</b> {@code 4.0}
282 * </p>
283 * @param latitude the latitude
284 * @param longitude the longitude
285 * @see VCardParameters#setGeo
286 */
287 public void setGeo(double latitude, double longitude) {
288 parameters.setGeo(latitude, longitude);
289 }
290
291 @Override
292 public List<Integer[]> getPids() {
293 return super.getPids();
294 }
295
296 @Override
297 public void addPid(int localId, int clientPidMapRef) {
298 super.addPid(localId, clientPidMapRef);
299 }
300
301 @Override
302 public void removePids() {
303 super.removePids();
304 }
305
306 @Override
307 public Integer getPref() {
308 return super.getPref();
309 }
310
311 @Override
312 public void setPref(Integer pref) {
313 super.setPref(pref);
314 }
315
316 //@Override
317 public String getAltId() {
318 return parameters.getAltId();
319 }
320
321 //@Override
322 public void setAltId(String altId) {
323 parameters.setAltId(altId);
324 }
325
326 /**
327 * Gets the timezone that's associated with this address.
328 * <p>
329 * <b>Supported versions:</b> {@code 4.0}
330 * </p>
331 * @return the timezone (e.g. "America/New_York") or null if it doesn't
332 * exist
333 */
334 public String getTimezone() {
335 return parameters.getTimezone();
336 }
337
338 /**
339 * Sets the timezone that's associated with this address.
340 * <p>
341 * <b>Supported versions:</b> {@code 4.0}
342 * </p>
343 * @param timezone the timezone (e.g. "America/New_York") or null to remove
344 */
345 public void setTimezone(String timezone) {
346 parameters.setTimezone(timezone);
347 }
348
349 @Override
350 protected void _validate(List<Warning> warnings, VCardVersion version, VCard vcard) {
351 for (AddressType type : getTypes()) {
352 if (type == AddressType.PREF) {
353 //ignore because it is converted to a PREF parameter for 4.0 vCards
354 continue;
355 }
356
357 if (!type.isSupported(version)) {
358 warnings.add(new Warning(9, type.getValue()));
359 }
360 }
361 }
362 }