001 package ezvcard.property;
002
003 import java.util.EnumSet;
004 import java.util.HashSet;
005 import java.util.Set;
006
007 import ezvcard.VCard;
008 import ezvcard.VCardVersion;
009 import ezvcard.parameter.AddressType;
010
011 /*
012 Copyright (c) 2013, Michael Angstadt
013 All rights reserved.
014
015 Redistribution and use in source and binary forms, with or without
016 modification, are permitted provided that the following conditions are met:
017
018 1. Redistributions of source code must retain the above copyright notice, this
019 list of conditions and the following disclaimer.
020 2. Redistributions in binary form must reproduce the above copyright notice,
021 this list of conditions and the following disclaimer in the documentation
022 and/or other materials provided with the distribution.
023
024 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
025 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
026 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
027 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
028 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
029 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
030 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
031 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
032 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
033 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
034
035 The views and conclusions contained in the software and documentation are those
036 of the authors and should not be interpreted as representing official policies,
037 either expressed or implied, of the FreeBSD Project.
038 */
039
040 /**
041 * <p>
042 * Defines the exact text to put on the mailing label when mailing a package or
043 * letter to the person.
044 * </p>
045 *
046 * <p>
047 * The LABEL property is not supported in 4.0. Instead, labels are included as a
048 * parameter to their corresponding {@link Address}. When marshalling a vCard,
049 * ez-vcard will use either the LABEL property or the LABEL parameter, depending
050 * on the requested vCard version.
051 * </p>
052 *
053 * <p>
054 * To add a label to a vCard, the {@link Address#setLabel} method should be
055 * used.
056 * </p>
057 *
058 * <pre class="brush:java">
059 * VCard vcard = new VCard();
060 * Address adr = new Address();
061 * adr.setStreetAddress("123 Main St.");
062 * adr.setLocality("Austin");
063 * adr.setRegion("TX");
064 * adr.setPostalCode("12345");
065 * adr.setLabel("123 Main St.\nAustin, TX 12345"); //newlines are allowed
066 * vcard.addAddress(adr);
067 * </pre>
068 *
069 * <p>
070 * The {@link VCard#addOrphanedLabel} method adds a LABEL property to the vCard.
071 * However, use of this method is discouraged because it creates a LABEL
072 * property that's not associated with an address. Also, orphaned LABEL
073 * properties are ignored when creating version 4.0 vCards because the LABEL
074 * property is not supported by vCard 4.0.
075 * </p>
076 *
077 * <p>
078 * The {@link VCard#getOrphanedLabels} method can be used after parsing a
079 * version 2.1 or 3.0 vCard to retrieve any LABEL properties which the parser
080 * could not assign to an address. A LABEL is assigned to an address if the
081 * LABEL's list of TYPE parameters is identical to the address's list of TYPE
082 * parameters.
083 * </p>
084 *
085 * <pre class="brush:java">
086 * VCard vcard = ...
087 * for (Label label : vcard.getOrphanedLabels()) {
088 * System.out.println(label.getValue());
089 * }
090 * </pre>
091 *
092 * <p>
093 * <b>Property name:</b> {@code LABEL}
094 * </p>
095 * <p>
096 * <b>Supported versions:</b> {@code 2.1, 3.0}
097 * </p>
098 * @author Michael Angstadt
099 */
100 public class Label extends TextProperty {
101 /**
102 * Creates a label property.
103 * @param label the label value
104 */
105 public Label(String label) {
106 super(label);
107 }
108
109 @Override
110 public Set<VCardVersion> _supportedVersions() {
111 return EnumSet.of(VCardVersion.V2_1, VCardVersion.V3_0);
112 }
113
114 /**
115 * Gets all the TYPE parameters.
116 * @return the TYPE parameters or empty set if there are none
117 */
118 public Set<AddressType> getTypes() {
119 Set<String> values = parameters.getTypes();
120 Set<AddressType> types = new HashSet<AddressType>(values.size());
121 for (String value : values) {
122 types.add(AddressType.get(value));
123 }
124 return types;
125 }
126
127 /**
128 * Adds a TYPE parameter.
129 * @param type the TYPE parameter to add
130 */
131 public void addType(AddressType type) {
132 parameters.addType(type.getValue());
133 }
134
135 /**
136 * Removes a TYPE parameter.
137 * @param type the TYPE parameter to remove
138 */
139 public void removeType(AddressType type) {
140 parameters.removeType(type.getValue());
141 }
142
143 @Override
144 public String getLanguage() {
145 return super.getLanguage();
146 }
147
148 @Override
149 public void setLanguage(String language) {
150 super.setLanguage(language);
151 }
152 }