001 package ezvcard;
002
003 import java.io.File;
004 import java.io.IOException;
005 import java.io.OutputStream;
006 import java.io.Writer;
007 import java.util.ArrayList;
008 import java.util.Arrays;
009 import java.util.Collection;
010 import java.util.Date;
011 import java.util.HashSet;
012 import java.util.Iterator;
013 import java.util.List;
014 import java.util.Map;
015 import java.util.Set;
016
017 import javax.xml.transform.TransformerException;
018
019 import ezvcard.io.text.VCardWriter;
020 import ezvcard.parameter.EmailType;
021 import ezvcard.parameter.TelephoneType;
022 import ezvcard.parameter.VCardParameters;
023 import ezvcard.property.Address;
024 import ezvcard.property.Agent;
025 import ezvcard.property.Anniversary;
026 import ezvcard.property.Birthday;
027 import ezvcard.property.Birthplace;
028 import ezvcard.property.CalendarRequestUri;
029 import ezvcard.property.CalendarUri;
030 import ezvcard.property.Categories;
031 import ezvcard.property.Classification;
032 import ezvcard.property.ClientPidMap;
033 import ezvcard.property.Deathdate;
034 import ezvcard.property.Deathplace;
035 import ezvcard.property.Email;
036 import ezvcard.property.Expertise;
037 import ezvcard.property.FormattedName;
038 import ezvcard.property.FreeBusyUrl;
039 import ezvcard.property.Gender;
040 import ezvcard.property.Geo;
041 import ezvcard.property.HasAltId;
042 import ezvcard.property.Hobby;
043 import ezvcard.property.Impp;
044 import ezvcard.property.Interest;
045 import ezvcard.property.Key;
046 import ezvcard.property.Kind;
047 import ezvcard.property.Label;
048 import ezvcard.property.Language;
049 import ezvcard.property.Logo;
050 import ezvcard.property.Mailer;
051 import ezvcard.property.Member;
052 import ezvcard.property.Nickname;
053 import ezvcard.property.Note;
054 import ezvcard.property.OrgDirectory;
055 import ezvcard.property.Organization;
056 import ezvcard.property.Photo;
057 import ezvcard.property.ProductId;
058 import ezvcard.property.Profile;
059 import ezvcard.property.RawProperty;
060 import ezvcard.property.Related;
061 import ezvcard.property.Revision;
062 import ezvcard.property.Role;
063 import ezvcard.property.SortString;
064 import ezvcard.property.Sound;
065 import ezvcard.property.Source;
066 import ezvcard.property.SourceDisplayText;
067 import ezvcard.property.StructuredName;
068 import ezvcard.property.Telephone;
069 import ezvcard.property.Timezone;
070 import ezvcard.property.Title;
071 import ezvcard.property.Uid;
072 import ezvcard.property.Url;
073 import ezvcard.property.VCardProperty;
074 import ezvcard.property.Xml;
075 import ezvcard.util.ListMultimap;
076
077 /*
078 Copyright (c) 2013, Michael Angstadt
079 All rights reserved.
080
081 Redistribution and use in source and binary forms, with or without
082 modification, are permitted provided that the following conditions are met:
083
084 1. Redistributions of source code must retain the above copyright notice, this
085 list of conditions and the following disclaimer.
086 2. Redistributions in binary form must reproduce the above copyright notice,
087 this list of conditions and the following disclaimer in the documentation
088 and/or other materials provided with the distribution.
089
090 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
091 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
092 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
093 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
094 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
095 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
096 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
097 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
098 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
099 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
100
101 The views and conclusions contained in the software and documentation are those
102 of the authors and should not be interpreted as representing official policies,
103 either expressed or implied, of the FreeBSD Project.
104 */
105
106 /**
107 * Represents a vCard.
108 * @author Michael Angstadt
109 */
110 public class VCard implements Iterable<VCardProperty> {
111 private VCardVersion version = VCardVersion.V3_0;
112
113 private final ListMultimap<Class<? extends VCardProperty>, VCardProperty> properties = new ListMultimap<Class<? extends VCardProperty>, VCardProperty>();
114
115 /**
116 * <p>
117 * Marshals this vCard to its text representation.
118 * </p>
119 * <p>
120 * The vCard will be marshalled to whatever version is attached to this
121 * VCard object (see {@link #setVersion(VCardVersion)}). If no version is
122 * set, then it will be marshalled to 3.0.
123 * </p>
124 * <p>
125 * Use the {@link Ezvcard} class to customize the marshalling process and to
126 * write multiple vCards to the same stream.
127 * </p>
128 * @return the vCard string
129 * @see Ezvcard
130 * @see <a href="http://www.imc.org/pdi/vcard-21.rtf">vCard 2.1</a>
131 * @see <a href="http://tools.ietf.org/html/rfc2426">RFC 2426 (3.0)</a>
132 * @see <a href="http://tools.ietf.org/html/rfc6350">RFC 6350 (4.0)</a>
133 */
134 public String write() {
135 return Ezvcard.write(this).go();
136 }
137
138 /**
139 * <p>
140 * Marshals this vCard to its text representation.
141 * </p>
142 * <p>
143 * The vCard will be marshalled to whatever version is attached to this
144 * VCard object (see {@link #setVersion(VCardVersion)}). If no version is
145 * set, then it will be marshalled to 3.0.
146 * </p>
147 * <p>
148 * Use the {@link Ezvcard} class to customize the marshalling process and to
149 * write multiple vCards to the same stream.
150 * </p>
151 * @param file the file to write the vCard to
152 * @throws IOException if there's a problem writing to the file
153 * @see Ezvcard
154 * @see <a href="http://www.imc.org/pdi/vcard-21.rtf">vCard 2.1</a>
155 * @see <a href="http://tools.ietf.org/html/rfc2426">RFC 2426 (3.0)</a>
156 * @see <a href="http://tools.ietf.org/html/rfc6350">RFC 6350 (4.0)</a>
157 */
158 public void write(File file) throws IOException {
159 Ezvcard.write(this).go(file);
160 }
161
162 /**
163 * <p>
164 * Marshals this vCard to its text representation.
165 * </p>
166 * <p>
167 * The vCard will be marshalled to whatever version is attached to this
168 * VCard object (see {@link #setVersion(VCardVersion)}). If no version is
169 * set, then it will be marshalled to 3.0.
170 * </p>
171 * <p>
172 * Use the {@link Ezvcard} class to customize the marshalling process and to
173 * write multiple vCards to the same stream.
174 * </p>
175 * @param out the output stream to write the vCard to
176 * @see Ezvcard
177 * @throws IOException if there's a problem writing to the output stream
178 * @see <a href="http://www.imc.org/pdi/vcard-21.rtf">vCard 2.1</a>
179 * @see <a href="http://tools.ietf.org/html/rfc2426">RFC 2426 (3.0)</a>
180 * @see <a href="http://tools.ietf.org/html/rfc6350">RFC 6350 (4.0)</a>
181 */
182 public void write(OutputStream out) throws IOException {
183 Ezvcard.write(this).go(out);
184 }
185
186 /**
187 * <p>
188 * Marshals this vCard to its text representation.
189 * </p>
190 * <p>
191 * The vCard will be marshalled to whatever version is attached to this
192 * VCard object (see {@link #setVersion(VCardVersion)}). If no version is
193 * set, then it will be marshalled to 3.0.
194 * </p>
195 * <p>
196 * Use the {@link Ezvcard} class to customize the marshalling process and to
197 * write multiple vCards to the same stream.
198 * </p>
199 * @param writer the writer to write the vCard to
200 * @throws IOException if there's a problem writing to the writer
201 * @see Ezvcard
202 * @see <a href="http://www.imc.org/pdi/vcard-21.rtf">vCard 2.1</a>
203 * @see <a href="http://tools.ietf.org/html/rfc2426">RFC 2426 (3.0)</a>
204 * @see <a href="http://tools.ietf.org/html/rfc6350">RFC 6350 (4.0)</a>
205 */
206 public void write(Writer writer) throws IOException {
207 Ezvcard.write(this).go(writer);
208 }
209
210 /**
211 * <p>
212 * Marshals this vCard to its XML representation (xCard).
213 * </p>
214 * <p>
215 * Use the {@link Ezvcard} class to customize the marshalling process and to
216 * write multiple vCards to the same stream.
217 * </p>
218 * @return the vCard XML document
219 * @see Ezvcard
220 * @see <a href="http://tools.ietf.org/html/rfc6351">RFC 6351</a>
221 */
222 public String writeXml() {
223 return Ezvcard.writeXml(this).indent(2).go();
224 }
225
226 /**
227 * <p>
228 * Marshals this vCard to its XML representation (xCard).
229 * </p>
230 * <p>
231 * Use the {@link Ezvcard} class to customize the marshalling process and to
232 * write multiple vCards to the same stream.
233 * </p>
234 * @param file the file to write to
235 * @throws IOException if there's a problem writing to the file
236 * @throws TransformerException if there's a problem writing the vCard
237 * @see Ezvcard
238 * @see <a href="http://tools.ietf.org/html/rfc6351">RFC 6351</a>
239 */
240 public void writeXml(File file) throws IOException, TransformerException {
241 Ezvcard.writeXml(this).indent(2).go(file);
242 }
243
244 /**
245 * <p>
246 * Marshals this vCard to its XML representation (xCard).
247 * </p>
248 * <p>
249 * Use the {@link Ezvcard} class to customize the marshalling process and to
250 * write multiple vCards to the same stream.
251 * </p>
252 * @param out the output stream to write the vCard to
253 * @throws TransformerException if there's a problem writing to the output
254 * stream
255 * @see Ezvcard
256 * @see <a href="http://tools.ietf.org/html/rfc6351">RFC 6351</a>
257 */
258 public void writeXml(OutputStream out) throws TransformerException {
259 Ezvcard.writeXml(this).indent(2).go(out);
260 }
261
262 /**
263 * <p>
264 * Marshals this vCard to its XML representation (xCard).
265 * </p>
266 * <p>
267 * Use the {@link Ezvcard} class to customize the marshalling process and to
268 * write multiple vCards to the same stream.
269 * </p>
270 * @param writer the writer to write the vCard to
271 * @throws TransformerException if there's a problem writing to the writer
272 * @see Ezvcard
273 * @see <a href="http://tools.ietf.org/html/rfc6351">RFC 6351</a>
274 */
275 public void writeXml(Writer writer) throws TransformerException {
276 Ezvcard.writeXml(this).indent(2).go(writer);
277 }
278
279 /**
280 * <p>
281 * Marshals this vCard to a basic HTML page (hCard).
282 * </p>
283 * <p>
284 * Use the {@link Ezvcard} class to customize the marshalling process and to
285 * write multiple vCards to the same stream.
286 * </p>
287 * @return the HTML page
288 * @see Ezvcard
289 * @see <a href="http://microformats.org/wiki/hcard">hCard 1.0</a>
290 */
291 public String writeHtml() {
292 return Ezvcard.writeHtml(this).go();
293 }
294
295 /**
296 * <p>
297 * Marshals this vCard to a basic HTML page (hCard).
298 * </p>
299 * <p>
300 * Use the {@link Ezvcard} class to customize the marshalling process and to
301 * write multiple vCards to the same stream.
302 * </p>
303 * @param file the file to write to
304 * @throws IOException if there's a problem writing to the file
305 * @see Ezvcard
306 * @see <a href="http://microformats.org/wiki/hcard">hCard 1.0</a>
307 */
308 public void writeHtml(File file) throws IOException {
309 Ezvcard.writeHtml(this).go(file);
310 }
311
312 /**
313 * <p>
314 * Marshals this vCard to a basic HTML page (hCard).
315 * </p>
316 * <p>
317 * Use the {@link Ezvcard} class to customize the marshalling process and to
318 * write multiple vCards to the same stream.
319 * </p>
320 * @param out the output stream to write to
321 * @throws IOException if there's a problem writing to the output stream
322 * @see Ezvcard
323 * @see <a href="http://microformats.org/wiki/hcard">hCard 1.0</a>
324 */
325 public void writeHtml(OutputStream out) throws IOException {
326 Ezvcard.writeHtml(this).go(out);
327 }
328
329 /**
330 * <p>
331 * Marshals this vCard to a basic HTML page (hCard).
332 * </p>
333 * <p>
334 * Use the {@link Ezvcard} class to customize the marshalling process and to
335 * write multiple vCards to the same stream.
336 * </p>
337 * @param writer the writer to write to
338 * @throws IOException if there's a problem writing to the writer
339 * @see Ezvcard
340 * @see <a href="http://microformats.org/wiki/hcard">hCard 1.0</a>
341 */
342 public void writeHtml(Writer writer) throws IOException {
343 Ezvcard.writeHtml(this).go(writer);
344 }
345
346 /**
347 * <p>
348 * Marshals this vCard to its JSON representation (jCard).
349 * </p>
350 * <p>
351 * Use the {@link Ezvcard} class to customize the marshalling process and to
352 * write multiple vCards to the same stream.
353 * </p>
354 * @return the JSON string
355 * @see Ezvcard
356 * @see <a href="http://tools.ietf.org/html/rfc7095">RFC 7095</a>
357 */
358 public String writeJson() {
359 return Ezvcard.writeJson(this).go();
360 }
361
362 /**
363 * <p>
364 * Marshals this vCard to its JSON representation (jCard).
365 * </p>
366 * <p>
367 * Use the {@link Ezvcard} class to customize the marshalling process and to
368 * write multiple vCards to the same stream.
369 * </p>
370 * @param file the file to write the vCard to
371 * @throws IOException if there's a problem writing to the file
372 * @see Ezvcard
373 * @see <a href="http://tools.ietf.org/html/rfc7095">RFC 7095</a>
374 */
375 public void writeJson(File file) throws IOException {
376 Ezvcard.writeJson(this).go(file);
377 }
378
379 /**
380 * <p>
381 * Marshals this vCard to its JSON representation (jCard).
382 * </p>
383 * <p>
384 * Use the {@link Ezvcard} class to customize the marshalling process and to
385 * write multiple vCards to the same stream.
386 * </p>
387 * @param out the output stream to write the vCard to
388 * @see Ezvcard
389 * @throws IOException if there's a problem writing to the output stream
390 * @see <a href="http://tools.ietf.org/html/rfc7095">RFC 7095</a>
391 */
392 public void writeJson(OutputStream out) throws IOException {
393 Ezvcard.writeJson(this).go(out);
394 }
395
396 /**
397 * <p>
398 * Marshals this vCard to its JSON representation (jCard).
399 * </p>
400 * <p>
401 * Use the {@link Ezvcard} class to customize the marshalling process and to
402 * write multiple vCards to the same stream.
403 * </p>
404 * @param writer the writer to write the vCard to
405 * @throws IOException if there's a problem writing to the writer
406 * @see Ezvcard
407 * @see <a href="http://tools.ietf.org/html/rfc7095">RFC 7095</a>
408 */
409 public void writeJson(Writer writer) throws IOException {
410 Ezvcard.writeJson(this).go(writer);
411 }
412
413 /**
414 * Gets the version attached to this vCard.
415 * @return the vCard version
416 */
417 public VCardVersion getVersion() {
418 return version;
419 }
420
421 /**
422 * Sets the version of this vCard. When marshalling a vCard with the
423 * {@link VCardWriter} class, use the {@link VCardWriter#setTargetVersion
424 * setTargetVersion} method to define what version the vCard should be
425 * marshalled as. {@link VCardWriter} <b>does not</b> look at the version
426 * that is set on the VCard object.
427 * @param version the vCard version
428 */
429 public void setVersion(VCardVersion version) {
430 this.version = version;
431 }
432
433 /**
434 * Gets the type of entity this vCard represents.
435 * <p>
436 * <b>Property name:</b> {@code KIND}
437 * </p>
438 * <p>
439 * <b>Supported versions:</b> {@code 4.0}
440 * </p>
441 * @return the kind
442 */
443 public Kind getKind() {
444 return getProperty(Kind.class);
445 }
446
447 /**
448 * Sets the type of entity this vCard represents.
449 * <p>
450 * <b>Property name:</b> {@code KIND}
451 * </p>
452 * <p>
453 * <b>Supported versions:</b> {@code 4.0}
454 * </p>
455 * @param kind the kind
456 */
457 public void setKind(Kind kind) {
458 setProperty(Kind.class, kind);
459 }
460
461 /**
462 * Gets the gender of the person.
463 * <p>
464 * <b>Property name:</b> {@code GENDER}
465 * </p>
466 * <p>
467 * <b>Supported versions:</b> {@code 4.0}
468 * </p>
469 * @return the gender
470 */
471 public Gender getGender() {
472 return getProperty(Gender.class);
473 }
474
475 /**
476 * Sets the gender of the person.
477 * <p>
478 * <b>Property name:</b> {@code GENDER}
479 * </p>
480 * <p>
481 * <b>Supported versions:</b> {@code 4.0}
482 * </p>
483 * @param gender the gender
484 */
485 public void setGender(Gender gender) {
486 setProperty(Gender.class, gender);
487 }
488
489 /**
490 * Gets the members of the group. Only valid if the KIND property is set to
491 * "group".
492 *
493 * <p>
494 *
495 * <pre class="brush:java">
496 * VCard vcard = ...
497 * Kind kind = vcard.getKind();
498 * if (kind != null && kind.isGroup()){
499 * for (Member member : vcard.getMembers(){
500 * ...
501 * }
502 * }
503 * </pre>
504 *
505 * </p>
506 *
507 * <p>
508 * <b>Property name:</b> {@code MEMBER}
509 * </p>
510 * <p>
511 * <b>Supported versions:</b> {@code 4.0}
512 * </p>
513 * @return the members
514 */
515 public List<Member> getMembers() {
516 return getProperties(Member.class);
517 }
518
519 /**
520 * Adds a member to the group. Only valid if the KIND property is set to
521 * "group".
522 *
523 * <p>
524 *
525 * <pre class="brush:java">
526 * VCard vcard = new VCard();
527 * vcard.setKind(Kind.group());
528 * vcard.addMember(...);
529 * </pre>
530 *
531 * </p>
532 *
533 * <p>
534 * <b>Property name:</b> {@code MEMBER}
535 * </p>
536 * <p>
537 * <b>Supported versions:</b> {@code 4.0}
538 * </p>
539 * @param member the member to add
540 */
541 public void addMember(Member member) {
542 addProperty(member);
543 }
544
545 /**
546 * <p>
547 * Adds a member property as a group of alternative representations (see:
548 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
549 * ALTID parameter value is automatically generated and assigned to the
550 * properties.
551 * </p>
552 * <p>
553 * <b>Property name:</b> {@code MEMBER}
554 * </p>
555 * <p>
556 * <b>Supported versions:</b> {@code 4.0}
557 * </p>
558 * @param altRepresentations the alternative representations of the property
559 */
560 public void addMemberAlt(Collection<Member> altRepresentations) {
561 addPropertyAlt(Member.class, altRepresentations);
562 }
563
564 /**
565 * <p>
566 * Adds a member property as a group of alternative representations (see:
567 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
568 * ALTID parameter value is automatically generated and assigned to the
569 * properties.
570 * </p>
571 * <p>
572 * <b>Property name:</b> {@code MEMBER}
573 * </p>
574 * <p>
575 * <b>Supported versions:</b> {@code 4.0}
576 * </p>
577 * @param altRepresentations the alternative representations of the property
578 */
579 public void addMemberAlt(Member... altRepresentations) {
580 addPropertyAlt(Member.class, altRepresentations);
581 }
582
583 /**
584 * Gets the PROFILE property.
585 * <p>
586 * <b>Property name:</b> {@code PROFILE}
587 * </p>
588 * <p>
589 * <b>Supported versions:</b> {@code 3.0}
590 * </p>
591 * @return the property
592 */
593 public Profile getProfile() {
594 return getProperty(Profile.class);
595 }
596
597 /**
598 * Sets the PROFILE property.
599 * <p>
600 * <b>Property name:</b> {@code PROFILE}
601 * </p>
602 * <p>
603 * <b>Supported versions:</b> {@code 3.0}
604 * </p>
605 * @param profile the property
606 */
607 public void setProfile(Profile profile) {
608 setProperty(Profile.class, profile);
609 }
610
611 /**
612 * Gets the classification of the vCard, which describes the sensitivity of
613 * the information in the vCard.
614 * <p>
615 * <b>Property name:</b> {@code CLASS}
616 * </p>
617 * <p>
618 * <b>Supported versions:</b> {@code 3.0}
619 * </p>
620 * @return the classification
621 */
622 public Classification getClassification() {
623 return getProperty(Classification.class);
624 }
625
626 /**
627 * Sets the classification of the vCard, which describes the sensitivity of
628 * the information in the vCard.
629 * <p>
630 * <b>Property name:</b> {@code CLASS}
631 * </p>
632 * <p>
633 * <b>Supported versions:</b> {@code 3.0}
634 * </p>
635 * @param classification the classification
636 */
637 public void setClassification(Classification classification) {
638 setProperty(Classification.class, classification);
639 }
640
641 /**
642 * Sets the classification of the vCard, which describes the sensitivity of
643 * the information in the vCard. This is a convenience method for
644 * {@link #setClassification(Classification)}.
645 * <p>
646 * </p>
647 * <p>
648 * <b>Property name:</b> {@code CLASS}
649 * </p>
650 * <p>
651 * <b>Supported versions:</b> {@code 3.0}
652 * </p>
653 * @param classification the classification (e.g. "PUBLIC", "PRIVATE",
654 * "CONFIDENTIAL") or null to remove
655 * @return the property object that was created
656 */
657 public Classification setClassification(String classification) {
658 Classification type = null;
659 if (classification != null) {
660 type = new Classification(classification);
661 }
662 setClassification(type);
663 return type;
664 }
665
666 /**
667 * Gets the URIs that can be used to retrieve the most up-to-date version of
668 * the person's vCard.
669 * <p>
670 * <b>Property name:</b> {@code SOURCE}
671 * </p>
672 * <p>
673 * <b>Supported versions:</b> {@code 3.0, 4.0}
674 * </p>
675 * @return the sources
676 */
677 public List<Source> getSources() {
678 return getProperties(Source.class);
679 }
680
681 /**
682 * Adds a URI that can be used to retrieve the most up-to-date version of
683 * the person's vCard.
684 * <p>
685 * <b>Property name:</b> {@code SOURCE}
686 * </p>
687 * <p>
688 * <b>Supported versions:</b> {@code 3.0, 4.0}
689 * </p>
690 * @param source the source
691 */
692 public void addSource(Source source) {
693 addProperty(source);
694 }
695
696 /**
697 * Adds a URI that can be used to retrieve the most up-to-date version of
698 * the person's vCard. This is a convenience method for
699 * {@link #addSource(Source)} .
700 * <p>
701 * <b>Property name:</b> {@code SOURCE}
702 * </p>
703 * <p>
704 * <b>Supported versions:</b> {@code 3.0, 4.0}
705 * </p>
706 * @param source the source URI (e.g. "http://example.com/vcard.vcf")
707 * @return the property object that was created
708 */
709 public Source addSource(String source) {
710 Source type = new Source(source);
711 addSource(type);
712 return type;
713 }
714
715 /**
716 * <p>
717 * Adds a source property as a group of alternative representations (see:
718 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
719 * ALTID parameter value is automatically generated and assigned to the
720 * properties.
721 * </p>
722 * <p>
723 * <b>Property name:</b> {@code SOURCE}
724 * </p>
725 * <p>
726 * <b>Supported versions:</b> {@code 4.0*}<br>
727 * <i>* Only 4.0 supports alternative representations</i>
728 * </p>
729 * @param altRepresentations the alternative representations of the property
730 */
731 public void addSourceAlt(Collection<Source> altRepresentations) {
732 addPropertyAlt(Source.class, altRepresentations);
733 }
734
735 /**
736 * <p>
737 * Adds a source property as a group of alternative representations (see:
738 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
739 * ALTID parameter value is automatically generated and assigned to the
740 * properties.
741 * </p>
742 * <p>
743 * <b>Property name:</b> {@code SOURCE}
744 * </p>
745 * <p>
746 * <b>Supported versions:</b> {@code 4.0*}<br>
747 * <i>* Only 4.0 supports alternative representations</i>
748 * </p>
749 * @param altRepresentations the alternative representations of the property
750 */
751 public void addSourceAlt(Source... altRepresentations) {
752 addPropertyAlt(Source.class, altRepresentations);
753 }
754
755 /**
756 * Gets a textual representation of the SOURCE property.
757 * <p>
758 * <b>Property name:</b> {@code NAME}
759 * </p>
760 * <p>
761 * <b>Supported versions:</b> {@code 3.0}
762 * </p>
763 * @return a textual representation of the vCard source
764 */
765 public SourceDisplayText getSourceDisplayText() {
766 return getProperty(SourceDisplayText.class);
767 }
768
769 /**
770 * Sets a textual representation of the SOURCE property.
771 * <p>
772 * <b>Property name:</b> {@code NAME}
773 * </p>
774 * <p>
775 * <b>Supported versions:</b> {@code 3.0}
776 * </p>
777 * @param sourceDisplayText a textual representation of the vCard source
778 */
779 public void setSourceDisplayText(SourceDisplayText sourceDisplayText) {
780 setProperty(SourceDisplayText.class, sourceDisplayText);
781 }
782
783 /**
784 * Sets a textual representation of the SOURCE property. This is a
785 * convenience method for {@link #setSourceDisplayText(SourceDisplayText)}.
786 * <p>
787 * <b>Property name:</b> {@code NAME}
788 * </p>
789 * <p>
790 * <b>Supported versions:</b> {@code 3.0}
791 * </p>
792 * @param sourceDisplayText a textual representation of the vCard source or
793 * null to remove
794 * @return the property object that was created
795 */
796 public SourceDisplayText setSourceDisplayText(String sourceDisplayText) {
797 SourceDisplayText type = null;
798 if (sourceDisplayText != null) {
799 type = new SourceDisplayText(sourceDisplayText);
800 }
801 setSourceDisplayText(type);
802 return type;
803 }
804
805 /**
806 * <p>
807 * Gets all instances of the formatted name property. Version 4.0 vCards may
808 * have multiple instances if alternative representations are defined (see:
809 * {@link VCardParameters#getAltId description of ALTID}) or if properties
810 * with different TYPE parameters are defined.
811 * </p>
812 * <p>
813 * <b>Property name:</b> {@code FN}
814 * </p>
815 * <p>
816 * <b>Supported versions:</b> {@code 4.0*}<br>
817 * <i>* Only 4.0 supports multiple instances</i>
818 * </p>
819 * @return the formatted name properties
820 */
821 public List<FormattedName> getFormattedNames() {
822 return getProperties(FormattedName.class);
823 }
824
825 /**
826 * <p>
827 * Gets the text value used for displaying the person's name.
828 * </p>
829 * <p>
830 * <b>Property name:</b> {@code FN}
831 * </p>
832 * <p>
833 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
834 * </p>
835 * @return the formatted name property or null if one doesn't exist
836 */
837 public FormattedName getFormattedName() {
838 return getProperty(FormattedName.class);
839 }
840
841 /**
842 * <p>
843 * Sets the formatted name property as a group of alternative
844 * representations (see: {@link VCardParameters#getAltId description of
845 * ALTID} ). An appropriate ALTID parameter value is automatically generated
846 * and assigned to the properties.
847 * </p>
848 * <p>
849 * <b>Property name:</b> {@code FN}
850 * </p>
851 * <p>
852 * <b>Supported versions:</b> {@code 4.0*}<br>
853 * <i>* Only 4.0 supports alternative representations</i>
854 * </p>
855 * @param altRepresentations the alternative representations of the property
856 */
857 public void setFormattedNameAlt(Collection<FormattedName> altRepresentations) {
858 setPropertyAlt(FormattedName.class, altRepresentations);
859 }
860
861 /**
862 * <p>
863 * Sets the formatted name property as a group of alternative
864 * representations (see: {@link VCardParameters#getAltId description of
865 * ALTID} ). An appropriate ALTID parameter value is automatically generated
866 * and assigned to the properties.
867 * </p>
868 * <p>
869 * <b>Property name:</b> {@code FN}
870 * </p>
871 * <p>
872 * <b>Supported versions:</b> {@code 4.0*}<br>
873 * <i>* Only 4.0 supports alternative representations</i>
874 * </p>
875 * @param altRepresentations the alternative representations of the property
876 */
877 public void setFormattedNameAlt(FormattedName... altRepresentations) {
878 setPropertyAlt(FormattedName.class, altRepresentations);
879 }
880
881 /**
882 * <p>
883 * Adds a formatted name property as a group of alternative representations
884 * (see: {@link VCardParameters#getAltId description of ALTID}). An
885 * appropriate ALTID parameter value is automatically generated and assigned
886 * to the properties.
887 * </p>
888 * <p>
889 * <b>Property name:</b> {@code FN}
890 * </p>
891 * <p>
892 * <b>Supported versions:</b> {@code 4.0*}<br>
893 * <i>* Only 4.0 supports alternative representations</i>
894 * </p>
895 * @param altRepresentations the alternative representations of the property
896 */
897 public void addFormattedNameAlt(Collection<FormattedName> altRepresentations) {
898 addPropertyAlt(FormattedName.class, altRepresentations);
899 }
900
901 /**
902 * <p>
903 * Adds a formatted name property as a group of alternative representations
904 * (see: {@link VCardParameters#getAltId description of ALTID}). An
905 * appropriate ALTID parameter value is automatically generated and assigned
906 * to the properties.
907 * </p>
908 * <p>
909 * <b>Property name:</b> {@code FN}
910 * </p>
911 * <p>
912 * <b>Supported versions:</b> {@code 4.0*}<br>
913 * <i>* Only 4.0 supports alternative representations</i>
914 * </p>
915 * @param altRepresentations the alternative representations of the property
916 */
917 public void addFormattedNameAlt(FormattedName... altRepresentations) {
918 addPropertyAlt(FormattedName.class, altRepresentations);
919 }
920
921 /*
922 * Not going to add this method because if they are defining alternative
923 * representations, then they'll probably want to set parameters on each one
924 * (like "LANGUAGE").
925 *
926 * public void addFormattedName(String... altRepresentations) { }
927 */
928
929 /**
930 * <p>
931 * Sets the text value used for displaying the person's name.
932 * </p>
933 * <p>
934 * <b>Property name:</b> {@code FN}
935 * </p>
936 * <p>
937 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
938 * </p>
939 * @param formattedName the formatted name property or null to remove
940 */
941 public void setFormattedName(FormattedName formattedName) {
942 setProperty(FormattedName.class, formattedName);
943 }
944
945 /**
946 * <p>
947 * Adds a text value used for displaying the person's name. Note that only
948 * version 4.0 vCards support multiple instances of this property.
949 * </p>
950 * <p>
951 * <b>Property name:</b> {@code FN}
952 * </p>
953 * <p>
954 * <b>Supported versions:</b> {@code 4.0*}<br>
955 * <i>* Only 4.0 supports multiple instances</i>
956 * </p>
957 * @param formattedName the formatted name property
958 */
959 public void addFormattedName(FormattedName formattedName) {
960 addProperty(formattedName);
961 }
962
963 /**
964 * <p>
965 * Sets the text value used for displaying the person's name. This is a
966 * convenience method for {@link #setFormattedName(FormattedName)}.
967 * </p>
968 * <p>
969 * <b>Property name:</b> {@code FN}
970 * </p>
971 * <p>
972 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
973 * </p>
974 * @param formattedName the formatted name (e.g. "John Doe") or null to
975 * remove
976 * @return the property object that was created
977 */
978 public FormattedName setFormattedName(String formattedName) {
979 FormattedName type = null;
980 if (formattedName != null) {
981 type = new FormattedName(formattedName);
982 }
983 setFormattedName(type);
984 return type;
985 }
986
987 /**
988 * <p>
989 * Gets all structured name properties. Version 4.0 vCards may have multiple
990 * instances if alternative representations are defined (see:
991 * {@link VCardParameters#getAltId description of ALTID}).
992 * </p>
993 * <p>
994 * <b>Property name:</b> {@code N}
995 * </p>
996 * <p>
997 * <b>Supported versions:</b> {@code 4.0*}
998 * </p>
999 * <i>* Only 4.0 supports alternative representations</i>
1000 * @return the structured name property objects
1001 */
1002 public List<StructuredName> getStructuredNames() {
1003 return getProperties(StructuredName.class);
1004 }
1005
1006 /**
1007 * <p>
1008 * Gets the individual components of the person's name.
1009 * </p>
1010 * <p>
1011 * <b>Property name:</b> {@code N}
1012 * </p>
1013 * <p>
1014 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1015 * </p>
1016 * @return the components of the person's name
1017 */
1018 public StructuredName getStructuredName() {
1019 return getProperty(StructuredName.class);
1020 }
1021
1022 /**
1023 * <p>
1024 * Sets the structured name property as a group of alternative
1025 * representations (see {@link VCardParameters#getAltId} for more details).
1026 * An appropriate ALTID parameter value is automatically generated and
1027 * assigned to the properties.
1028 * </p>
1029 * <p>
1030 * <b>Property name:</b> {@code N}
1031 * </p>
1032 * <p>
1033 * <b>Supported versions:</b> {@code 4.0*}<br>
1034 * <i>* Only 4.0 supports alternative representations</i>
1035 * </p>
1036 * @param altRepresentations the alternative representations of the property
1037 */
1038 public void setStructuredNameAlt(Collection<StructuredName> altRepresentations) {
1039 setPropertyAlt(StructuredName.class, altRepresentations);
1040 }
1041
1042 /**
1043 * <p>
1044 * Sets the structured name property as a group of alternative
1045 * representations (see {@link VCardParameters#getAltId} for more details).
1046 * An appropriate ALTID parameter value is automatically generated and
1047 * assigned to the properties.
1048 * </p>
1049 * <p>
1050 * <b>Property name:</b> {@code N}
1051 * </p>
1052 * <p>
1053 * <b>Supported versions:</b> {@code 4.0*}<br>
1054 * <i>* Only 4.0 supports alternative representations</i>
1055 * </p>
1056 * @param altRepresentations the alternative representations of the property
1057 */
1058 public void setStructuredNameAlt(StructuredName... altRepresentations) {
1059 setPropertyAlt(StructuredName.class, altRepresentations);
1060 }
1061
1062 /**
1063 * Sets the individual components of the person's name.
1064 * <p>
1065 * <b>Property name:</b> {@code N}
1066 * </p>
1067 * <p>
1068 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1069 * </p>
1070 * @param structuredName the components of the person's name or null to
1071 * remove
1072 */
1073 public void setStructuredName(StructuredName structuredName) {
1074 setProperty(StructuredName.class, structuredName);
1075 }
1076
1077 /**
1078 * <p>
1079 * Gets all instances of the nickname property. Version 4.0 vCards may have
1080 * multiple instances if alternative representations are defined (see:
1081 * {@link VCardParameters#getAltId description of ALTID}) or if properties
1082 * with different TYPE parameters are defined.
1083 * </p>
1084 * <p>
1085 * <b>Property name:</b> {@code NICKNAME}
1086 * </p>
1087 * <p>
1088 * <b>Supported versions:</b> {@code 3.0, 4.0}
1089 * </p>
1090 * @return the nickname properties
1091 */
1092 public List<Nickname> getNicknames() {
1093 return getProperties(Nickname.class);
1094 }
1095
1096 /**
1097 * <p>
1098 * Gets the person's nicknames.
1099 * </p>
1100 * <p>
1101 * <b>Property name:</b> {@code NICKNAME}
1102 * </p>
1103 * <p>
1104 * <b>Supported versions:</b> {@code 3.0, 4.0}
1105 * </p>
1106 * @return the person's nicknames
1107 */
1108 public Nickname getNickname() {
1109 return getProperty(Nickname.class);
1110 }
1111
1112 /**
1113 * <p>
1114 * Sets the nickname property as a group of alternative representations
1115 * (see: {@link VCardParameters#getAltId description of ALTID}). An
1116 * appropriate ALTID parameter value is automatically generated and assigned
1117 * to the properties.
1118 * </p>
1119 * <p>
1120 * <b>Property name:</b> {@code NICKNAME}
1121 * </p>
1122 * <p>
1123 * <b>Supported versions:</b> {@code 4.0*}<br>
1124 * <i>* Only 4.0 supports alternative representations</i>
1125 * </p>
1126 * @param altRepresentations the alternative representations of the property
1127 */
1128 public void setNicknameAlt(Collection<Nickname> altRepresentations) {
1129 setPropertyAlt(Nickname.class, altRepresentations);
1130 }
1131
1132 /**
1133 * <p>
1134 * Sets the nickname property as a group of alternative representations
1135 * (see: {@link VCardParameters#getAltId description of ALTID}). An
1136 * appropriate ALTID parameter value is automatically generated and assigned
1137 * to the properties.
1138 * </p>
1139 * <p>
1140 * <b>Property name:</b> {@code NICKNAME}
1141 * </p>
1142 * <p>
1143 * <b>Supported versions:</b> {@code 4.0*}<br>
1144 * <i>* Only 4.0 supports alternative representations</i>
1145 * </p>
1146 * @param altRepresentations the alternative representations of the property
1147 */
1148 public void setNicknameAlt(Nickname... altRepresentations) {
1149 setPropertyAlt(Nickname.class, altRepresentations);
1150 }
1151
1152 /**
1153 * <p>
1154 * Adds a nickname property as a group of alternative representations (see:
1155 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1156 * ALTID parameter value is automatically generated and assigned to the
1157 * properties.
1158 * </p>
1159 * <p>
1160 * <b>Property name:</b> {@code NICKNAME}
1161 * </p>
1162 * <p>
1163 * <b>Supported versions:</b> {@code 4.0*}<br>
1164 * <i>* Only 4.0 supports alternative representations</i>
1165 * </p>
1166 * @param altRepresentations the alternative representations of the property
1167 */
1168 public void addNicknameAlt(Collection<Nickname> altRepresentations) {
1169 addPropertyAlt(Nickname.class, altRepresentations);
1170 }
1171
1172 /**
1173 * <p>
1174 * Adds a nickname property as a group of alternative representations (see:
1175 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1176 * ALTID parameter value is automatically generated and assigned to the
1177 * properties.
1178 * </p>
1179 * <p>
1180 * <b>Property name:</b> {@code NICKNAME}
1181 * </p>
1182 * <p>
1183 * <b>Supported versions:</b> {@code 4.0*}<br>
1184 * <i>* Only 4.0 supports alternative representations</i>
1185 * </p>
1186 * @param altRepresentations the alternative representations of the property
1187 */
1188 public void addNicknameAlt(Nickname... altRepresentations) {
1189 addPropertyAlt(Nickname.class, altRepresentations);
1190 }
1191
1192 /**
1193 * <p>
1194 * Sets the person's nickname(s).
1195 * </p>
1196 * <p>
1197 * <b>Property name:</b> {@code NICKNAME}
1198 * </p>
1199 * <p>
1200 * <b>Supported versions:</b> {@code 3.0, 4.0}
1201 * </p>
1202 * @param nickname the nickname property or null to remove (note that
1203 * multiple nicknames may be added this object)
1204 */
1205 public void setNickname(Nickname nickname) {
1206 setProperty(Nickname.class, nickname);
1207 }
1208
1209 /**
1210 * <p>
1211 * Adds a set of nicknames. Note that only version 4.0 vCards support
1212 * multiple instances of this property.
1213 * </p>
1214 * <p>
1215 * <b>Property name:</b> {@code NICKNAME}
1216 * </p>
1217 * <p>
1218 * <b>Supported versions:</b> {@code 4.0*}<br>
1219 * <i>* Only 4.0 supports multiple instances</i>
1220 * </p>
1221 * @param nickname the nickname property (note that multiple nicknames may
1222 * be added this object)
1223 */
1224 public void addNickname(Nickname nickname) {
1225 addProperty(nickname);
1226 }
1227
1228 /**
1229 * <p>
1230 * Sets the person's nicknames. This is a convenience method for
1231 * {@link #setNickname(Nickname)}.
1232 * </p>
1233 * <p>
1234 * <b>Property name:</b> {@code NICKNAME}
1235 * </p>
1236 * <p>
1237 * <b>Supported versions:</b> {@code 3.0, 4.0}
1238 * </p>
1239 * @param nicknames the nickname(s) (e.g. "Jonny") or null to remove
1240 * @return the property object that was created
1241 */
1242 public Nickname setNickname(String... nicknames) {
1243 Nickname type = null;
1244 if (nicknames != null) {
1245 type = new Nickname();
1246 for (String nickname : nicknames) {
1247 type.addValue(nickname);
1248 }
1249 }
1250 setNickname(type);
1251 return type;
1252 }
1253
1254 /**
1255 * <p>
1256 * Gets the string that should be used to sort the vCard.
1257 * </p>
1258 * <p>
1259 * For 4.0 vCards, use the {@link StructuredName#getSortAs} and/or
1260 * {@link Organization#getSortAs} methods.
1261 * </p>
1262 * <p>
1263 * <b>Property name:</b> {@code SORT-STRING}
1264 * </p>
1265 * <p>
1266 * <b>Supported versions:</b> {@code 2.1, 3.0}
1267 * </p>
1268 * @return the sort string
1269 */
1270 public SortString getSortString() {
1271 return getProperty(SortString.class);
1272 }
1273
1274 /**
1275 * <p>
1276 * Sets the string that should be used to sort the vCard.
1277 * </p>
1278 * <p>
1279 * For 4.0 vCards, use the {@link StructuredName#setSortAs} and/or
1280 * {@link Organization#setSortAs} methods.
1281 * </p>
1282 * <p>
1283 * <b>Property name:</b> {@code SORT-STRING}
1284 * </p>
1285 * <p>
1286 * <b>Supported versions:</b> {@code 2.1, 3.0}
1287 * </p>
1288 * @param sortString the sort string
1289 */
1290 public void setSortString(SortString sortString) {
1291 setProperty(SortString.class, sortString);
1292 }
1293
1294 /**
1295 * <p>
1296 * Sets the string that should be used to sort the vCard. This is a
1297 * convenience method for {@link #setSortString(SortString)}.
1298 * </p>
1299 * <p>
1300 * For 4.0 vCards, use the {@link StructuredName#setSortAs} and/or
1301 * {@link Organization#setSortAs} methods.
1302 * </p>
1303 * <p>
1304 * <b>Property name:</b> {@code SORT-STRING}
1305 * </p>
1306 * <p>
1307 * <b>Supported versions:</b> {@code 2.1, 3.0}
1308 * </p>
1309 * @param sortString the sort string (e.g. "Armour" if the person's last
1310 * name is "d'Armour") or null to remove
1311 * @return the property object that was created
1312 */
1313 public SortString setSortString(String sortString) {
1314 SortString type = null;
1315 if (sortString != null) {
1316 type = new SortString(sortString);
1317 }
1318 setSortString(type);
1319 return type;
1320 }
1321
1322 /**
1323 * Gets the titles associated with the person.
1324 * <p>
1325 * <b>Property name:</b> {@code TITLE}
1326 * </p>
1327 * <p>
1328 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1329 * </p>
1330 * @return the titles
1331 */
1332 public List<Title> getTitles() {
1333 return getProperties(Title.class);
1334 }
1335
1336 /**
1337 * Adds a title associated with the person.
1338 * <p>
1339 * <b>Property name:</b> {@code TITLE}
1340 * </p>
1341 * <p>
1342 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1343 * </p>
1344 * @param title the title
1345 */
1346 public void addTitle(Title title) {
1347 addProperty(title);
1348 }
1349
1350 /**
1351 * Adds a title associated with the person. This is a convenience method for
1352 * {@link #addTitle(Title)}.
1353 * <p>
1354 * <b>Property name:</b> {@code TITLE}
1355 * </p>
1356 * <p>
1357 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1358 * </p>
1359 * @param title the title (e.g. "V.P. Research and Development")
1360 * @return the property object that was created
1361 */
1362 public Title addTitle(String title) {
1363 Title type = new Title(title);
1364 addTitle(type);
1365 return type;
1366 }
1367
1368 /**
1369 * <p>
1370 * Adds a title property as a group of alternative representations (see:
1371 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1372 * ALTID parameter value is automatically generated and assigned to the
1373 * properties.
1374 * </p>
1375 * <p>
1376 * <b>Property name:</b> {@code TITLE}
1377 * </p>
1378 * <p>
1379 * <b>Supported versions:</b> {@code 4.0*}<br>
1380 * <i>* Only 4.0 supports alternative representations</i>
1381 * </p>
1382 * @param altRepresentations the alternative representations of the property
1383 */
1384 public void addTitleAlt(Collection<Title> altRepresentations) {
1385 addPropertyAlt(Title.class, altRepresentations);
1386 }
1387
1388 /**
1389 * <p>
1390 * Adds a title property as a group of alternative representations (see:
1391 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1392 * ALTID parameter value is automatically generated and assigned to the
1393 * properties.
1394 * </p>
1395 * <p>
1396 * <b>Property name:</b> {@code TITLE}
1397 * </p>
1398 * <p>
1399 * <b>Supported versions:</b> {@code 4.0*}<br>
1400 * <i>* Only 4.0 supports alternative representations</i>
1401 * </p>
1402 * @param altRepresentations the alternative representations of the property
1403 */
1404 public void addTitleAlt(Title... altRepresentations) {
1405 addPropertyAlt(Title.class, altRepresentations);
1406 }
1407
1408 /**
1409 * Gets the roles associated with the person.
1410 * <p>
1411 * <b>Property name:</b> {@code ROLE}
1412 * </p>
1413 * <p>
1414 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1415 * </p>
1416 * @return the roles
1417 */
1418 public List<Role> getRoles() {
1419 return getProperties(Role.class);
1420 }
1421
1422 /**
1423 * Adds a role associated with the person.
1424 * <p>
1425 * <b>Property name:</b> {@code ROLE}
1426 * </p>
1427 * <p>
1428 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1429 * </p>
1430 * @param role the role
1431 */
1432 public void addRole(Role role) {
1433 addProperty(role);
1434 }
1435
1436 /**
1437 * Adds a role associated with the person. This is a convenience method for
1438 * {@link #addRole(Role)}.
1439 * <p>
1440 * <b>Property name:</b> {@code ROLE}
1441 * </p>
1442 * <p>
1443 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1444 * </p>
1445 * @param role the role (e.g. "Executive")
1446 * @return the property object that was created
1447 */
1448 public Role addRole(String role) {
1449 Role type = new Role(role);
1450 addRole(type);
1451 return type;
1452 }
1453
1454 /**
1455 * <p>
1456 * Adds a role property as a group of alternative representations (see:
1457 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1458 * ALTID parameter value is automatically generated and assigned to the
1459 * properties.
1460 * </p>
1461 * <p>
1462 * <b>Property name:</b> {@code ROLE}
1463 * </p>
1464 * <p>
1465 * <b>Supported versions:</b> {@code 4.0*}<br>
1466 * <i>* Only 4.0 supports alternative representations</i>
1467 * </p>
1468 * @param altRepresentations the alternative representations of the property
1469 */
1470 public void addRoleAlt(Collection<Role> altRepresentations) {
1471 addPropertyAlt(Role.class, altRepresentations);
1472 }
1473
1474 /**
1475 * <p>
1476 * Adds a role property as a group of alternative representations (see:
1477 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1478 * ALTID parameter value is automatically generated and assigned to the
1479 * properties.
1480 * </p>
1481 * <p>
1482 * <b>Property name:</b> {@code ROLE}
1483 * </p>
1484 * <p>
1485 * <b>Supported versions:</b> {@code 4.0*}<br>
1486 * <i>* Only 4.0 supports alternative representations</i>
1487 * </p>
1488 * @param altRepresentations the alternative representations of the property
1489 */
1490 public void addRoleAlt(Role... altRepresentations) {
1491 addPropertyAlt(Role.class, altRepresentations);
1492 }
1493
1494 /**
1495 * Gets the photos attached to the vCard, such as a picture of the person's
1496 * face.
1497 * <p>
1498 * <b>Property name:</b> {@code PHOTO}
1499 * </p>
1500 * <p>
1501 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1502 * </p>
1503 * @return the photos
1504 */
1505 public List<Photo> getPhotos() {
1506 return getProperties(Photo.class);
1507 }
1508
1509 /**
1510 * Adds a photo to the vCard, such as a picture of the person's face.
1511 * <p>
1512 * <b>Property name:</b> {@code PHOTO}
1513 * </p>
1514 * <p>
1515 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1516 * </p>
1517 * @param photo the photo to add
1518 */
1519 public void addPhoto(Photo photo) {
1520 addProperty(photo);
1521 }
1522
1523 /**
1524 * <p>
1525 * Adds a photo property as a group of alternative representations (see:
1526 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1527 * ALTID parameter value is automatically generated and assigned to the
1528 * properties.
1529 * </p>
1530 * <p>
1531 * <b>Property name:</b> {@code FN}
1532 * </p>
1533 * <p>
1534 * <b>Supported versions:</b> {@code 4.0*}<br>
1535 * <i>* Only 4.0 supports alternative representations</i>
1536 * </p>
1537 * @param altRepresentations the alternative representations of the property
1538 */
1539 public void addPhotoAlt(Collection<Photo> altRepresentations) {
1540 addPropertyAlt(Photo.class, altRepresentations);
1541 }
1542
1543 /**
1544 * <p>
1545 * Adds a photo property as a group of alternative representations (see:
1546 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1547 * ALTID parameter value is automatically generated and assigned to the
1548 * properties.
1549 * </p>
1550 * <p>
1551 * <b>Property name:</b> {@code FN}
1552 * </p>
1553 * <p>
1554 * <b>Supported versions:</b> {@code 4.0*}<br>
1555 * <i>* Only 4.0 supports alternative representations</i>
1556 * </p>
1557 * @param altRepresentations the alternative representations of the property
1558 */
1559 public void addPhotoAlt(Photo... altRepresentations) {
1560 addPropertyAlt(Photo.class, altRepresentations);
1561 }
1562
1563 /**
1564 * Gets the logos attached to the vCard, such a company logo.
1565 * <p>
1566 * <b>Property name:</b> {@code LOGO}
1567 * </p>
1568 * <p>
1569 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1570 * </p>
1571 * @return the logos
1572 */
1573 public List<Logo> getLogos() {
1574 return getProperties(Logo.class);
1575 }
1576
1577 /**
1578 * Adds a logo to the vCard, such as a company logo.
1579 * <p>
1580 * <b>Property name:</b> {@code LOGO}
1581 * </p>
1582 * <p>
1583 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1584 * </p>
1585 * @param logo the logo to add
1586 */
1587 public void addLogo(Logo logo) {
1588 addProperty(logo);
1589 }
1590
1591 /**
1592 * <p>
1593 * Adds a logo property as a group of alternative representations (see:
1594 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1595 * ALTID parameter value is automatically generated and assigned to the
1596 * properties.
1597 * </p>
1598 * <p>
1599 * <b>Property name:</b> {@code LOGO}
1600 * </p>
1601 * <p>
1602 * <b>Supported versions:</b> {@code 4.0*}<br>
1603 * <i>* Only 4.0 supports alternative representations</i>
1604 * </p>
1605 * @param altRepresentations the alternative representations of the property
1606 */
1607 public void addLogoAlt(Collection<Logo> altRepresentations) {
1608 addPropertyAlt(Logo.class, altRepresentations);
1609 }
1610
1611 /**
1612 * <p>
1613 * Adds a logo property as a group of alternative representations (see:
1614 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1615 * ALTID parameter value is automatically generated and assigned to the
1616 * properties.
1617 * </p>
1618 * <p>
1619 * <b>Property name:</b> {@code LOGO}
1620 * </p>
1621 * <p>
1622 * <b>Supported versions:</b> {@code 4.0*}<br>
1623 * <i>* Only 4.0 supports alternative representations</i>
1624 * </p>
1625 * @param altRepresentations the alternative representations of the property
1626 */
1627 public void addLogoAlt(Logo... altRepresentations) {
1628 addPropertyAlt(Logo.class, altRepresentations);
1629 }
1630
1631 /**
1632 * Gets the sounds attached to the vCard, such as a pronunciation of the
1633 * person's name.
1634 * <p>
1635 * <b>Property name:</b> {@code SOUND}
1636 * </p>
1637 * <p>
1638 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1639 * </p>
1640 * @return the sounds
1641 */
1642 public List<Sound> getSounds() {
1643 return getProperties(Sound.class);
1644 }
1645
1646 /**
1647 * Adds a sound to the vCard, such as a pronunciation of the person's name.
1648 * <p>
1649 * <b>Property name:</b> {@code SOUND}
1650 * </p>
1651 * <p>
1652 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
1653 * </p>
1654 * @param sound the sound to add
1655 */
1656 public void addSound(Sound sound) {
1657 addProperty(sound);
1658 }
1659
1660 /**
1661 * <p>
1662 * Adds a sound property as a group of alternative representations (see:
1663 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1664 * ALTID parameter value is automatically generated and assigned to the
1665 * properties.
1666 * </p>
1667 * <p>
1668 * <b>Property name:</b> {@code FN}
1669 * </p>
1670 * <p>
1671 * <b>Supported versions:</b> {@code 4.0*}<br>
1672 * <i>* Only 4.0 supports alternative representations</i>
1673 * </p>
1674 * @param altRepresentations the alternative representations of the property
1675 */
1676 public void addSoundAlt(Collection<Sound> altRepresentations) {
1677 addPropertyAlt(Sound.class, altRepresentations);
1678 }
1679
1680 /**
1681 * <p>
1682 * Adds a sound property as a group of alternative representations (see:
1683 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
1684 * ALTID parameter value is automatically generated and assigned to the
1685 * properties.
1686 * </p>
1687 * <p>
1688 * <b>Property name:</b> {@code FN}
1689 * </p>
1690 * <p>
1691 * <b>Supported versions:</b> {@code 4.0*}<br>
1692 * <i>* Only 4.0 supports alternative representations</i>
1693 * </p>
1694 * @param altRepresentations the alternative representations of the property
1695 */
1696 public void addSoundAlt(Sound... altRepresentations) {
1697 addPropertyAlt(Sound.class, altRepresentations);
1698 }
1699
1700 /**
1701 * <p>
1702 * Gets all birthplace property instances. There may be multiple instances
1703 * if alternative representations are defined (see:
1704 * {@link VCardParameters#getAltId description of ALTID}).
1705 * </p>
1706 * <p>
1707 * <b>Property name:</b> {@code BIRTHPLACE}
1708 * </p>
1709 * <p>
1710 * <b>Supported versions:</b> {@code 4.0}
1711 * </p>
1712 * @return the birthplace properties
1713 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1714 */
1715 public List<Birthplace> getBirthplaces() {
1716 return getProperties(Birthplace.class);
1717 }
1718
1719 /**
1720 * <p>
1721 * Gets the person's birthplace.
1722 * </p>
1723 * <p>
1724 * <b>Property name:</b> {@code BIRTHPLACE}
1725 * </p>
1726 * <p>
1727 * <b>Supported versions:</b> {@code 4.0}
1728 * </p>
1729 * @return the birthplace or null if one doesn't exist
1730 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1731 */
1732 public Birthplace getBirthplace() {
1733 return getProperty(Birthplace.class);
1734 }
1735
1736 /**
1737 * <p>
1738 * Sets the person's birthplace as a group of alternative representations
1739 * (see: {@link VCardParameters#getAltId description of ALTID}. An
1740 * appropriate ALTID parameter value is automatically generated and assigned
1741 * to the properties.
1742 * </p>
1743 * <p>
1744 * <b>Property name:</b> {@code BIRTHPLACE}
1745 * </p>
1746 * <p>
1747 * <b>Supported versions:</b> {@code 4.0}
1748 * </p>
1749 * @param altRepresentations the alternative representations of the property
1750 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1751 */
1752 public void setBirthplaceAlt(Collection<Birthplace> altRepresentations) {
1753 setPropertyAlt(Birthplace.class, altRepresentations);
1754 }
1755
1756 /**
1757 * <p>
1758 * Sets the person's birthplace as a group of alternative representations
1759 * (see: {@link VCardParameters#getAltId description of ALTID}. An
1760 * appropriate ALTID parameter value is automatically generated and assigned
1761 * to the properties.
1762 * </p>
1763 * <p>
1764 * <b>Property name:</b> {@code BIRTHPLACE}
1765 * </p>
1766 * <p>
1767 * <b>Supported versions:</b> {@code 4.0}
1768 * </p>
1769 * @param altRepresentations the alternative representations of the property
1770 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1771 */
1772 public void setBirthplaceAlt(Birthplace... altRepresentations) {
1773 setPropertyAlt(Birthplace.class, altRepresentations);
1774 }
1775
1776 /**
1777 * <p>
1778 * Sets the person's birthplace.
1779 * </p>
1780 * <p>
1781 * <b>Property name:</b> {@code BIRTHPLACE}
1782 * </p>
1783 * <p>
1784 * <b>Supported versions:</b> {@code 4.0}
1785 * </p>
1786 * @param birthplace the birthplace or null to remove
1787 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1788 */
1789 public void setBirthplace(Birthplace birthplace) {
1790 setProperty(Birthplace.class, birthplace);
1791 }
1792
1793 /**
1794 * <p>
1795 * Gets all deathplace property instances. There may be multiple instances
1796 * if alternative representations are defined (see:
1797 * {@link VCardParameters#getAltId description of ALTID}).
1798 * </p>
1799 * <p>
1800 * <b>Property name:</b> {@code DEATHPLACE}
1801 * </p>
1802 * <p>
1803 * <b>Supported versions:</b> {@code 4.0}
1804 * </p>
1805 * @return the deathplace properties
1806 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1807 */
1808 public List<Deathplace> getDeathplaces() {
1809 return getProperties(Deathplace.class);
1810 }
1811
1812 /**
1813 * <p>
1814 * Gets the person's deathplace.
1815 * </p>
1816 * <p>
1817 * <b>Property name:</b> {@code DEATHPLACE}
1818 * </p>
1819 * <p>
1820 * <b>Supported versions:</b> {@code 4.0}
1821 * </p>
1822 * @return the deathplace or null if one doesn't exist
1823 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1824 */
1825 public Deathplace getDeathplace() {
1826 return getProperty(Deathplace.class);
1827 }
1828
1829 /**
1830 * <p>
1831 * Sets the person's deathplace as a group of alternative representations
1832 * (see {@link VCardParameters#getAltId} for more details). An appropriate
1833 * ALTID parameter value is automatically generated and assigned to the
1834 * properties.
1835 * </p>
1836 * <p>
1837 * <b>Property name:</b> {@code DEATHPLACE}
1838 * </p>
1839 * <p>
1840 * <b>Supported versions:</b> {@code 4.0}
1841 * </p>
1842 * @param altRepresentations the alternative representations of the property
1843 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1844 */
1845 public void setDeathplaceAlt(Collection<Deathplace> altRepresentations) {
1846 setPropertyAlt(Deathplace.class, altRepresentations);
1847 }
1848
1849 /**
1850 * <p>
1851 * Sets the person's deathplace as a group of alternative representations
1852 * (see {@link VCardParameters#getAltId} for more details). An appropriate
1853 * ALTID parameter value is automatically generated and assigned to the
1854 * properties.
1855 * </p>
1856 * <p>
1857 * <b>Property name:</b> {@code DEATHPLACE}
1858 * </p>
1859 * <p>
1860 * <b>Supported versions:</b> {@code 4.0}
1861 * </p>
1862 * @param altRepresentations the alternative representations of the property
1863 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1864 */
1865 public void setDeathplaceAlt(Deathplace... altRepresentations) {
1866 setPropertyAlt(Deathplace.class, altRepresentations);
1867 }
1868
1869 /**
1870 * <p>
1871 * Sets the person's deathplace.
1872 * </p>
1873 * <p>
1874 * <b>Property name:</b> {@code DEATHPLACE}
1875 * </p>
1876 * <p>
1877 * <b>Supported versions:</b> {@code 4.0}
1878 * </p>
1879 * @param deathplace the deathplace or null to remove
1880 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1881 */
1882 public void setDeathplace(Deathplace deathplace) {
1883 setProperty(Deathplace.class, deathplace);
1884 }
1885
1886 /**
1887 * <p>
1888 * Gets all death date property instances. There may be multiple instances
1889 * if alternative representations are defined (see:
1890 * {@link VCardParameters#getAltId description of ALTID}).
1891 * </p>
1892 * <p>
1893 * <b>Property name:</b> {@code DEATHDATE}
1894 * </p>
1895 * <p>
1896 * <b>Supported versions:</b> {@code 4.0}
1897 * </p>
1898 * @return the death date properties
1899 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1900 */
1901 public List<Deathdate> getDeathdates() {
1902 return getProperties(Deathdate.class);
1903 }
1904
1905 /**
1906 * <p>
1907 * Gets the person's time of death.
1908 * </p>
1909 * <p>
1910 * <b>Property name:</b> {@code DEATHDATE}
1911 * </p>
1912 * <p>
1913 * <b>Supported versions:</b> {@code 4.0}
1914 * </p>
1915 * @return the time of death or null if one doesn't exist
1916 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1917 */
1918 public Deathdate getDeathdate() {
1919 return getProperty(Deathdate.class);
1920 }
1921
1922 /**
1923 * <p>
1924 * Sets the deathdate property as a group of alternative representations
1925 * (see: {@link VCardParameters#getAltId description of ALTID}). An
1926 * appropriate ALTID parameter value is automatically generated and assigned
1927 * to the properties.
1928 * </p>
1929 * <p>
1930 * <b>Property name:</b> {@code DEATHDATE}
1931 * </p>
1932 * <p>
1933 * <b>Supported versions:</b> {@code 4.0}
1934 * </p>
1935 * @param altRepresentations the alternative representations of the property
1936 */
1937 public void setDeathdateAlt(Collection<Deathdate> altRepresentations) {
1938 setPropertyAlt(Deathdate.class, altRepresentations);
1939 }
1940
1941 /**
1942 * <p>
1943 * Sets the deathdate property as a group of alternative representations
1944 * (see: {@link VCardParameters#getAltId description of ALTID}). An
1945 * appropriate ALTID parameter value is automatically generated and assigned
1946 * to the properties.
1947 * </p>
1948 * <p>
1949 * <b>Property name:</b> {@code DEATHDATE}
1950 * </p>
1951 * <p>
1952 * <b>Supported versions:</b> {@code 4.0}
1953 * </p>
1954 * @param altRepresentations the alternative representations of the property
1955 */
1956 public void setDeathdateAlt(Deathdate... altRepresentations) {
1957 setPropertyAlt(Deathdate.class, altRepresentations);
1958 }
1959
1960 /**
1961 * <p>
1962 * Sets the person's time of death.
1963 * </p>
1964 * <p>
1965 * <b>Property name:</b> {@code DEATHDATE}
1966 * </p>
1967 * <p>
1968 * <b>Supported versions:</b> {@code 4.0}
1969 * </p>
1970 * @param deathdate the time of death or null to remove
1971 * @see <a href="http://tools.ietf.org/html/rfc6474">RFC 6474</a>
1972 */
1973 public void setDeathdate(Deathdate deathdate) {
1974 setProperty(Deathdate.class, deathdate);
1975 }
1976
1977 /**
1978 * <p>
1979 * Gets all birthday property instances. Version 4.0 vCards may have
1980 * multiple instances if alternative representations are defined (see:
1981 * {@link VCardParameters#getAltId description of ALTID}).
1982 * </p>
1983 * <p>
1984 * <b>Property name:</b> {@code BDAY}
1985 * </p>
1986 * <p>
1987 * <b>Supported versions:</b> {@code 4.0*}<br>
1988 * <i>* Only 4.0 supports alternative representations</i>
1989 * </p>
1990 * @return the birthday properties
1991 */
1992 public List<Birthday> getBirthdays() {
1993 return getProperties(Birthday.class);
1994 }
1995
1996 /**
1997 * <p>
1998 * Gets the person's birthday.
1999 * </p>
2000 * <p>
2001 * <b>Property name:</b> {@code BDAY}
2002 * </p>
2003 * <p>
2004 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2005 * </p>
2006 * @return the birthday
2007 */
2008 public Birthday getBirthday() {
2009 return getProperty(Birthday.class);
2010 }
2011
2012 /**
2013 * <p>
2014 * Sets the person's birthday as a group of alternative representations
2015 * (see: {@link VCardParameters#getAltId description of ALTID}). An
2016 * appropriate ALTID parameter value is automatically generated and assigned
2017 * to the properties.
2018 * </p>
2019 * <p>
2020 * <b>Property name:</b> {@code BDAY}
2021 * </p>
2022 * <p>
2023 * <b>Supported versions:</b> {@code 4.0*}<br>
2024 * <i>* Only 4.0 supports alternative representations</i>
2025 * </p>
2026 * @param altRepresentations the alternative representations of the property
2027 */
2028 public void setBirthdayAlt(Collection<Birthday> altRepresentations) {
2029 setPropertyAlt(Birthday.class, altRepresentations);
2030 }
2031
2032 /**
2033 * <p>
2034 * Sets the person's birthday as a group of alternative representations
2035 * (see: {@link VCardParameters#getAltId description of ALTID}). An
2036 * appropriate ALTID parameter value is automatically generated and assigned
2037 * to the properties.
2038 * </p>
2039 * <p>
2040 * <b>Property name:</b> {@code BDAY}
2041 * </p>
2042 * <p>
2043 * <b>Supported versions:</b> {@code 4.0*}<br>
2044 * <i>* Only 4.0 supports alternative representations</i>
2045 * </p>
2046 * @param altRepresentations the alternative representations of the property
2047 */
2048 public void setBirthdayAlt(Birthday... altRepresentations) {
2049 setPropertyAlt(Birthday.class, altRepresentations);
2050 }
2051
2052 /**
2053 * <p>
2054 * Sets the person's birthday.
2055 * </p>
2056 * <p>
2057 * <b>Property name:</b> {@code BDAY}
2058 * </p>
2059 * <p>
2060 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2061 * </p>
2062 * @param birthday the birthday or null to remove
2063 */
2064 public void setBirthday(Birthday birthday) {
2065 setProperty(Birthday.class, birthday);
2066 }
2067
2068 /**
2069 * <p>
2070 * Gets all anniversary property instances. There may be multiple instances
2071 * if alternative representations are defined (see:
2072 * {@link VCardParameters#getAltId description of ALTID}).
2073 * </p>
2074 * <p>
2075 * <b>Property name:</b> {@code ANNIVERSARY}
2076 * </p>
2077 * <p>
2078 * <b>Supported versions:</b> {@code 4.0}
2079 * </p>
2080 * @return the anniversary properties
2081 */
2082 public List<Anniversary> getAnniversaries() {
2083 return getProperties(Anniversary.class);
2084 }
2085
2086 /**
2087 * <p>
2088 * Gets the person's anniversary.
2089 * </p>
2090 * <p>
2091 * <b>Property name:</b> {@code ANNIVERSARY}
2092 * </p>
2093 * <p>
2094 * <b>Supported versions:</b> {@code 4.0}
2095 * </p>
2096 * @return the anniversary
2097 */
2098 public Anniversary getAnniversary() {
2099 return getProperty(Anniversary.class);
2100 }
2101
2102 /**
2103 * <p>
2104 * Sets the person's anniversary as a group of alternative representations
2105 * (see {@link VCardParameters#getAltId} for more details). An appropriate
2106 * ALTID parameter value is automatically generated and assigned to the
2107 * properties.
2108 * </p>
2109 * <p>
2110 * <b>Property name:</b> {@code ANNIVERSARY}
2111 * </p>
2112 * <p>
2113 * <b>Supported versions:</b> {@code 4.0}
2114 * </p>
2115 * @param altRepresentations the alternative representations of the property
2116 */
2117 public void setAnniversaryAlt(Collection<Anniversary> altRepresentations) {
2118 setPropertyAlt(Anniversary.class, altRepresentations);
2119 }
2120
2121 /**
2122 * <p>
2123 * Sets the person's anniversary as a group of alternative representations
2124 * (see {@link VCardParameters#getAltId} for more details). An appropriate
2125 * ALTID parameter value is automatically generated and assigned to the
2126 * properties.
2127 * </p>
2128 * <p>
2129 * <b>Property name:</b> {@code ANNIVERSARY}
2130 * </p>
2131 * <p>
2132 * <b>Supported versions:</b> {@code 4.0}
2133 * </p>
2134 * @param altRepresentations the alternative representations of the property
2135 */
2136 public void setAnniversaryAlt(Anniversary... altRepresentations) {
2137 setPropertyAlt(Anniversary.class, altRepresentations);
2138 }
2139
2140 /**
2141 * <p>
2142 * Sets the person's anniversary.
2143 * </p>
2144 * <p>
2145 * <b>Property name:</b> {@code ANNIVERSARY}
2146 * </p>
2147 * <p>
2148 * <b>Supported versions:</b> {@code 4.0}
2149 * </p>
2150 * @param anniversary the anniversary or null to remove
2151 */
2152 public void setAnniversary(Anniversary anniversary) {
2153 setProperty(Anniversary.class, anniversary);
2154 }
2155
2156 /**
2157 * Gets the time that the vCard was last modified.
2158 * <p>
2159 * <b>Property name:</b> {@code REV}
2160 * </p>
2161 * <p>
2162 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2163 * </p>
2164 * @return the last modified time
2165 */
2166 public Revision getRevision() {
2167 return getProperty(Revision.class);
2168 }
2169
2170 /**
2171 * Sets the time that the vCard was last modified.
2172 * <p>
2173 * <b>Property name:</b> {@code REV}
2174 * </p>
2175 * <p>
2176 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2177 * </p>
2178 * @param rev the last modified time
2179 */
2180 public void setRevision(Revision rev) {
2181 setProperty(Revision.class, rev);
2182 }
2183
2184 /**
2185 * Sets the time that the vCard was last modified. This is a convenience
2186 * method for {@link #setRevision(Revision)}.
2187 * <p>
2188 * <b>Property name:</b> {@code REV}
2189 * </p>
2190 * <p>
2191 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2192 * </p>
2193 * @param rev the last modified time or null to remove
2194 * @return the property object that was created
2195 */
2196 public Revision setRevision(Date rev) {
2197 Revision type = null;
2198 if (rev != null) {
2199 type = new Revision(rev);
2200 }
2201 setRevision(type);
2202 return type;
2203 }
2204
2205 /**
2206 * Gets the product ID, which identifies the software that created the
2207 * vCard.
2208 * <p>
2209 * <b>Property name:</b> {@code PRODID}
2210 * </p>
2211 * <p>
2212 * <b>Supported versions:</b> {@code 3.0, 4.0}
2213 * </p>
2214 * @return the product ID
2215 */
2216 public ProductId getProdId() {
2217 return getProperty(ProductId.class);
2218 }
2219
2220 /**
2221 * Sets the product ID, which identifies the software that created the
2222 * vCard.
2223 * <p>
2224 * <b>Property name:</b> {@code PRODID}
2225 * </p>
2226 * <p>
2227 * <b>Supported versions:</b> {@code 3.0, 4.0}
2228 * </p>
2229 * @param prodId the product ID
2230 */
2231 public void setProdId(ProductId prodId) {
2232 setProperty(ProductId.class, prodId);
2233 }
2234
2235 /**
2236 * Sets the product ID, which identifies the software that created the
2237 * vCard. This is a convenience method for {@link #setProdId(ProductId)}.
2238 * <p>
2239 * <b>Property name:</b> {@code PRODID}
2240 * </p>
2241 * <p>
2242 * <b>Supported versions:</b> {@code 3.0, 4.0}
2243 * </p>
2244 * @param prodId the product ID (e.g. "ez-vcard 1.0") or null to remove
2245 * @return the property object that was created
2246 */
2247 public ProductId setProdId(String prodId) {
2248 ProductId type = null;
2249 if (prodId != null) {
2250 type = new ProductId(prodId);
2251 }
2252 setProdId(type);
2253 return type;
2254 }
2255
2256 /**
2257 * Gets the mailing addresses.
2258 * <p>
2259 * <b>Property name:</b> {@code ADR}
2260 * </p>
2261 * <p>
2262 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2263 * </p>
2264 * @return the mailing addresses
2265 */
2266 public List<Address> getAddresses() {
2267 return getProperties(Address.class);
2268 }
2269
2270 /**
2271 * Adds a mailing address.
2272 * <p>
2273 * <b>Property name:</b> {@code ADR}
2274 * </p>
2275 * <p>
2276 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2277 * </p>
2278 * @param address the mailing address to add
2279 */
2280 public void addAddress(Address address) {
2281 addProperty(address);
2282 }
2283
2284 /**
2285 * <p>
2286 * Adds an address property as a group of alternative representations (see:
2287 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
2288 * ALTID parameter value is automatically generated and assigned to the
2289 * properties.
2290 * </p>
2291 * <p>
2292 * <b>Property name:</b> {@code ADR}
2293 * </p>
2294 * <p>
2295 * <b>Supported versions:</b> {@code 4.0*}<br>
2296 * <i>* Only 4.0 supports alternative representations</i>
2297 * </p>
2298 * @param altRepresentations the alternative representations of the property
2299 */
2300 public void addAddressAlt(Collection<Address> altRepresentations) {
2301 addPropertyAlt(Address.class, altRepresentations);
2302 }
2303
2304 /**
2305 * <p>
2306 * Adds an address property as a group of alternative representations (see:
2307 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
2308 * ALTID parameter value is automatically generated and assigned to the
2309 * properties.
2310 * </p>
2311 * <p>
2312 * <b>Property name:</b> {@code ADR}
2313 * </p>
2314 * <p>
2315 * <b>Supported versions:</b> {@code 4.0*}<br>
2316 * <i>* Only 4.0 supports alternative representations</i>
2317 * </p>
2318 * @param altRepresentations the alternative representations of the property
2319 */
2320 public void addAddressAlt(Address... altRepresentations) {
2321 addPropertyAlt(Address.class, altRepresentations);
2322 }
2323
2324 /**
2325 * Gets all mailing labels that could not be assigned to an address. Use
2326 * {@link Address#getLabel} to get a label that has been assigned to an
2327 * address.
2328 * <p>
2329 * <b>Property name:</b> {@code LABEL}
2330 * </p>
2331 * <p>
2332 * <b>Supported versions:</b> {@code 2.1, 3.0}
2333 * </p>
2334 * @return the orphaned labels
2335 */
2336 public List<Label> getOrphanedLabels() {
2337 return getProperties(Label.class);
2338 }
2339
2340 /**
2341 * Adds a mailing label which is not associated with any address. Use of
2342 * this method is discouraged. To add a mailing label to an address, use the
2343 * {@link Address#setLabel} method.
2344 * <p>
2345 * <b>Property name:</b> {@code LABEL}
2346 * </p>
2347 * <p>
2348 * <b>Supported versions:</b> {@code 2.1, 3.0}
2349 * </p>
2350 * @param label the orphaned label to add
2351 */
2352 public void addOrphanedLabel(Label label) {
2353 addProperty(label);
2354 }
2355
2356 /**
2357 * Gets the email addresses.
2358 * <p>
2359 * <b>Property name:</b> {@code EMAIL}
2360 * </p>
2361 * <p>
2362 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2363 * </p>
2364 * @return the email addresses
2365 */
2366 public List<Email> getEmails() {
2367 return getProperties(Email.class);
2368 }
2369
2370 /**
2371 * Adds an email address.
2372 * <p>
2373 * <b>Property name:</b> {@code EMAIL}
2374 * </p>
2375 * <p>
2376 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2377 * </p>
2378 * @param email the email address to add
2379 */
2380 public void addEmail(Email email) {
2381 addProperty(email);
2382 }
2383
2384 /**
2385 * Adds an email address. This is a convenience method for
2386 * {@link #addEmail(Email)}.
2387 * <p>
2388 * <b>Property name:</b> {@code EMAIL}
2389 * </p>
2390 * <p>
2391 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2392 * </p>
2393 * @param email the email address to add (e.g. "[email protected]")
2394 * @param types the type(s) to assign to the email
2395 * @return the property object that was created
2396 */
2397 public Email addEmail(String email, EmailType... types) {
2398 Email type = new Email(email);
2399 for (EmailType t : types) {
2400 type.addType(t);
2401 }
2402 addEmail(type);
2403 return type;
2404 }
2405
2406 /**
2407 * <p>
2408 * Adds an email property as a group of alternative representations (see:
2409 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
2410 * ALTID parameter value is automatically generated and assigned to the
2411 * properties.
2412 * </p>
2413 * <p>
2414 * <b>Property name:</b> {@code EMAIL}
2415 * </p>
2416 * <p>
2417 * <b>Supported versions:</b> {@code 4.0*}<br>
2418 * <i>* Only 4.0 supports alternative representations</i>
2419 * </p>
2420 * @param altRepresentations the alternative representations of the property
2421 */
2422 public void addEmailAlt(Collection<Email> altRepresentations) {
2423 addPropertyAlt(Email.class, altRepresentations);
2424 }
2425
2426 /**
2427 * <p>
2428 * Adds an email property as a group of alternative representations (see:
2429 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
2430 * ALTID parameter value is automatically generated and assigned to the
2431 * properties.
2432 * </p>
2433 * <p>
2434 * <b>Property name:</b> {@code EMAIL}
2435 * </p>
2436 * <p>
2437 * <b>Supported versions:</b> {@code 4.0*}<br>
2438 * <i>* Only 4.0 supports alternative representations</i>
2439 * </p>
2440 * @param altRepresentations the alternative representations of the property
2441 */
2442 public void addEmailAlt(Email... altRepresentations) {
2443 addPropertyAlt(Email.class, altRepresentations);
2444 }
2445
2446 /**
2447 * Gets the telephone numbers.
2448 * <p>
2449 * <b>Property name:</b> {@code TEL}
2450 * </p>
2451 * <p>
2452 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2453 * </p>
2454 * @return the telephone numbers
2455 */
2456 public List<Telephone> getTelephoneNumbers() {
2457 return getProperties(Telephone.class);
2458 }
2459
2460 /**
2461 * Adds a telephone number.
2462 * <p>
2463 * <b>Property name:</b> {@code TEL}
2464 * </p>
2465 * <p>
2466 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2467 * </p>
2468 * @param telephoneNumber the telephone number to add
2469 */
2470 public void addTelephoneNumber(Telephone telephoneNumber) {
2471 addProperty(telephoneNumber);
2472 }
2473
2474 /**
2475 * Adds a telephone number. This is a convenience method for
2476 * {@link #addTelephoneNumber(Telephone)}.
2477 * <p>
2478 * <b>Property name:</b> {@code TEL}
2479 * </p>
2480 * <p>
2481 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2482 * </p>
2483 * @param telephoneNumber the telephone number to add (e.g.
2484 * "+1 555-555-5555")
2485 * @param types the type(s) to assign to the telephone number (e.g. "cell",
2486 * "work", etc)
2487 * @return the property object that was created
2488 */
2489 public Telephone addTelephoneNumber(String telephoneNumber, TelephoneType... types) {
2490 Telephone type = new Telephone(telephoneNumber);
2491 for (TelephoneType t : types) {
2492 type.addType(t);
2493 }
2494 addTelephoneNumber(type);
2495 return type;
2496 }
2497
2498 /**
2499 * <p>
2500 * Adds a telephone property as a group of alternative representations (see:
2501 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
2502 * ALTID parameter value is automatically generated and assigned to the
2503 * properties.
2504 * </p>
2505 * <p>
2506 * <b>Property name:</b> {@code TEL}
2507 * </p>
2508 * <p>
2509 * <b>Supported versions:</b> {@code 4.0*}<br>
2510 * <i>* Only 4.0 supports alternative representations</i>
2511 * </p>
2512 * @param altRepresentations the alternative representations of the property
2513 */
2514 public void addTelephoneNumberAlt(Collection<Telephone> altRepresentations) {
2515 addPropertyAlt(Telephone.class, altRepresentations);
2516 }
2517
2518 /**
2519 * <p>
2520 * Adds a telephone property as a group of alternative representations (see:
2521 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
2522 * ALTID parameter value is automatically generated and assigned to the
2523 * properties.
2524 * </p>
2525 * <p>
2526 * <b>Property name:</b> {@code TEL}
2527 * </p>
2528 * <p>
2529 * <b>Supported versions:</b> {@code 4.0*}<br>
2530 * <i>* Only 4.0 supports alternative representations</i>
2531 * </p>
2532 * @param altRepresentations the alternative representations of the property
2533 */
2534 public void addTelephoneNumberAlt(Telephone... altRepresentations) {
2535 addPropertyAlt(Telephone.class, altRepresentations);
2536 }
2537
2538 /**
2539 * Gets the email client that the person uses.
2540 * <p>
2541 * <b>Property name:</b> {@code MAILER}
2542 * </p>
2543 * <p>
2544 * <b>Supported versions:</b> {@code 2.1, 3.0}
2545 * </p>
2546 * @return the email client
2547 */
2548 public Mailer getMailer() {
2549 return getProperty(Mailer.class);
2550 }
2551
2552 /**
2553 * Sets the email client that the person uses.
2554 * <p>
2555 * <b>Property name:</b> {@code MAILER}
2556 * </p>
2557 * <p>
2558 * <b>Supported versions:</b> {@code 2.1, 3.0}
2559 * </p>
2560 * @param mailer the email client
2561 */
2562 public void setMailer(Mailer mailer) {
2563 setProperty(Mailer.class, mailer);
2564 }
2565
2566 /**
2567 * Sets the email client that the person uses. This is a convenience method
2568 * for {@link #setMailer(Mailer)}.
2569 * <p>
2570 * <b>Property name:</b> {@code MAILER}
2571 * </p>
2572 * <p>
2573 * <b>Supported versions:</b> {@code 2.1, 3.0}
2574 * </p>
2575 * @param mailer the email client (e.g. "Thunderbird") or null to remove
2576 * @return the property object that was created
2577 */
2578 public Mailer setMailer(String mailer) {
2579 Mailer type = null;
2580 if (mailer != null) {
2581 type = new Mailer(mailer);
2582 }
2583 setMailer(type);
2584 return type;
2585 }
2586
2587 /**
2588 * Gets the URLs. URLs can point to websites such as a personal homepage or
2589 * business website.
2590 * <p>
2591 * <b>Property name:</b> {@code URL}
2592 * </p>
2593 * <p>
2594 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2595 * </p>
2596 * @return the URLs
2597 */
2598 public List<Url> getUrls() {
2599 return getProperties(Url.class);
2600 }
2601
2602 /**
2603 * Adds a URL. URLs can point to websites such as a personal homepage or
2604 * business website.
2605 * <p>
2606 * <b>Property name:</b> {@code URL}
2607 * </p>
2608 * <p>
2609 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2610 * </p>
2611 * @param url the URL to add
2612 */
2613 public void addUrl(Url url) {
2614 addProperty(url);
2615 }
2616
2617 /**
2618 * Adds a URL. URLs can point to websites such as a personal homepage or
2619 * business website. This is a convenience method for {@link #addUrl(Url)}.
2620 * <p>
2621 * <b>Property name:</b> {@code URL}
2622 * </p>
2623 * <p>
2624 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2625 * </p>
2626 * @param url the URL to add (e.g. "http://example.com")
2627 * @return the property object that was created
2628 */
2629 public Url addUrl(String url) {
2630 Url type = new Url(url);
2631 addUrl(type);
2632 return type;
2633 }
2634
2635 /**
2636 * <p>
2637 * Adds a URL property as a group of alternative representations (see:
2638 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
2639 * ALTID parameter value is automatically generated and assigned to the
2640 * properties.
2641 * </p>
2642 * <p>
2643 * <b>Property name:</b> {@code URL}
2644 * </p>
2645 * <p>
2646 * <b>Supported versions:</b> {@code 4.0*}<br>
2647 * <i>* Only 4.0 supports alternative representations</i>
2648 * </p>
2649 * @param altRepresentations the alternative representations of the property
2650 */
2651 public void addUrlAlt(Collection<Url> altRepresentations) {
2652 addPropertyAlt(Url.class, altRepresentations);
2653 }
2654
2655 /**
2656 * <p>
2657 * Adds a URL property as a group of alternative representations (see:
2658 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
2659 * ALTID parameter value is automatically generated and assigned to the
2660 * properties.
2661 * </p>
2662 * <p>
2663 * <b>Property name:</b> {@code URL}
2664 * </p>
2665 * <p>
2666 * <b>Supported versions:</b> {@code 4.0*}<br>
2667 * <i>* Only 4.0 supports alternative representations</i>
2668 * </p>
2669 * @param altRepresentations the alternative representations of the property
2670 */
2671 public void addUrlAlt(Url... altRepresentations) {
2672 addPropertyAlt(Url.class, altRepresentations);
2673 }
2674
2675 /**
2676 * <p>
2677 * Gets all instances of the timezone property. Version 4.0 vCards may have
2678 * multiple instances if alternative representations are defined (see:
2679 * {@link VCardParameters#getAltId description of ALTID}) or if properties
2680 * with different TYPE parameters are defined.
2681 * </p>
2682 * <p>
2683 * <b>Property name:</b> {@code TZ}
2684 * </p>
2685 * <p>
2686 * <b>Supported versions:</b> {@code 4.0*}<br>
2687 * <i>* Only 4.0 supports multiple instances</i>
2688 * </p>
2689 * @return the timezones
2690 */
2691 public List<Timezone> getTimezones() {
2692 return getProperties(Timezone.class);
2693 }
2694
2695 /**
2696 * <p>
2697 * Gets the timezone the person lives/works in.
2698 * </p>
2699 * <p>
2700 * <b>Property name:</b> {@code TZ}
2701 * </p>
2702 * <p>
2703 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2704 * </p>
2705 * @return the timezone
2706 */
2707 public Timezone getTimezone() {
2708 return getProperty(Timezone.class);
2709 }
2710
2711 /**
2712 * <p>
2713 * Sets the timezone the person lives/works in as a group of alternative
2714 * representations (see: {@link VCardParameters#getAltId description of
2715 * ALTID} ). An appropriate ALTID parameter value is automatically generated
2716 * and assigned to the properties.
2717 * </p>
2718 * <p>
2719 * <b>Property name:</b> {@code TZ}
2720 * </p>
2721 * <p>
2722 * <b>Supported versions:</b> {@code 4.0*}<br>
2723 * <i>* Only 4.0 supports alternative representations</i>
2724 * </p>
2725 * @param altRepresentations the alternative representations of the property
2726 */
2727 public void setTimezoneAlt(Collection<Timezone> altRepresentations) {
2728 setPropertyAlt(Timezone.class, altRepresentations);
2729 }
2730
2731 /**
2732 * <p>
2733 * Sets the timezone the person lives/works in as a group of alternative
2734 * representations (see: {@link VCardParameters#getAltId description of
2735 * ALTID} ). An appropriate ALTID parameter value is automatically generated
2736 * and assigned to the properties.
2737 * </p>
2738 * <p>
2739 * <b>Property name:</b> {@code TZ}
2740 * </p>
2741 * <p>
2742 * <b>Supported versions:</b> {@code 4.0*}<br>
2743 * <i>* Only 4.0 supports alternative representations</i>
2744 * </p>
2745 * @param altRepresentations the alternative representations of the property
2746 */
2747 public void setTimezoneAlt(Timezone... altRepresentations) {
2748 setPropertyAlt(Timezone.class, altRepresentations);
2749 }
2750
2751 /**
2752 * <p>
2753 * Adds a timezone the person lives/works in as a group of alternative
2754 * representations (see: {@link VCardParameters#getAltId description of
2755 * ALTID} ). An appropriate ALTID parameter value is automatically generated
2756 * and assigned to the properties.
2757 * </p>
2758 * <p>
2759 * <b>Property name:</b> {@code TZ}
2760 * </p>
2761 * <p>
2762 * <b>Supported versions:</b> {@code 4.0*}<br>
2763 * <i>* Only 4.0 supports alternative representations</i>
2764 * </p>
2765 * @param altRepresentations the alternative representations of the property
2766 */
2767 public void addTimezoneAlt(Collection<Timezone> altRepresentations) {
2768 addPropertyAlt(Timezone.class, altRepresentations);
2769 }
2770
2771 /**
2772 * <p>
2773 * Adds a timezone the person lives/works in as a group of alternative
2774 * representations (see: {@link VCardParameters#getAltId description of
2775 * ALTID} ). An appropriate ALTID parameter value is automatically generated
2776 * and assigned to the properties.
2777 * </p>
2778 * <p>
2779 * <b>Property name:</b> {@code TZ}
2780 * </p>
2781 * <p>
2782 * <b>Supported versions:</b> {@code 4.0*}<br>
2783 * <i>* Only 4.0 supports alternative representations</i>
2784 * </p>
2785 * @param altRepresentations the alternative representations of the property
2786 */
2787 public void addTimezoneAlt(Timezone... altRepresentations) {
2788 addPropertyAlt(Timezone.class, altRepresentations);
2789 }
2790
2791 /**
2792 * <p>
2793 * Sets the timezone the person lives/works in.
2794 * </p>
2795 * <p>
2796 * <b>Property name:</b> {@code TZ}
2797 * </p>
2798 * <p>
2799 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2800 * </p>
2801 * @param timezone the timezone or null to remove
2802 */
2803 public void setTimezone(Timezone timezone) {
2804 setProperty(Timezone.class, timezone);
2805 }
2806
2807 /**
2808 * <p>
2809 * Adds a timezone the person lives/works in.
2810 * </p>
2811 * <p>
2812 * <b>Property name:</b> {@code TZ}
2813 * </p>
2814 * <p>
2815 * <b>Supported versions:</b> {@code 4.0*}<br>
2816 * <i>* Only 4.0 supports multiple instances</i>
2817 * </p>
2818 * @param timezone the timezone or null to remove
2819 */
2820 public void addTimezone(Timezone timezone) {
2821 addProperty(timezone);
2822 }
2823
2824 /**
2825 * <p>
2826 * Gets all instances of the geo property. Version 4.0 vCards may have
2827 * multiple instances if alternative representations are defined (see:
2828 * {@link VCardParameters#getAltId description of ALTID}) or if properties
2829 * with different TYPE parameters are defined.
2830 * </p>
2831 * <p>
2832 * <b>Property name:</b> {@code GEO}
2833 * </p>
2834 * <p>
2835 * <b>Supported versions:</b> {@code 4.0*}<br>
2836 * <i>* Only 4.0 supports multiple instances</i>
2837 * </p>
2838 * @return the geo properties
2839 */
2840 public List<Geo> getGeos() {
2841 return getProperties(Geo.class);
2842 }
2843
2844 /**
2845 * <p>
2846 * Gets the geographical position of where the person lives/works.
2847 * </p>
2848 * <p>
2849 * <b>Property name:</b> {@code GEO}
2850 * </p>
2851 * <p>
2852 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2853 * </p>
2854 * @return the geographical position or null if one doesn't exist
2855 */
2856 public Geo getGeo() {
2857 return getProperty(Geo.class);
2858 }
2859
2860 /**
2861 * <p>
2862 * Sets the geographical position of where the person lives/works as a group
2863 * of alternative representations (see: {@link VCardParameters#getAltId
2864 * description of ALTID}). An appropriate ALTID parameter value is
2865 * automatically generated and assigned to the properties.
2866 * </p>
2867 * <p>
2868 * <b>Property name:</b> {@code GEO}
2869 * </p>
2870 * <p>
2871 * <b>Supported versions:</b> {@code 4.0*}<br>
2872 * <i>* Only 4.0 supports alternative representations</i>
2873 * </p>
2874 * @param altRepresentations the alternative representations of the property
2875 */
2876 public void setGeoAlt(Collection<Geo> altRepresentations) {
2877 setPropertyAlt(Geo.class, altRepresentations);
2878 }
2879
2880 /**
2881 * <p>
2882 * Adds a geographical position of where the person lives/works as a group
2883 * of alternative representations (see: {@link VCardParameters#getAltId
2884 * description of ALTID}). An appropriate ALTID parameter value is
2885 * automatically generated and assigned to the properties.
2886 * </p>
2887 * <p>
2888 * <b>Property name:</b> {@code GEO}
2889 * </p>
2890 * <p>
2891 * <b>Supported versions:</b> {@code 4.0*}<br>
2892 * <i>* Only 4.0 supports alternative representations</i>
2893 * </p>
2894 * @param altRepresentations the alternative representations of the property
2895 */
2896 public void addGeoAlt(Collection<Geo> altRepresentations) {
2897 addPropertyAlt(Geo.class, altRepresentations);
2898 }
2899
2900 /**
2901 * <p>
2902 * Adds a geographical position of where the person lives/works as a group
2903 * of alternative representations (see: {@link VCardParameters#getAltId
2904 * description of ALTID}). An appropriate ALTID parameter value is
2905 * automatically generated and assigned to the properties.
2906 * </p>
2907 * <p>
2908 * <b>Property name:</b> {@code GEO}
2909 * </p>
2910 * <p>
2911 * <b>Supported versions:</b> {@code 4.0*}<br>
2912 * <i>* Only 4.0 supports alternative representations</i>
2913 * </p>
2914 * @param altRepresentations the alternative representations of the property
2915 */
2916 public void addGeoAlt(Geo... altRepresentations) {
2917 addPropertyAlt(Geo.class, altRepresentations);
2918 }
2919
2920 /**
2921 * <p>
2922 * Sets the geographical position of where the person lives/works.
2923 * </p>
2924 * <p>
2925 * <b>Property name:</b> {@code GEO}
2926 * </p>
2927 * <p>
2928 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2929 * </p>
2930 * @param geo the geographical position or null to remove
2931 */
2932 public void setGeo(Geo geo) {
2933 setProperty(Geo.class, geo);
2934 }
2935
2936 /**
2937 * <p>
2938 * Adds a geographical position of where the person lives/works. Note that
2939 * only version 4.0 vCards support multiple instances of this property.
2940 * </p>
2941 * <p>
2942 * <b>Property name:</b> {@code GEO}
2943 * </p>
2944 * <p>
2945 * <b>Supported versions:</b> {@code 4.0*}<br>
2946 * <i>* Only 4.0 supports multiple instances</i>
2947 * </p>
2948 * @param geo the geographical position
2949 */
2950 public void addGeo(Geo geo) {
2951 addProperty(geo);
2952 }
2953
2954 /**
2955 * <p>
2956 * Sets the geographical position of where the person lives/works. This is a
2957 * convenience method for {@link #setGeo(Geo)}.
2958 * </p>
2959 * <p>
2960 * <b>Property name:</b> {@code GEO}
2961 * </p>
2962 * <p>
2963 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
2964 * </p>
2965 * @param latitude the latitude
2966 * @param longitude the longitude
2967 * @return the property object that was created
2968 */
2969 public Geo setGeo(double latitude, double longitude) {
2970 Geo type = new Geo(latitude, longitude);
2971 setGeo(type);
2972 return type;
2973 }
2974
2975 /**
2976 * <p>
2977 * Gets all instances of the organization property. Version 4.0 vCards may
2978 * have multiple instances if alternative representations are defined (see:
2979 * {@link VCardParameters#getAltId description of ALTID}) or if properties
2980 * with different TYPE parameters are defined.
2981 * </p>
2982 * <p>
2983 * <b>Property name:</b> {@code ORG}
2984 * </p>
2985 * <p>
2986 * <b>Supported versions:</b> {@code 4.0*}<br>
2987 * <i>* Only 4.0 supports multiple instances</i>
2988 * </p>
2989 * @return the organization properties
2990 */
2991 public List<Organization> getOrganizations() {
2992 return getProperties(Organization.class);
2993 }
2994
2995 /**
2996 * <p>
2997 * Gets the hierarchy of department(s) to which the person belongs.
2998 * </p>
2999 * <p>
3000 * <b>Property name:</b> {@code ORG}
3001 * </p>
3002 * <p>
3003 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3004 * </p>
3005 * @return the department(s)
3006 */
3007 public Organization getOrganization() {
3008 return getProperty(Organization.class);
3009 }
3010
3011 /**
3012 * <p>
3013 * Sets the organization property as a group of alternative representations
3014 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3015 * appropriate ALTID parameter value is automatically generated and assigned
3016 * to the properties.
3017 * </p>
3018 * <p>
3019 * <b>Property name:</b> {@code ORG}
3020 * </p>
3021 * <p>
3022 * <b>Supported versions:</b> {@code 4.0*}<br>
3023 * <i>* Only 4.0 supports alternative representations</i>
3024 * </p>
3025 * @param altRepresentations the alternative representations of the property
3026 */
3027 public void setOrganizationAlt(Collection<Organization> altRepresentations) {
3028 setPropertyAlt(Organization.class, altRepresentations);
3029 }
3030
3031 /**
3032 * <p>
3033 * Sets the organization property as a group of alternative representations
3034 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3035 * appropriate ALTID parameter value is automatically generated and assigned
3036 * to the properties.
3037 * </p>
3038 * <p>
3039 * <b>Property name:</b> {@code ORG}
3040 * </p>
3041 * <p>
3042 * <b>Supported versions:</b> {@code 4.0*}<br>
3043 * <i>* Only 4.0 supports alternative representations</i>
3044 * </p>
3045 * @param altRepresentations the alternative representations of the property
3046 */
3047 public void setOrganizationAlt(Organization... altRepresentations) {
3048 setPropertyAlt(Organization.class, altRepresentations);
3049 }
3050
3051 /**
3052 * <p>
3053 * Adds an organization property as a group of alternative representations
3054 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3055 * appropriate ALTID parameter value is automatically generated and assigned
3056 * to the properties.
3057 * </p>
3058 * <p>
3059 * <b>Property name:</b> {@code ORG}
3060 * </p>
3061 * <p>
3062 * <b>Supported versions:</b> {@code 4.0*}<br>
3063 * <i>* Only 4.0 supports alternative representations</i>
3064 * </p>
3065 * @param altRepresentations the alternative representations of the property
3066 */
3067 public void addOrganizationAlt(Collection<Organization> altRepresentations) {
3068 addPropertyAlt(Organization.class, altRepresentations);
3069 }
3070
3071 /**
3072 * <p>
3073 * Adds an organization property as a group of alternative representations
3074 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3075 * appropriate ALTID parameter value is automatically generated and assigned
3076 * to the properties.
3077 * </p>
3078 * <p>
3079 * <b>Property name:</b> {@code ORG}
3080 * </p>
3081 * <p>
3082 * <b>Supported versions:</b> {@code 4.0*}<br>
3083 * <i>* Only 4.0 supports alternative representations</i>
3084 * </p>
3085 * @param altRepresentations the alternative representations of the property
3086 */
3087 public void addOrganizationAlt(Organization... altRepresentations) {
3088 addPropertyAlt(Organization.class, altRepresentations);
3089 }
3090
3091 /**
3092 * <p>
3093 * Sets the hierarchy of departments to which the person belongs.
3094 * </p>
3095 * <p>
3096 * <b>Property name:</b> {@code ORG}
3097 * </p>
3098 * <p>
3099 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3100 * </p>
3101 * @param organization the organization property or null to remove
3102 */
3103 public void setOrganization(Organization organization) {
3104 setProperty(Organization.class, organization);
3105 }
3106
3107 /**
3108 * <p>
3109 * Adds a hierarchy of departments to which the person belongs. Note that
3110 * only version 4.0 vCards support multiple instances of this property.
3111 * </p>
3112 * <p>
3113 * <b>Property name:</b> {@code ORG}
3114 * </p>
3115 * <p>
3116 * <b>Supported versions:</b> {@code 4.0*}<br>
3117 * <i>* Only 4.0 supports multiple instances</i>
3118 * </p>
3119 * @param organization the organization property
3120 */
3121 public void addOrganization(Organization organization) {
3122 addProperty(organization);
3123 }
3124
3125 /**
3126 * <p>
3127 * Sets the hierarchy of departments to which the person belongs. This is a
3128 * convenience method for {@link #setOrganization(Organization)}.
3129 * </p>
3130 * <p>
3131 * <b>Property name:</b> {@code ORG}
3132 * </p>
3133 * <p>
3134 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3135 * </p>
3136 * @param departments the ordered list of department(s), starting with the
3137 * broadest and ending with the most specific (e.g. "Google", "GMail Team",
3138 * "Spam Detection Squad") or null to remove
3139 * @return the property object that was created
3140 */
3141 public Organization setOrganization(String... departments) {
3142 Organization type = null;
3143 if (departments != null) {
3144 type = new Organization();
3145 for (String department : departments) {
3146 type.addValue(department);
3147 }
3148 }
3149 setOrganization(type);
3150 return type;
3151 }
3152
3153 /**
3154 * <p>
3155 * Gets all instances of the categories property. Version 4.0 vCards may
3156 * have multiple instances if alternative representations are defined (see:
3157 * {@link VCardParameters#getAltId description of ALTID}) or if properties
3158 * with different TYPE parameters are defined.
3159 * </p>
3160 * <p>
3161 * <b>Property name:</b> {@code CATEGORIES}
3162 * </p>
3163 * <p>
3164 * <b>Supported versions:</b> {@code 4.0*}<br>
3165 * <i>* Only 4.0 supports multiple instances</i>
3166 * </p>
3167 * @return the categories properties
3168 */
3169 public List<Categories> getCategoriesList() {
3170 return getProperties(Categories.class);
3171 }
3172
3173 /**
3174 * <p>
3175 * Gets the list of keywords (aka "tags") that can be used to describe the
3176 * person.
3177 * </p>
3178 * <p>
3179 * <b>Property name:</b> {@code CATEGORIES}
3180 * </p>
3181 * <p>
3182 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3183 * </p>
3184 * @return the categories
3185 */
3186 public Categories getCategories() {
3187 return getProperty(Categories.class);
3188 }
3189
3190 /**
3191 * <p>
3192 * Sets the categories property as a group of alternative representations
3193 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3194 * appropriate ALTID parameter value is automatically generated and assigned
3195 * to the properties.
3196 * </p>
3197 * <p>
3198 * <b>Property name:</b> {@code CATEGORIES}
3199 * </p>
3200 * <p>
3201 * <b>Supported versions:</b> {@code 4.0*}<br>
3202 * <i>* Only 4.0 supports alternative representations</i>
3203 * </p>
3204 * @param altRepresentations the alternative representations of the property
3205 */
3206 public void setCategoriesAlt(Collection<Categories> altRepresentations) {
3207 setPropertyAlt(Categories.class, altRepresentations);
3208 }
3209
3210 /**
3211 * <p>
3212 * Sets the categories property as a group of alternative representations
3213 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3214 * appropriate ALTID parameter value is automatically generated and assigned
3215 * to the properties.
3216 * </p>
3217 * <p>
3218 * <b>Property name:</b> {@code CATEGORIES}
3219 * </p>
3220 * <p>
3221 * <b>Supported versions:</b> {@code 4.0*}<br>
3222 * <i>* Only 4.0 supports alternative representations</i>
3223 * </p>
3224 * @param altRepresentations the alternative representations of the property
3225 */
3226 public void setCategoriesAlt(Categories... altRepresentations) {
3227 setPropertyAlt(Categories.class, altRepresentations);
3228 }
3229
3230 /**
3231 * <p>
3232 * Adds a categories property as a group of alternative representations
3233 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3234 * appropriate ALTID parameter value is automatically generated and assigned
3235 * to the properties.
3236 * </p>
3237 * <p>
3238 * <b>Property name:</b> {@code CATEGORIES}
3239 * </p>
3240 * <p>
3241 * <b>Supported versions:</b> {@code 4.0*}<br>
3242 * <i>* Only 4.0 supports alternative representations</i>
3243 * </p>
3244 * @param altRepresentations the alternative representations of the property
3245 */
3246 public void addCategoriesAlt(Collection<Categories> altRepresentations) {
3247 addPropertyAlt(Categories.class, altRepresentations);
3248 }
3249
3250 /**
3251 * <p>
3252 * Adds a categories property as a group of alternative representations
3253 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3254 * appropriate ALTID parameter value is automatically generated and assigned
3255 * to the properties.
3256 * </p>
3257 * <p>
3258 * <b>Property name:</b> {@code CATEGORIES}
3259 * </p>
3260 * <p>
3261 * <b>Supported versions:</b> {@code 4.0*}<br>
3262 * <i>* Only 4.0 supports alternative representations</i>
3263 * </p>
3264 * @param altRepresentations the alternative representations of the property
3265 */
3266 public void addCategoriesAlt(Categories... altRepresentations) {
3267 addPropertyAlt(Categories.class, altRepresentations);
3268 }
3269
3270 /**
3271 * <p>
3272 * Sets the list of keywords (aka "tags") that can be used to describe the
3273 * person.
3274 * </p>
3275 * <p>
3276 * <b>Property name:</b> {@code CATEGORIES}
3277 * </p>
3278 * <p>
3279 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3280 * </p>
3281 * @param categories the categories or null to remove (note: multiple
3282 * categories may be added to this object)
3283 */
3284 public void setCategories(Categories categories) {
3285 setProperty(Categories.class, categories);
3286 }
3287
3288 /**
3289 * <p>
3290 * Adds a list of keywords (aka "tags") that can be used to describe the
3291 * person. Note that only version 4.0 vCards support multiple instances of
3292 * this property.
3293 * </p>
3294 * <p>
3295 * <b>Property name:</b> {@code CATEGORIES}
3296 * </p>
3297 * <p>
3298 * <b>Supported versions:</b> {@code 4.0*}<br>
3299 * <i>* Only 4.0 supports multiple instances</i>
3300 * </p>
3301 * @param categories the categories (note: multiple categories may be added
3302 * to this object)
3303 */
3304 public void addCategories(Categories categories) {
3305 addProperty(categories);
3306 }
3307
3308 /**
3309 * <p>
3310 * Sets the list of keywords (aka "tags") that can be used to describe the
3311 * person. This is a convenience method for
3312 * {@link #setCategories(Categories)}.
3313 * </p>
3314 * <p>
3315 * <b>Property name:</b> {@code CATEGORIES}
3316 * </p>
3317 * <p>
3318 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3319 * </p>
3320 * @param categories the category or categories (e.g. "swimmer", "biker",
3321 * "knitter")
3322 * @return the property object that was created
3323 */
3324 public Categories setCategories(String... categories) {
3325 Categories type = null;
3326 if (categories != null) {
3327 type = new Categories();
3328 for (String category : categories) {
3329 type.addValue(category);
3330 }
3331 }
3332 setCategories(type);
3333 return type;
3334 }
3335
3336 /**
3337 * Gets information about the person's agent.
3338 * <p>
3339 * <b>Property name:</b> {@code AGENT}
3340 * </p>
3341 * <p>
3342 * <b>Supported versions:</b> {@code 2.1, 3.0}
3343 * </p>
3344 * @return the agent information
3345 */
3346 public Agent getAgent() {
3347 return getProperty(Agent.class);
3348 }
3349
3350 /**
3351 * Sets information about the person's agent.
3352 * <p>
3353 * <b>Property name:</b> {@code AGENT}
3354 * </p>
3355 * <p>
3356 * <b>Supported versions:</b> {@code 2.1, 3.0}
3357 * </p>
3358 * @param agent the agent information
3359 */
3360 public void setAgent(Agent agent) {
3361 setProperty(Agent.class, agent);
3362 }
3363
3364 /**
3365 * Gets the notes. Notes contain free-form, miscellaneous text.
3366 * <p>
3367 * <b>Property name:</b> {@code NOTE}
3368 * </p>
3369 * <p>
3370 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3371 * </p>
3372 * @return the notes
3373 */
3374 public List<Note> getNotes() {
3375 return getProperties(Note.class);
3376 }
3377
3378 /**
3379 * Adds a note. Notes contain free-form, miscellaneous text.
3380 * <p>
3381 * <b>Property name:</b> {@code NOTE}
3382 * </p>
3383 * <p>
3384 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3385 * </p>
3386 * @param note the note to add
3387 */
3388 public void addNote(Note note) {
3389 addProperty(note);
3390 }
3391
3392 /**
3393 * Adds a note. Notes contain free-form, miscellaneous text. This is a
3394 * convenience method for {@link #addNote(Note)}.
3395 * <p>
3396 * <b>Property name:</b> {@code NOTE}
3397 * </p>
3398 * <p>
3399 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3400 * </p>
3401 * @param note the note to add
3402 * @return the property object that was created
3403 */
3404 public Note addNote(String note) {
3405 Note type = new Note(note);
3406 addNote(type);
3407 return type;
3408 }
3409
3410 /**
3411 * <p>
3412 * Adds a note property as a group of alternative representations (see:
3413 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3414 * ALTID parameter value is automatically generated and assigned to the
3415 * properties.
3416 * </p>
3417 * <p>
3418 * <b>Property name:</b> {@code NOTE}
3419 * </p>
3420 * <p>
3421 * <b>Supported versions:</b> {@code 4.0*}<br>
3422 * <i>* Only 4.0 supports alternative representations</i>
3423 * </p>
3424 * @param altRepresentations the alternative representations of the property
3425 */
3426 public void addNoteAlt(Collection<Note> altRepresentations) {
3427 addPropertyAlt(Note.class, altRepresentations);
3428 }
3429
3430 /**
3431 * <p>
3432 * Adds a note property as a group of alternative representations (see:
3433 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3434 * ALTID parameter value is automatically generated and assigned to the
3435 * properties.
3436 * </p>
3437 * <p>
3438 * <b>Property name:</b> {@code NOTE}
3439 * </p>
3440 * <p>
3441 * <b>Supported versions:</b> {@code 4.0*}<br>
3442 * <i>* Only 4.0 supports alternative representations</i>
3443 * </p>
3444 * @param altRepresentations the alternative representations of the property
3445 */
3446 public void addNoteAlt(Note... altRepresentations) {
3447 addPropertyAlt(Note.class, altRepresentations);
3448 }
3449
3450 /**
3451 * Gets the unique identifier of the vCard.
3452 * <p>
3453 * <b>Property name:</b> {@code UID}
3454 * </p>
3455 * <p>
3456 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3457 * </p>
3458 * @return the unique identifier
3459 */
3460 public Uid getUid() {
3461 return getProperty(Uid.class);
3462 }
3463
3464 /**
3465 * Sets the unique identifier of the vCard.
3466 * <p>
3467 * <b>Property name:</b> {@code UID}
3468 * </p>
3469 * <p>
3470 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3471 * </p>
3472 * @param uid the unique identifier
3473 */
3474 public void setUid(Uid uid) {
3475 setProperty(Uid.class, uid);
3476 }
3477
3478 /**
3479 * Gets the public encryption keys.
3480 * <p>
3481 * <b>Property name:</b> {@code KEY}
3482 * </p>
3483 * <p>
3484 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3485 * </p>
3486 * @return the keys
3487 */
3488 public List<Key> getKeys() {
3489 return getProperties(Key.class);
3490 }
3491
3492 /**
3493 * Adds a public encryption key.
3494 * <p>
3495 * <b>Property name:</b> {@code KEY}
3496 * </p>
3497 * <p>
3498 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
3499 * </p>
3500 * @param key the key to add
3501 */
3502 public void addKey(Key key) {
3503 addProperty(key);
3504 }
3505
3506 /**
3507 * <p>
3508 * Adds a key property as a group of alternative representations (see:
3509 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3510 * ALTID parameter value is automatically generated and assigned to the
3511 * properties.
3512 * </p>
3513 * <p>
3514 * <b>Property name:</b> {@code KEY}
3515 * </p>
3516 * <p>
3517 * <b>Supported versions:</b> {@code 4.0*}<br>
3518 * <i>* Only 4.0 supports alternative representations</i>
3519 * </p>
3520 * @param altRepresentations the alternative representations of the property
3521 */
3522 public void addKeyAlt(Collection<Key> altRepresentations) {
3523 addPropertyAlt(Key.class, altRepresentations);
3524 }
3525
3526 /**
3527 * <p>
3528 * Adds a key property as a group of alternative representations (see:
3529 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3530 * ALTID parameter value is automatically generated and assigned to the
3531 * properties.
3532 * </p>
3533 * <p>
3534 * <b>Property name:</b> {@code KEY}
3535 * </p>
3536 * <p>
3537 * <b>Supported versions:</b> {@code 4.0*}<br>
3538 * <i>* Only 4.0 supports alternative representations</i>
3539 * </p>
3540 * @param altRepresentations the alternative representations of the property
3541 */
3542 public void addKeyAlt(Key... altRepresentations) {
3543 addPropertyAlt(Key.class, altRepresentations);
3544 }
3545
3546 /**
3547 * Gets the instant messaging handles.
3548 * <p>
3549 * <b>Property name:</b> {@code IMPP}
3550 * </p>
3551 * <p>
3552 * <b>Supported versions:</b> {@code 3.0, 4.0}
3553 * </p>
3554 * @return the instant messaging handles
3555 */
3556 public List<Impp> getImpps() {
3557 return getProperties(Impp.class);
3558 }
3559
3560 /**
3561 * Adds an instant messaging handle.
3562 * <p>
3563 * <b>Property name:</b> {@code IMPP}
3564 * </p>
3565 * <p>
3566 * <b>Supported versions:</b> {@code 3.0, 4.0}
3567 * </p>
3568 * @param impp the instant messaging handle to add
3569 */
3570 public void addImpp(Impp impp) {
3571 addProperty(impp);
3572 }
3573
3574 /**
3575 * <p>
3576 * Adds an impp property as a group of alternative representations (see:
3577 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3578 * ALTID parameter value is automatically generated and assigned to the
3579 * properties.
3580 * </p>
3581 * <p>
3582 * <b>Property name:</b> {@code IMPP}
3583 * </p>
3584 * <p>
3585 * <b>Supported versions:</b> {@code 4.0*}<br>
3586 * <i>* Only 4.0 supports alternative representations</i>
3587 * </p>
3588 * @param altRepresentations the alternative representations of the property
3589 */
3590 public void addImppAlt(Collection<Impp> altRepresentations) {
3591 addPropertyAlt(Impp.class, altRepresentations);
3592 }
3593
3594 /**
3595 * <p>
3596 * Adds an impp property as a group of alternative representations (see:
3597 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3598 * ALTID parameter value is automatically generated and assigned to the
3599 * properties.
3600 * </p>
3601 * <p>
3602 * <b>Property name:</b> {@code IMPP}
3603 * </p>
3604 * <p>
3605 * <b>Supported versions:</b> {@code 4.0*}<br>
3606 * <i>* Only 4.0 supports alternative representations</i>
3607 * </p>
3608 * @param altRepresentations the alternative representations of the property
3609 */
3610 public void addImppAlt(Impp... altRepresentations) {
3611 addPropertyAlt(Impp.class, altRepresentations);
3612 }
3613
3614 /**
3615 * Gets a list of people that the person is related to.
3616 * <p>
3617 * <b>Property name:</b> {@code RELATED}
3618 * </p>
3619 * <p>
3620 * <b>Supported versions:</b> {@code 4.0}
3621 * </p>
3622 * @return the person's relations
3623 */
3624 public List<Related> getRelations() {
3625 return getProperties(Related.class);
3626 }
3627
3628 /**
3629 * Adds someone that the person is related to.
3630 * <p>
3631 * <b>Property name:</b> {@code RELATED}
3632 * </p>
3633 * <p>
3634 * <b>Supported versions:</b> {@code 4.0}
3635 * </p>
3636 * @param related the relation to add
3637 */
3638 public void addRelated(Related related) {
3639 addProperty(related);
3640 }
3641
3642 /**
3643 * <p>
3644 * Adds a related property as a group of alternative representations (see:
3645 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3646 * ALTID parameter value is automatically generated and assigned to the
3647 * properties.
3648 * </p>
3649 * <p>
3650 * <b>Property name:</b> {@code RELATED}
3651 * </p>
3652 * <p>
3653 * <b>Supported versions:</b> {@code 4.0}
3654 * </p>
3655 * @param altRepresentations the alternative representations of the property
3656 */
3657 public void addRelatedAlt(Collection<Related> altRepresentations) {
3658 addPropertyAlt(Related.class, altRepresentations);
3659 }
3660
3661 /**
3662 * <p>
3663 * Adds a related property as a group of alternative representations (see:
3664 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3665 * ALTID parameter value is automatically generated and assigned to the
3666 * properties.
3667 * </p>
3668 * <p>
3669 * <b>Property name:</b> {@code RELATED}
3670 * </p>
3671 * <p>
3672 * <b>Supported versions:</b> {@code 4.0}
3673 * </p>
3674 * @param altRepresentations the alternative representations of the property
3675 */
3676 public void addRelatedAlt(Related... altRepresentations) {
3677 addPropertyAlt(Related.class, altRepresentations);
3678 }
3679
3680 /**
3681 * Gets the languages that the person speaks.
3682 * <p>
3683 * <b>Property name:</b> {@code LANG}
3684 * </p>
3685 * <p>
3686 * <b>Supported versions:</b> {@code 4.0}
3687 * </p>
3688 * @return the languages
3689 */
3690 public List<Language> getLanguages() {
3691 return getProperties(Language.class);
3692 }
3693
3694 /**
3695 * Adds a language that the person speaks.
3696 * <p>
3697 * <b>Property name:</b> {@code LANG}
3698 * </p>
3699 * <p>
3700 * <b>Supported versions:</b> {@code 4.0}
3701 * </p>
3702 * @param language the language to add
3703 */
3704 public void addLanguage(Language language) {
3705 addProperty(language);
3706 }
3707
3708 /**
3709 * Adds a language that the person speaks. This is a convenience method for
3710 * {@link #addLanguage(Language)}.
3711 * <p>
3712 * <b>Property name:</b> {@code LANG}
3713 * </p>
3714 * <p>
3715 * <b>Supported versions:</b> {@code 4.0}
3716 * </p>
3717 * @param language the language to add (e.g. "en-us")
3718 * @return the property object that was created
3719 */
3720 public Language addLanguage(String language) {
3721 Language type = new Language(language);
3722 addLanguage(type);
3723 return type;
3724 }
3725
3726 /**
3727 * <p>
3728 * Adds a language property as a group of alternative representations (see:
3729 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3730 * ALTID parameter value is automatically generated and assigned to the
3731 * properties.
3732 * </p>
3733 * <p>
3734 * <b>Property name:</b> {@code LANG}
3735 * </p>
3736 * <p>
3737 * <b>Supported versions:</b> {@code 4.0}
3738 * @param altRepresentations the alternative representations of the property
3739 */
3740 public void addLanguageAlt(Collection<Language> altRepresentations) {
3741 addPropertyAlt(Language.class, altRepresentations);
3742 }
3743
3744 /**
3745 * <p>
3746 * Adds a language property as a group of alternative representations (see:
3747 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3748 * ALTID parameter value is automatically generated and assigned to the
3749 * properties.
3750 * </p>
3751 * <p>
3752 * <b>Property name:</b> {@code LANG}
3753 * </p>
3754 * <p>
3755 * <b>Supported versions:</b> {@code 4.0}
3756 * @param altRepresentations the alternative representations of the property
3757 */
3758 public void addLanguageAlt(Language... altRepresentations) {
3759 addPropertyAlt(Language.class, altRepresentations);
3760 }
3761
3762 /**
3763 * Gets the URIs that can be used to schedule a meeting with the person on
3764 * his or her calendar.
3765 * <p>
3766 * <b>Property name:</b> {@code CALADRURI}
3767 * </p>
3768 * <p>
3769 * <b>Supported versions:</b> {@code 4.0}
3770 * </p>
3771 * @return the calendar request URIs
3772 */
3773 public List<CalendarRequestUri> getCalendarRequestUris() {
3774 return getProperties(CalendarRequestUri.class);
3775 }
3776
3777 /**
3778 * Adds a URI that can be used to schedule a meeting with the person on his
3779 * or her calendar.
3780 * <p>
3781 * <b>Property name:</b> {@code CALADRURI}
3782 * </p>
3783 * <p>
3784 * <b>Supported versions:</b> {@code 4.0}
3785 * </p>
3786 * @param calendarRequestUri the calendar request URI to add
3787 */
3788 public void addCalendarRequestUri(CalendarRequestUri calendarRequestUri) {
3789 addProperty(calendarRequestUri);
3790 }
3791
3792 /**
3793 * <p>
3794 * Adds a calendar request URI property as a group of alternative
3795 * representations (see: {@link VCardParameters#getAltId description of
3796 * ALTID} ). An appropriate ALTID parameter value is automatically generated
3797 * and assigned to the properties.
3798 * </p>
3799 * <p>
3800 * <b>Property name:</b> {@code CALADRURI}
3801 * </p>
3802 * <p>
3803 * <b>Supported versions:</b> {@code 4.0}
3804 * </p>
3805 * @param altRepresentations the alternative representations of the property
3806 */
3807 public void addCalendarRequestUriAlt(Collection<CalendarRequestUri> altRepresentations) {
3808 addPropertyAlt(CalendarRequestUri.class, altRepresentations);
3809 }
3810
3811 /**
3812 * <p>
3813 * Adds a calendar request URI property as a group of alternative
3814 * representations (see: {@link VCardParameters#getAltId description of
3815 * ALTID} ). An appropriate ALTID parameter value is automatically generated
3816 * and assigned to the properties.
3817 * </p>
3818 * <p>
3819 * <b>Property name:</b> {@code CALADRURI}
3820 * </p>
3821 * <p>
3822 * <b>Supported versions:</b> {@code 4.0}
3823 * </p>
3824 * @param altRepresentations the alternative representations of the property
3825 */
3826 public void addCalendarRequestUriAlt(CalendarRequestUri... altRepresentations) {
3827 addPropertyAlt(CalendarRequestUri.class, altRepresentations);
3828 }
3829
3830 /**
3831 * Gets the URIs that point to the person's calendar.
3832 * <p>
3833 * <b>Property name:</b> {@code CALURI}
3834 * </p>
3835 * <p>
3836 * <b>Supported versions:</b> {@code 4.0}
3837 * </p>
3838 * @return the calendar URIs
3839 */
3840 public List<CalendarUri> getCalendarUris() {
3841 return getProperties(CalendarUri.class);
3842 }
3843
3844 /**
3845 * Adds a URI that points to the person's calendar.
3846 * <p>
3847 * <b>Property name:</b> {@code CALURI}
3848 * </p>
3849 * <p>
3850 * <b>Supported versions:</b> {@code 4.0}
3851 * </p>
3852 * @param calendarUri the calendar URI to add
3853 */
3854 public void addCalendarUri(CalendarUri calendarUri) {
3855 addProperty(calendarUri);
3856 }
3857
3858 /**
3859 * <p>
3860 * Adds a calendar URI property as a group of alternative representations
3861 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3862 * appropriate ALTID parameter value is automatically generated and assigned
3863 * to the properties.
3864 * </p>
3865 * <p>
3866 * <b>Property name:</b> {@code CALURI}
3867 * </p>
3868 * <p>
3869 * <b>Supported versions:</b> {@code 4.0}
3870 * </p>
3871 * @param altRepresentations the alternative representations of the property
3872 */
3873 public void addCalendarUriAlt(Collection<CalendarUri> altRepresentations) {
3874 addPropertyAlt(CalendarUri.class, altRepresentations);
3875 }
3876
3877 /**
3878 * <p>
3879 * Adds a calendar URI property as a group of alternative representations
3880 * (see: {@link VCardParameters#getAltId description of ALTID}). An
3881 * appropriate ALTID parameter value is automatically generated and assigned
3882 * to the properties.
3883 * </p>
3884 * <p>
3885 * <b>Property name:</b> {@code CALURI}
3886 * </p>
3887 * <p>
3888 * <b>Supported versions:</b> {@code 4.0}
3889 * </p>
3890 * @param altRepresentations the alternative representations of the property
3891 */
3892 public void addCalendarUriAlt(CalendarUri... altRepresentations) {
3893 addPropertyAlt(CalendarUri.class, altRepresentations);
3894 }
3895
3896 /**
3897 * Gets the URLs that can be used to determine when the person is free
3898 * and/or busy.
3899 * <p>
3900 * <b>Property name:</b> {@code FBURL}
3901 * </p>
3902 * <p>
3903 * <b>Supported versions:</b> {@code 4.0}
3904 * </p>
3905 * @return the free-busy URLs
3906 */
3907 public List<FreeBusyUrl> getFbUrls() {
3908 return getProperties(FreeBusyUrl.class);
3909 }
3910
3911 /**
3912 * Adds a URL that can be used to determine when the person is free and/or
3913 * busy.
3914 * <p>
3915 * <b>Property name:</b> {@code FBURL}
3916 * </p>
3917 * <p>
3918 * <b>Supported versions:</b> {@code 4.0}
3919 * </p>
3920 * @param fbUrl the free-busy URL to add
3921 */
3922 public void addFbUrl(FreeBusyUrl fbUrl) {
3923 addProperty(fbUrl);
3924 }
3925
3926 /**
3927 * <p>
3928 * Adds an fburl property as a group of alternative representations (see:
3929 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3930 * ALTID parameter value is automatically generated and assigned to the
3931 * properties.
3932 * </p>
3933 * <p>
3934 * <b>Property name:</b> {@code FBURL}
3935 * </p>
3936 * <p>
3937 * <b>Supported versions:</b> {@code 4.0}
3938 * @param altRepresentations the alternative representations of the property
3939 */
3940 public void addFbUrlAlt(Collection<FreeBusyUrl> altRepresentations) {
3941 addPropertyAlt(FreeBusyUrl.class, altRepresentations);
3942 }
3943
3944 /**
3945 * <p>
3946 * Adds an fburl property as a group of alternative representations (see:
3947 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
3948 * ALTID parameter value is automatically generated and assigned to the
3949 * properties.
3950 * </p>
3951 * <p>
3952 * <b>Property name:</b> {@code FBURL}
3953 * </p>
3954 * <p>
3955 * <b>Supported versions:</b> {@code 4.0}
3956 * @param altRepresentations the alternative representations of the property
3957 */
3958 public void addFbUrlAlt(FreeBusyUrl... altRepresentations) {
3959 addPropertyAlt(FreeBusyUrl.class, altRepresentations);
3960 }
3961
3962 /**
3963 * Gets the properties that are used to assign globally-unique identifiers
3964 * to individual property instances. CLIENTPIDMAPs are used for merging
3965 * together different versions of the same vCard.
3966 * <p>
3967 * <b>Property name:</b> {@code CLIENTPIDMAP}
3968 * </p>
3969 * <p>
3970 * <b>Supported versions:</b> {@code 4.0}
3971 * </p>
3972 * @return the client PID maps
3973 */
3974 public List<ClientPidMap> getClientPidMaps() {
3975 return getProperties(ClientPidMap.class);
3976 }
3977
3978 /**
3979 * Adds a property that is used to assign a globally-unique identifier to an
3980 * individual property instance. CLIENTPIDMAPs are used for merging together
3981 * different versions of the same vCard.
3982 * <p>
3983 * <b>Property name:</b> {@code CLIENTPIDMAP}
3984 * </p>
3985 * <p>
3986 * <b>Supported versions:</b> {@code 4.0}
3987 * </p>
3988 * @param clientPidMap the client PID map to add
3989 */
3990 public void addClientPidMap(ClientPidMap clientPidMap) {
3991 addProperty(clientPidMap);
3992 }
3993
3994 /**
3995 * Gets any XML data that is attached to the vCard. XML properties may be
3996 * present if the vCard was encoded in XML and the XML document contained
3997 * non-standard elements. The XML vCard properties in this case would
3998 * contain all of the non-standard XML elements.
3999 * <p>
4000 * <b>Property name:</b> {@code XML}
4001 * </p>
4002 * <p>
4003 * <b>Supported versions:</b> {@code 4.0}
4004 * </p>
4005 * @return the XML data
4006 */
4007 public List<Xml> getXmls() {
4008 return getProperties(Xml.class);
4009 }
4010
4011 /**
4012 * Adds XML data to the vCard. XML properties may be present if the vCard
4013 * was encoded in XML and the XML document contained non-standard elements.
4014 * The XML vCard properties in this case would contain all of the
4015 * non-standard XML elements.
4016 * <p>
4017 * <b>Property name:</b> {@code XML}
4018 * </p>
4019 * <p>
4020 * <b>Supported versions:</b> {@code 4.0}
4021 * </p>
4022 * @param xml the XML data to add
4023 */
4024 public void addXml(Xml xml) {
4025 addProperty(xml);
4026 }
4027
4028 /**
4029 * <p>
4030 * Adds an XML property as a group of alternative representations (see:
4031 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
4032 * ALTID parameter value is automatically generated and assigned to the
4033 * properties.
4034 * </p>
4035 * <p>
4036 * <b>Property name:</b> {@code XML}
4037 * </p>
4038 * <p>
4039 * <b>Supported versions:</b> {@code 4.0}
4040 * </p>
4041 * @param altRepresentations the alternative representations of the property
4042 */
4043 public void addXmlAlt(Collection<Xml> altRepresentations) {
4044 addPropertyAlt(Xml.class, altRepresentations);
4045 }
4046
4047 /**
4048 * <p>
4049 * Adds an XML property as a group of alternative representations (see:
4050 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
4051 * ALTID parameter value is automatically generated and assigned to the
4052 * properties.
4053 * </p>
4054 * <p>
4055 * <b>Property name:</b> {@code XML}
4056 * </p>
4057 * <p>
4058 * <b>Supported versions:</b> {@code 4.0}
4059 * </p>
4060 * @param altRepresentations the alternative representations of the property
4061 */
4062 public void addXmlAlt(Xml... altRepresentations) {
4063 addPropertyAlt(Xml.class, altRepresentations);
4064 }
4065
4066 /**
4067 * Gets the professional subject areas of which the the person is
4068 * knowledgeable.
4069 * <p>
4070 * <b>Property name:</b> {@code EXPERTISE}
4071 * </p>
4072 * <p>
4073 * <b>Supported versions:</b> {@code 4.0}
4074 * </p>
4075 * @return the professional skills
4076 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4077 */
4078 public List<Expertise> getExpertise() {
4079 return getProperties(Expertise.class);
4080 }
4081
4082 /**
4083 * Adds a professional subject area of which the the person is
4084 * knowledgeable.
4085 * <p>
4086 * <b>Property name:</b> {@code EXPERTISE}
4087 * </p>
4088 * <p>
4089 * <b>Supported versions:</b> {@code 4.0}
4090 * </p>
4091 * @param expertise the professional skill to add
4092 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4093 */
4094 public void addExpertise(Expertise expertise) {
4095 addProperty(expertise);
4096 }
4097
4098 /**
4099 * Adds a professional subject area of which the the person is
4100 * knowledgeable. This is a convenience method for
4101 * {@link #addExpertise(Expertise)}.
4102 * <p>
4103 * <b>Property name:</b> {@code EXPERTISE}
4104 * </p>
4105 * <p>
4106 * <b>Supported versions:</b> {@code 4.0}
4107 * </p>
4108 * @param expertise the professional skill to add (e.g. "programming")
4109 * @return the property object that was created
4110 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4111 */
4112 public Expertise addExpertise(String expertise) {
4113 Expertise type = new Expertise(expertise);
4114 addExpertise(type);
4115 return type;
4116 }
4117
4118 /**
4119 * <p>
4120 * Adds an expertise property as a group of alternative representations
4121 * (see: {@link VCardParameters#getAltId description of ALTID}). An
4122 * appropriate ALTID parameter value is automatically generated and assigned
4123 * to the properties.
4124 * </p>
4125 * <p>
4126 * <b>Property name:</b> {@code EXPERTISE}
4127 * </p>
4128 * <p>
4129 * <b>Supported versions:</b> {@code 4.0}
4130 * </p>
4131 * @param altRepresentations the alternative representations of the property
4132 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4133 */
4134 public void addExpertiseAlt(Collection<Expertise> altRepresentations) {
4135 addPropertyAlt(Expertise.class, altRepresentations);
4136 }
4137
4138 /**
4139 * <p>
4140 * Adds an expertise property as a group of alternative representations
4141 * (see: {@link VCardParameters#getAltId description of ALTID}). An
4142 * appropriate ALTID parameter value is automatically generated and assigned
4143 * to the properties.
4144 * </p>
4145 * <p>
4146 * <b>Property name:</b> {@code EXPERTISE}
4147 * </p>
4148 * <p>
4149 * <b>Supported versions:</b> {@code 4.0}
4150 * </p>
4151 * @param altRepresentations the alternative representations of the property
4152 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4153 */
4154 public void addExpertiseAlt(Expertise... altRepresentations) {
4155 addPropertyAlt(Expertise.class, altRepresentations);
4156 }
4157
4158 /**
4159 * Gets the hobbies that the person actively engages in.
4160 * <p>
4161 * <b>Property name:</b> {@code HOBBY}
4162 * </p>
4163 * <p>
4164 * <b>Supported versions:</b> {@code 4.0}
4165 * </p>
4166 * @return the hobbies
4167 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4168 */
4169 public List<Hobby> getHobbies() {
4170 return getProperties(Hobby.class);
4171 }
4172
4173 /**
4174 * Adds a hobby that the person actively engages in.
4175 * <p>
4176 * <b>Property name:</b> {@code HOBBY}
4177 * </p>
4178 * <p>
4179 * <b>Supported versions:</b> {@code 4.0}
4180 * </p>
4181 * @param hobby the hobby to add
4182 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4183 */
4184 public void addHobby(Hobby hobby) {
4185 addProperty(hobby);
4186 }
4187
4188 /**
4189 * Adds a hobby that the person actively engages in. This is a convenience
4190 * method for {@link #addHobby(Hobby)}.
4191 * <p>
4192 * <b>Property name:</b> {@code HOBBY}
4193 * </p>
4194 * <p>
4195 * <b>Supported versions:</b> {@code 4.0}
4196 * </p>
4197 * @param hobby the hobby to add (e.g. "photography")
4198 * @return the type objec that was created
4199 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4200 */
4201 public Hobby addHobby(String hobby) {
4202 Hobby type = new Hobby(hobby);
4203 addHobby(type);
4204 return type;
4205 }
4206
4207 /**
4208 * <p>
4209 * Adds a hobby property as a group of alternative representations (see:
4210 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
4211 * ALTID parameter value is automatically generated and assigned to the
4212 * properties.
4213 * </p>
4214 * <p>
4215 * <b>Property name:</b> {@code HOBBY}
4216 * </p>
4217 * <p>
4218 * <b>Supported versions:</b> {@code 4.0}
4219 * @param altRepresentations the alternative representations of the property
4220 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4221 */
4222 public void addHobbyAlt(Collection<Hobby> altRepresentations) {
4223 addPropertyAlt(Hobby.class, altRepresentations);
4224 }
4225
4226 /**
4227 * <p>
4228 * Adds a hobby property as a group of alternative representations (see:
4229 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
4230 * ALTID parameter value is automatically generated and assigned to the
4231 * properties.
4232 * </p>
4233 * <p>
4234 * <b>Property name:</b> {@code HOBBY}
4235 * </p>
4236 * <p>
4237 * <b>Supported versions:</b> {@code 4.0}
4238 * @param altRepresentations the alternative representations of the property
4239 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4240 */
4241 public void addHobbyAlt(Hobby... altRepresentations) {
4242 addPropertyAlt(Hobby.class, altRepresentations);
4243 }
4244
4245 /**
4246 * Gets the person's interests.
4247 * <p>
4248 * <b>Property name:</b> {@code INTEREST}
4249 * </p>
4250 * <p>
4251 * <b>Supported versions:</b> {@code 4.0}
4252 * </p>
4253 * @return the interests
4254 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4255 */
4256 public List<Interest> getInterests() {
4257 return getProperties(Interest.class);
4258 }
4259
4260 /**
4261 * Adds an interest.
4262 * <p>
4263 * <b>Property name:</b> {@code INTEREST}
4264 * </p>
4265 * <p>
4266 * <b>Supported versions:</b> {@code 4.0}
4267 * </p>
4268 * @param interest the interest to add
4269 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4270 */
4271 public void addInterest(Interest interest) {
4272 addProperty(interest);
4273 }
4274
4275 /**
4276 * Adds an interest. This is a convenience method for
4277 * {@link #addInterest(Interest)}.
4278 * <p>
4279 * <b>Property name:</b> {@code INTEREST}
4280 * </p>
4281 * <p>
4282 * <b>Supported versions:</b> {@code 4.0}
4283 * </p>
4284 * @param interest the interest to add (e.g. "football")
4285 * @return the property object that was created
4286 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4287 */
4288 public Interest addInterest(String interest) {
4289 Interest type = new Interest(interest);
4290 addInterest(type);
4291 return type;
4292 }
4293
4294 /**
4295 * <p>
4296 * Adds an interest property as a group of alternative representations (see:
4297 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
4298 * ALTID parameter value is automatically generated and assigned to the
4299 * properties.
4300 * </p>
4301 * <p>
4302 * <b>Property name:</b> {@code INTEREST}
4303 * </p>
4304 * <p>
4305 * <b>Supported versions:</b> {@code 4.0}
4306 * @param altRepresentations the alternative representations of the property
4307 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4308 */
4309 public void addInterestAlt(Collection<Interest> altRepresentations) {
4310 addPropertyAlt(Interest.class, altRepresentations);
4311 }
4312
4313 /**
4314 * <p>
4315 * Adds an interest property as a group of alternative representations (see:
4316 * {@link VCardParameters#getAltId description of ALTID}). An appropriate
4317 * ALTID parameter value is automatically generated and assigned to the
4318 * properties.
4319 * </p>
4320 * <p>
4321 * <b>Property name:</b> {@code INTEREST}
4322 * </p>
4323 * <p>
4324 * <b>Supported versions:</b> {@code 4.0}
4325 * @param altRepresentations the alternative representations of the property
4326 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4327 */
4328 public void addInterestAlt(Interest... altRepresentations) {
4329 addPropertyAlt(Interest.class, altRepresentations);
4330 }
4331
4332 /**
4333 * Gets the organization directories.
4334 * <p>
4335 * <b>Property name:</b> {@code ORG-DIRECTORY}
4336 * </p>
4337 * <p>
4338 * <b>Supported versions:</b> {@code 4.0}
4339 * </p>
4340 * @return the organization directories
4341 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4342 */
4343 public List<OrgDirectory> getOrgDirectories() {
4344 return getProperties(OrgDirectory.class);
4345 }
4346
4347 /**
4348 * Adds an organization directory.
4349 * <p>
4350 * <b>Property name:</b> {@code ORG-DIRECTORY}
4351 * </p>
4352 * <p>
4353 * <b>Supported versions:</b> {@code 4.0}
4354 * </p>
4355 * @param orgDirectory the organization directory to add
4356 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4357 */
4358 public void addOrgDirectory(OrgDirectory orgDirectory) {
4359 addProperty(orgDirectory);
4360 }
4361
4362 /**
4363 * Adds an organization directory. This is a convenience method for
4364 * {@link #addOrgDirectory(OrgDirectory)}.
4365 * <p>
4366 * <b>Property name:</b> {@code ORG-DIRECTORY}
4367 * </p>
4368 * <p>
4369 * <b>Supported versions:</b> {@code 4.0}
4370 * </p>
4371 * @param orgDirectory the organization directory to add (e.g.
4372 * "http://company.com/staff")
4373 * @return the property object that was created
4374 * @see <a href="http://tools.ietf.org/html/rfc6715">RFC 6715</a>
4375 */
4376 public OrgDirectory addOrgDirectory(String orgDirectory) {
4377 OrgDirectory type = new OrgDirectory(orgDirectory);
4378 addOrgDirectory(type);
4379 return type;
4380 }
4381
4382 /**
4383 * <p>
4384 * Adds an org directory property as a group of alternative representations
4385 * (see: {@link VCardParameters#getAltId description of ALTID}). An
4386 * appropriate ALTID parameter value is automatically generated and assigned
4387 * to the properties.
4388 * </p>
4389 * <p>
4390 * <b>Property name:</b> {@code ORG-DIRECTORY}
4391 * </p>
4392 * <p>
4393 * <b>Supported versions:</b> {@code 4.0}
4394 * </p>
4395 * @param altRepresentations the alternative representations of the property
4396 */
4397 public void addOrgDirectoryAlt(Collection<OrgDirectory> altRepresentations) {
4398 addPropertyAlt(OrgDirectory.class, altRepresentations);
4399 }
4400
4401 /**
4402 * <p>
4403 * Adds an org directory property as a group of alternative representations
4404 * (see: {@link VCardParameters#getAltId description of ALTID}). An
4405 * appropriate ALTID parameter value is automatically generated and assigned
4406 * to the properties.
4407 * </p>
4408 * <p>
4409 * <b>Property name:</b> {@code ORG-DIRECTORY}
4410 * </p>
4411 * <p>
4412 * <b>Supported versions:</b> {@code 4.0}
4413 * </p>
4414 * @param altRepresentations the alternative representations of the property
4415 */
4416 public void addOrgDirectoryAlt(OrgDirectory... altRepresentations) {
4417 addPropertyAlt(OrgDirectory.class, altRepresentations);
4418 }
4419
4420 /**
4421 * Iterates through each of the vCard's properties in no particular order.
4422 * Does not include the "BEGIN", "END", or "VERSION" properties.
4423 * @return the iterator
4424 */
4425 public Iterator<VCardProperty> iterator() {
4426 return properties.values().iterator();
4427 }
4428
4429 /**
4430 * Gets the first property of a given class.
4431 * @param clazz the property class
4432 * @return the property or null if not found
4433 */
4434 public <T extends VCardProperty> T getProperty(Class<T> clazz) {
4435 return clazz.cast(properties.first(clazz));
4436 }
4437
4438 /**
4439 * Gets all properties of a given class.
4440 * @param clazz the property class
4441 * @return the properties
4442 */
4443 public <T extends VCardProperty> List<T> getProperties(Class<T> clazz) {
4444 List<VCardProperty> props = properties.get(clazz);
4445
4446 //cast to the requested class
4447 List<T> ret = new ArrayList<T>(props.size());
4448 for (VCardProperty property : props) {
4449 ret.add(clazz.cast(property));
4450 }
4451 return ret;
4452 }
4453
4454 /**
4455 * Gets all properties of a given class, grouping the alternative
4456 * representations of each property together (see:
4457 * {@link VCardParameters#getAltId description of ALTID})
4458 * @param clazz the property class
4459 * @return the properties
4460 */
4461 public <T extends VCardProperty & HasAltId> List<List<T>> getPropertiesAlt(Class<T> clazz) {
4462 List<T> nullAltId = new ArrayList<T>();
4463 ListMultimap<String, T> map = new ListMultimap<String, T>();
4464 for (T property : getProperties(clazz)) {
4465 String altId = property.getAltId();
4466 if (altId == null) {
4467 nullAltId.add(property);
4468 } else {
4469 map.put(altId, property);
4470 }
4471 }
4472
4473 List<List<T>> list = new ArrayList<List<T>>();
4474 for (Map.Entry<String, List<T>> entry : map) {
4475 list.add(entry.getValue());
4476 }
4477
4478 //put properties without ALTIDs at the end
4479 for (T property : nullAltId) {
4480 List<T> l = new ArrayList<T>(1);
4481 l.add(property);
4482 list.add(l);
4483 }
4484
4485 return list;
4486 }
4487
4488 /**
4489 * Gets all the properties in this vCard.
4490 * @return the properties
4491 */
4492 public Collection<VCardProperty> getProperties() {
4493 return properties.values();
4494 }
4495
4496 /**
4497 * Adds a property.
4498 * @param property the property to add
4499 */
4500 public void addProperty(VCardProperty property) {
4501 properties.put(property.getClass(), property);
4502 }
4503
4504 /**
4505 * Replaces all existing properties of the given class with a single
4506 * property instance. If the property instance is null, then all instances
4507 * of that property will be removed.
4508 * @param clazz the property class (e.g. "Note.class")
4509 * @param property the property or null to remove
4510 */
4511 public <T extends VCardProperty> void setProperty(Class<T> clazz, T property) {
4512 properties.replace(clazz, property);
4513 }
4514
4515 /**
4516 * Removes a property instance from the vCard.
4517 * @param property the property to remove
4518 */
4519 public void removeProperty(VCardProperty property) {
4520 properties.remove(property.getClass(), property);
4521 }
4522
4523 /**
4524 * Removes all properties of a given class.
4525 * @param clazz the class of the properties to remove (e.g. "Note.class")
4526 */
4527 public void removeProperties(Class<? extends VCardProperty> clazz) {
4528 properties.removeAll(clazz);
4529 }
4530
4531 /**
4532 * Gets the first extended property with a given name.
4533 * @param name the property name (e.g. "X-ALT-DESC")
4534 * @return the property or null if none were found
4535 */
4536 public RawProperty getExtendedProperty(String name) {
4537 for (RawProperty raw : getProperties(RawProperty.class)) {
4538 if (raw.getPropertyName().equalsIgnoreCase(name)) {
4539 return raw;
4540 }
4541 }
4542 return null;
4543 }
4544
4545 /**
4546 * Gets all extended properties with a given name.
4547 * @param name the property name (e.g. "X-ALT-DESC")
4548 * @return the properties
4549 */
4550 public List<RawProperty> getExtendedProperties(String name) {
4551 List<RawProperty> props = new ArrayList<RawProperty>();
4552
4553 for (RawProperty raw : getProperties(RawProperty.class)) {
4554 if (raw.getPropertyName().equalsIgnoreCase(name)) {
4555 props.add(raw);
4556 }
4557 }
4558
4559 return props;
4560 }
4561
4562 /**
4563 * Gets all extended properties.
4564 * @return the properties
4565 */
4566 public List<RawProperty> getExtendedProperties() {
4567 return getProperties(RawProperty.class);
4568 }
4569
4570 /**
4571 * Adds an extended property.
4572 * @param name the property name (e.g. "X-ALT-DESC")
4573 * @param value the property value
4574 * @return the property object that was created
4575 */
4576 public RawProperty addExtendedProperty(String name, String value) {
4577 RawProperty raw = new RawProperty(name, value);
4578 addProperty(raw);
4579 return raw;
4580 }
4581
4582 /**
4583 * Replaces all existing extended properties with the given name with a
4584 * single property instance.
4585 * @param name the property name (e.g. "X-ALT-DESC")
4586 * @param value the property value
4587 * @return the property object that was created
4588 */
4589 public RawProperty setExtendedProperty(String name, String value) {
4590 removeExtendedProperty(name);
4591 RawProperty raw = new RawProperty(name, value);
4592 addProperty(raw);
4593 return raw;
4594 }
4595
4596 /**
4597 * Removes all extended properties that have the given name.
4598 * @param name the component name (e.g. "X-ALT-DESC")
4599 */
4600 public void removeExtendedProperty(String name) {
4601 List<RawProperty> xproperties = getExtendedProperties(name);
4602 for (RawProperty xproperty : xproperties) {
4603 properties.remove(xproperty.getClass(), xproperty);
4604 }
4605 }
4606
4607 /**
4608 * Adds a property in the form of a collection of alternative
4609 * representations. This method will generate a unique ALTID parameter value
4610 * and assign it to each of the property instances (see:
4611 * {@link VCardParameters#getAltId description of ALTID}).
4612 * @param propertyClass the property class
4613 * @param altRepresentations the alternative representations of the property
4614 * to add
4615 */
4616 public <T extends VCardProperty & HasAltId> void addPropertyAlt(Class<T> propertyClass, T... altRepresentations) {
4617 addPropertyAlt(propertyClass, Arrays.asList(altRepresentations));
4618 }
4619
4620 /**
4621 * Adds a property in the form of a collection of alternative
4622 * representations. This method will generate a unique ALTID parameter value
4623 * and assign it to each of the property instances (see:
4624 * {@link VCardParameters#getAltId description of ALTID}).
4625 * @param propertyClass the property class
4626 * @param altRepresentations the alternative representations of the property
4627 * to add
4628 */
4629 public <T extends VCardProperty & HasAltId> void addPropertyAlt(Class<T> propertyClass, Collection<T> altRepresentations) {
4630 String altId = generateAltId(getProperties(propertyClass));
4631 for (T property : altRepresentations) {
4632 property.setAltId(altId);
4633 addProperty(property);
4634 }
4635 }
4636
4637 /**
4638 * Sets a property in the form of a collection of alternative
4639 * representations. This method will generate a unique ALTID parameter value
4640 * and assign it to each of the property instances (see:
4641 * {@link VCardParameters#getAltId description of ALTID}).
4642 * @param propertyClass the property class
4643 * @param altRepresentations the alternative representations of the property
4644 * to add
4645 */
4646 public <T extends VCardProperty & HasAltId> void setPropertyAlt(Class<T> propertyClass, T... altRepresentations) {
4647 removeProperties(propertyClass);
4648 addPropertyAlt(propertyClass, altRepresentations);
4649 }
4650
4651 /**
4652 * Sets a property in the form of a collection of alternative
4653 * representations. This method will generate a unique ALTID parameter value
4654 * and assign it to each of the property instances (see:
4655 * {@link VCardParameters#getAltId description of ALTID}).
4656 * @param propertyClass the property class
4657 * @param altRepresentations the alternative representations of the property
4658 * to add
4659 */
4660 public <T extends VCardProperty & HasAltId> void setPropertyAlt(Class<T> propertyClass, Collection<T> altRepresentations) {
4661 removeProperties(propertyClass);
4662 addPropertyAlt(propertyClass, altRepresentations);
4663 }
4664
4665 /**
4666 * Checks this vCard for data consistency problems or deviations from the
4667 * spec. These problems will not prevent the vCard from being written to a
4668 * data stream, but may prevent it from being parsed correctly by the
4669 * consuming application. These problems can largely be avoided by reading
4670 * the Javadocs of the property classes, or by being familiar with the vCard
4671 * standard.
4672 * @param version the version to check the vCard against (use 4.0 for xCard
4673 * and jCard)
4674 * @return the validation warnings
4675 */
4676 public ValidationWarnings validate(VCardVersion version) {
4677 ValidationWarnings warnings = new ValidationWarnings();
4678
4679 //validate overall vCard object
4680 if (getStructuredName() == null && (version == VCardVersion.V2_1 || version == VCardVersion.V3_0)) {
4681 warnings.add(null, new Warning(0));
4682 }
4683 if (getFormattedName() == null && (version == VCardVersion.V3_0 || version == VCardVersion.V4_0)) {
4684 warnings.add(null, new Warning(1));
4685 }
4686
4687 //validate properties
4688 for (VCardProperty property : this) {
4689 List<Warning> propWarnings = property.validate(version, this);
4690 if (!propWarnings.isEmpty()) {
4691 warnings.add(property, propWarnings);
4692 }
4693 }
4694
4695 return warnings;
4696 }
4697
4698 /**
4699 * Generates a unique ALTID parameter value.
4700 * @param properties the collection of properties under which the ALTID must
4701 * be unique
4702 * @return a unique ALTID
4703 */
4704 static <T extends HasAltId> String generateAltId(Collection<T> properties) {
4705 Set<String> altIds = new HashSet<String>();
4706 for (T property : properties) {
4707 String altId = property.getAltId();
4708 if (altId != null) {
4709 altIds.add(altId);
4710 }
4711 }
4712
4713 int altId = 1;
4714 while (altIds.contains(altId + "")) {
4715 altId++;
4716 }
4717 return altId + "";
4718 }
4719 }