001 package ezvcard.property;
002
003 import java.util.ArrayList;
004 import java.util.List;
005
006 import ezvcard.parameter.VCardParameters;
007
008 /*
009 Copyright (c) 2013, Michael Angstadt
010 All rights reserved.
011
012 Redistribution and use in source and binary forms, with or without
013 modification, are permitted provided that the following conditions are met:
014
015 1. Redistributions of source code must retain the above copyright notice, this
016 list of conditions and the following disclaimer.
017 2. Redistributions in binary form must reproduce the above copyright notice,
018 this list of conditions and the following disclaimer in the documentation
019 and/or other materials provided with the distribution.
020
021 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
022 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
023 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
024 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
025 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
026 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
027 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
028 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
029 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
030 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
031
032 The views and conclusions contained in the software and documentation are those
033 of the authors and should not be interpreted as representing official policies,
034 either expressed or implied, of the FreeBSD Project.
035 */
036
037 /**
038 * Contains the separated components of the person's name.
039 *
040 * <p>
041 * <b>Code sample</b>
042 * </p>
043 *
044 * <pre class="brush:java">
045 * VCard vcard = new VCard();
046 * StructuredName n = new StructuredName();
047 * n.setFamily("House");
048 * n.setGiven("Gregory");
049 * n.addPrefix("Dr");
050 * n.addSuffix("MD");
051 * vcard.setStructuredName(n);
052 * </pre>
053 *
054 * <p>
055 * <b>Property name:</b> {@code N}
056 * </p>
057 * <p>
058 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
059 * </p>
060 * @author Michael Angstadt
061 */
062 public class StructuredName extends VCardProperty implements HasAltId {
063 private String family;
064 private String given;
065 private List<String> additional = new ArrayList<String>();
066 private List<String> prefixes = new ArrayList<String>();
067 private List<String> suffixes = new ArrayList<String>();
068
069 /**
070 * Gets the family name (aka "last name").
071 * @return the family name or null if not set
072 */
073 public String getFamily() {
074 return family;
075 }
076
077 /**
078 * Sets the family name (aka "last name").
079 * @param family the family name or null to remove
080 */
081 public void setFamily(String family) {
082 this.family = family;
083 }
084
085 /**
086 * Gets the given name (aka "first name").
087 * @return the given name or null if not set
088 */
089 public String getGiven() {
090 return given;
091 }
092
093 /**
094 * Sets the given name (aka "first name").
095 * @param given the given name or null to remove
096 */
097 public void setGiven(String given) {
098 this.given = given;
099 }
100
101 /**
102 * Gets any additional names the person goes by.
103 * @return the additional names or empty list if there are none
104 */
105 public List<String> getAdditional() {
106 return additional;
107 }
108
109 /**
110 * Adds an additional name the person goes by.
111 * @param additional the additional name to add
112 */
113 public void addAdditional(String additional) {
114 this.additional.add(additional);
115 }
116
117 /**
118 * Gets the prefixes.
119 * @return the prefixes (e.g. "Mr.") or empty list if there are none
120 */
121 public List<String> getPrefixes() {
122 return prefixes;
123 }
124
125 /**
126 * Adds a prefix.
127 * @param prefix the prefix to add (e.g. "Mr.")
128 */
129 public void addPrefix(String prefix) {
130 this.prefixes.add(prefix);
131 }
132
133 /**
134 * Gets the suffixes.
135 * @return the suffixes (e.g. "Jr.") or empty list if there are none
136 */
137 public List<String> getSuffixes() {
138 return suffixes;
139 }
140
141 /**
142 * Adds a suffix.
143 * @param suffix the suffix to add (e.g. "Jr.")
144 */
145 public void addSuffix(String suffix) {
146 this.suffixes.add(suffix);
147 }
148
149 /**
150 * Gets the string(s) that define how to sort the vCard.
151 * <p>
152 * 2.1 and 3.0 vCards should use the {@link SortString SORT-STRING}
153 * property instead.
154 * </p>
155 * <p>
156 * <b>Supported versions:</b> {@code 4.0}
157 * </p>
158 * @return the sort string(s) (e.g. ["Aboville", "Christine"] if the family
159 * name is "d'Aboville" and the given name is "Christine") or empty list if
160 * there are none
161 * @see VCardParameters#getSortAs
162 */
163 public List<String> getSortAs() {
164 return parameters.getSortAs();
165 }
166
167 /**
168 * Sets the string that defines how to sort the vCard.
169 * <p>
170 * 2.1 and 3.0 vCards should use the {@link SortString SORT-STRING}
171 * property instead.
172 * </p>
173 * <p>
174 * <b>Supported versions:</b> {@code 4.0}
175 * </p>
176 * @param family the sorttable family name (e.g. "Adboville" if the family
177 * name is "d'Aboville") or null to remove
178 */
179 public void setSortAs(String family) {
180 if (family == null) {
181 parameters.setSortAs();
182 } else {
183 parameters.setSortAs(family);
184 }
185 }
186
187 /**
188 * Sets the strings that define how to sort the vCard.
189 * <p>
190 * 2.1 and 3.0 vCards should use the {@link SortString SORT-STRING}
191 * property instead.
192 * </p>
193 * <p>
194 * <b>Supported versions:</b> {@code 4.0}
195 * </p>
196 * @param family the sortable family name (e.g. "Adboville" if the family
197 * name is "d'Aboville")
198 * @param given the sortable given name
199 */
200 public void setSortAs(String family, String given) {
201 parameters.setSortAs(family, given);
202 }
203
204 @Override
205 public String getLanguage() {
206 return super.getLanguage();
207 }
208
209 @Override
210 public void setLanguage(String language) {
211 super.setLanguage(language);
212 }
213
214 //@Override
215 public String getAltId() {
216 return parameters.getAltId();
217 }
218
219 //@Override
220 public void setAltId(String altId) {
221 parameters.setAltId(altId);
222 }
223 }