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