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