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}