001 package biweekly.property;
002
003 import java.util.ArrayList;
004 import java.util.Collection;
005 import java.util.List;
006
007 import biweekly.ICalendar;
008 import biweekly.component.ICalComponent;
009 import biweekly.component.VTimezone;
010 import biweekly.parameter.ICalParameters;
011
012 /*
013 Copyright (c) 2013, Michael Angstadt
014 All rights reserved.
015
016 Redistribution and use in source and binary forms, with or without
017 modification, are permitted provided that the following conditions are met:
018
019 1. Redistributions of source code must retain the above copyright notice, this
020 list of conditions and the following disclaimer.
021 2. Redistributions in binary form must reproduce the above copyright notice,
022 this list of conditions and the following disclaimer in the documentation
023 and/or other materials provided with the distribution.
024
025 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
026 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
027 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
028 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
029 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
030 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
031 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
032 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
033 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
034 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
035 */
036
037 /**
038 * Base class for all iCalendar properties.
039 * @author Michael Angstadt
040 */
041 public abstract class ICalProperty {
042 /**
043 * The property parameters.
044 */
045 protected ICalParameters parameters = new ICalParameters();
046
047 /**
048 * Gets the property's parameters.
049 * @return the parameters
050 */
051 public ICalParameters getParameters() {
052 return parameters;
053 }
054
055 /**
056 * Sets the property's parameters
057 * @param parameters the parameters
058 */
059 public void setParameters(ICalParameters parameters) {
060 this.parameters = parameters;
061 }
062
063 /**
064 * Gets the first value of a parameter with the given name.
065 * @param name the parameter name (case insensitive, e.g. "LANGUAGE")
066 * @return the parameter value or null if not found
067 */
068 public String getParameter(String name) {
069 return parameters.first(name);
070 }
071
072 /**
073 * Gets all values of a parameter with the given name.
074 * @param name the parameter name (case insensitive, e.g. "LANGUAGE")
075 * @return the parameter values
076 */
077 public List<String> getParameters(String name) {
078 return parameters.get(name);
079 }
080
081 /**
082 * Adds a value to a parameter.
083 * @param name the parameter name (case insensitive, e.g. "LANGUAGE")
084 * @param value the parameter value
085 */
086 public void addParameter(String name, String value) {
087 parameters.put(name, value);
088 }
089
090 /**
091 * Replaces all existing values of a parameter with the given value.
092 * @param name the parameter name (case insensitive, e.g. "LANGUAGE")
093 * @param value the parameter value
094 */
095 public void setParameter(String name, String value) {
096 parameters.replace(name, value);
097 }
098
099 /**
100 * Replaces all existing values of a parameter with the given values.
101 * @param name the parameter name (case insensitive, e.g. "LANGUAGE")
102 * @param values the parameter values
103 */
104 public void setParameter(String name, Collection<String> values) {
105 parameters.replace(name, values);
106 }
107
108 /**
109 * Removes a parameter from the property.
110 * @param name the parameter name (case insensitive, e.g. "LANGUAGE")
111 */
112 public void removeParameter(String name) {
113 parameters.removeAll(name);
114 }
115
116 //Note: The following parameter helper methods are package-scoped to prevent them from cluttering up the Javadocs
117
118 /**
119 * Gets a URI pointing to additional information about the entity
120 * represented by the property.
121 * @return the URI or null if not set
122 * @rfc 5545 p.14-5
123 */
124 String getAltRepresentation() {
125 return parameters.getAltRepresentation();
126 }
127
128 /**
129 * Sets a URI pointing to additional information about the entity
130 * represented by the property.
131 * @param uri the URI or null to remove
132 * @rfc 5545 p.14-5
133 */
134 void setAltRepresentation(String uri) {
135 parameters.setAltRepresentation(uri);
136 }
137
138 /**
139 * Gets the content-type of the property's value.
140 * @return the content type (e.g. "image/png") or null if not set
141 * @rfc 5545 p.19-20
142 */
143 String getFormatType() {
144 return parameters.getFormatType();
145 }
146
147 /**
148 * Sets the content-type of the property's value.
149 * @param formatType the content type (e.g. "image/png") or null to remove
150 * @rfc 5545 p.19-20
151 */
152 void setFormatType(String formatType) {
153 parameters.setFormatType(formatType);
154 }
155
156 /**
157 * Gets the language that the property value is written in.
158 * @return the language (e.g. "en" for English) or null if not set
159 * @rfc 5545 p.21
160 */
161 String getLanguage() {
162 return parameters.getLanguage();
163 }
164
165 /**
166 * Sets the language that the property value is written in.
167 * @param language the language (e.g. "en" for English) or null to remove
168 * @rfc 5545 p.21
169 */
170 void setLanguage(String language) {
171 parameters.setLanguage(language);
172 }
173
174 /**
175 * Gets the timezone identifier. This either (a) references the
176 * {@link TimezoneId} property of a {@link VTimezone} component, or (b)
177 * specifies a globally-defined timezone (e.g. "America/New_York"). For a
178 * list of globally-defined timezones, see the <a
179 * href="http://www.twinsun.com/tz/tz-link.htm">TZ database</a>.
180 * @return the timezone identifier or null if not set
181 * @rfc 5545 p.27-8
182 */
183 String getTimezoneId() {
184 return parameters.getTimezoneId();
185 }
186
187 /**
188 * Sets the timezone identifier. This either (a) references the
189 * {@link TimezoneId} property of a {@link VTimezone} component, or (b)
190 * specifies a globally-defined timezone (e.g. "America/New_York"). For a
191 * list of globally-defined timezones, see the <a
192 * href="http://www.twinsun.com/tz/tz-link.htm">TZ database</a>.
193 * @param timezoneId the timezone identifier (e.g. "America/New_York") or
194 * null to remove
195 * @rfc 5545 p.27-8
196 */
197 void setTimezoneId(String timezoneId) {
198 parameters.setTimezoneId(timezoneId);
199 }
200
201 /**
202 * Sets the property's timezone to a timezone that is defined within the
203 * iCalendar object. Use {@link #setTimezoneId(String)} to use a
204 * globally-defined timezone (e.g. "America/New_York").
205 * @param timezone the timezone component to reference or null to remove
206 * @rfc 5545 p.27-8
207 */
208 void setTimezone(VTimezone timezone) {
209 if (timezone == null) {
210 setTimezoneId(null);
211 return;
212 }
213
214 TimezoneId tzid = timezone.getTimezoneId();
215 if (tzid != null) {
216 setTimezoneId(tzid.getValue());
217 }
218 }
219
220 /**
221 * Gets a person that is acting on behalf of the person defined in the
222 * property.
223 * @return a URI representing the person (typically, an email URI, e.g.
224 * "mailto:janedoe@example.com") or null if not set
225 * @rfc 5545 p.27
226 */
227 String getSentBy() {
228 return parameters.getSentBy();
229 }
230
231 /**
232 * Sets a person that is acting on behalf of the person defined in the
233 * property.
234 * @param uri a URI representing the person (typically, an email URI, e.g.
235 * "mailto:janedoe@example.com") or null to remove
236 * @rfc 5545 p.27
237 */
238 void setSentBy(String uri) {
239 parameters.setSentBy(uri);
240 }
241
242 /**
243 * Gets the display name of the person.
244 * @return the display name (e.g. "John Doe") or null if not set
245 * @rfc 5545 p.15-6
246 */
247 String getCommonName() {
248 return parameters.getCommonName();
249 }
250
251 /**
252 * Sets the display name of the person.
253 * @param commonName the display name (e.g. "John Doe") or null to remove
254 * @rfc 5545 p.15-6
255 */
256 void setCommonName(String commonName) {
257 parameters.setCommonName(commonName);
258 }
259
260 /**
261 * Gets a URI that contains additional information about the person.
262 * @return the URI (e.g. an LDAP URI) or null if not set
263 * @rfc 5545 p.18
264 */
265 String getDirectoryEntry() {
266 return parameters.getDirectoryEntry();
267 }
268
269 /**
270 * Sets a URI that contains additional information about the person.
271 * @param uri the URI (e.g. an LDAP URI) or null to remove
272 * @rfc 5545 p.18
273 */
274 void setDirectoryEntry(String uri) {
275 parameters.setDirectoryEntry(uri);
276 }
277
278 /**
279 * Checks the property for data consistency problems or deviations from the
280 * spec. These problems will not prevent the property from being written to
281 * a data stream, but may prevent it from being parsed correctly by the
282 * consuming application. These problems can largely be avoided by reading
283 * the Javadocs of the property class, or by being familiar with the
284 * iCalendar standard.
285 * @param components the hierarchy of components that the property belongs
286 * to
287 * @see ICalendar#validate
288 * @return a list of warnings or an empty list if no problems were found
289 */
290 public final List<String> validate(List<ICalComponent> components) {
291 //validate property value
292 List<String> warnings = new ArrayList<String>(0);
293 validate(components, warnings);
294
295 //validate parameters
296 warnings.addAll(parameters.validate());
297
298 return warnings;
299 }
300
301 /**
302 * Checks the property for data consistency problems or deviations from the
303 * spec. Meant to be overridden by child classes that wish to provide
304 * validation logic.
305 * @param components the hierarchy of components that the property belongs
306 * to
307 * @param warnings the list to add the warnings to
308 */
309 protected void validate(List<ICalComponent> components, List<String> warnings) {
310 //do nothing
311 }
312 }