001package ezvcard.property;
002
003import java.util.List;
004
005import ezvcard.SupportedVersions;
006import ezvcard.VCard;
007import ezvcard.VCardVersion;
008import ezvcard.parameter.AddressType;
009
010/*
011 Copyright (c) 2012-2023, Michael Angstadt
012 All rights reserved.
013
014 Redistribution and use in source and binary forms, with or without
015 modification, are permitted provided that the following conditions are met: 
016
017 1. Redistributions of source code must retain the above copyright notice, this
018 list of conditions and the following disclaimer. 
019 2. Redistributions in binary form must reproduce the above copyright notice,
020 this list of conditions and the following disclaimer in the documentation
021 and/or other materials provided with the distribution. 
022
023 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
024 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
025 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
026 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
027 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
028 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
029 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
030 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
031 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
032 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
033
034 The views and conclusions contained in the software and documentation are those
035 of the authors and should not be interpreted as representing official policies, 
036 either expressed or implied, of the FreeBSD Project.
037 */
038
039/**
040 * <p>
041 * Defines the exact text to put on the mailing label when sending snail mail to
042 * the person. Note that instances of this class should NEVER be added to a
043 * vCard! Instead, use the {@link Address#setLabel} method to assign a mailing
044 * label to an {@link Address} property.
045 * </p>
046 * 
047 * <p>
048 * <b>Version interoperability</b>
049 * </p>
050 * 
051 * <p>
052 * The label property is not supported in vCard version 4.0. Instead, labels are
053 * included as <i>parameters</i> to their corresponding {@link Address}
054 * properties. When marshalling a vCard, ez-vcard will use either the label
055 * property or the LABEL parameter, depending on the requested vCard version.
056 * </p>
057 * 
058 * <p>
059 * <b>Orphaned labels</b>
060 * </p>
061 * 
062 * <p>
063 * ez-vcard defines an "orphaned label" as a label property that could not be
064 * assigned to an address (a label is assigned to an address if its list of TYPE
065 * parameters is identical to the address's list of TYPE parameters). The
066 * {@link VCard#addOrphanedLabel} method can be used to add such labels to a
067 * vCard, but its use is strongly discouraged. The
068 * {@link VCard#getOrphanedLabels} method can be useful when parsing version 2.1
069 * or 3.0 vCards in order to retrieve any label properties that the parser could
070 * not assign to an address.
071 * </p>
072 * 
073 * <p>
074 * <b>Property name:</b> {@code LABEL}
075 * </p>
076 * <p>
077 * <b>Supported versions:</b> {@code 2.1, 3.0}
078 * </p>
079 * @author Michael Angstadt
080 * @see <a href="http://tools.ietf.org/html/rfc2426#page-13">RFC 2426 p.13</a>
081 * @see <a href="http://www.imc.org/pdi/vcard-21.doc">vCard 2.1 p.12</a>
082 */
083@SupportedVersions({ VCardVersion.V2_1, VCardVersion.V3_0 })
084public class Label extends TextProperty {
085        /**
086         * Creates a label property.
087         * @param label the label value
088         */
089        public Label(String label) {
090                super(label);
091        }
092
093        /**
094         * Copy constructor.
095         * @param original the property to make a copy of
096         */
097        public Label(Label original) {
098                super(original);
099        }
100
101        /**
102         * Gets the list that stores this property's address types (TYPE
103         * parameters).
104         * @return the address types (e.g. "HOME", "WORK") (this list is mutable)
105         */
106        public List<AddressType> getTypes() {
107                return parameters.new TypeParameterList<AddressType>() {
108                        @Override
109                        protected AddressType _asObject(String value) {
110                                return AddressType.get(value);
111                        }
112                };
113        }
114
115        @Override
116        public String getLanguage() {
117                return super.getLanguage();
118        }
119
120        @Override
121        public void setLanguage(String language) {
122                super.setLanguage(language);
123        }
124
125        @Override
126        public Label copy() {
127                return new Label(this);
128        }
129}