michael@0: /**
michael@0: * Copyright (c) 2012, Ben Fortuna
michael@0: * All rights reserved.
michael@0: *
michael@0: * Redistribution and use in source and binary forms, with or without
michael@0: * modification, are permitted provided that the following conditions
michael@0: * are met:
michael@0: *
michael@0: * o Redistributions of source code must retain the above copyright
michael@0: * notice, this list of conditions and the following disclaimer.
michael@0: *
michael@0: * o Redistributions in binary form must reproduce the above copyright
michael@0: * notice, this list of conditions and the following disclaimer in the
michael@0: * documentation and/or other materials provided with the distribution.
michael@0: *
michael@0: * o Neither the name of Ben Fortuna nor the names of any other contributors
michael@0: * may be used to endorse or promote products derived from this software
michael@0: * without specific prior written permission.
michael@0: *
michael@0: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
michael@0: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
michael@0: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
michael@0: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
michael@0: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
michael@0: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
michael@0: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
michael@0: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
michael@0: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
michael@0: * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
michael@0: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
michael@0: */
michael@0: package net.fortuna.ical4j.model.component;
michael@0:
michael@0: import java.io.IOException;
michael@0: import java.net.URISyntaxException;
michael@0: import java.text.ParseException;
michael@0: import java.util.Iterator;
michael@0:
michael@0: import net.fortuna.ical4j.model.Component;
michael@0: import net.fortuna.ical4j.model.ComponentList;
michael@0: import net.fortuna.ical4j.model.Date;
michael@0: import net.fortuna.ical4j.model.Property;
michael@0: import net.fortuna.ical4j.model.PropertyList;
michael@0: import net.fortuna.ical4j.model.ValidationException;
michael@0: import net.fortuna.ical4j.model.Validator;
michael@0: import net.fortuna.ical4j.model.property.LastModified;
michael@0: import net.fortuna.ical4j.model.property.Method;
michael@0: import net.fortuna.ical4j.model.property.TzId;
michael@0: import net.fortuna.ical4j.model.property.TzUrl;
michael@0: import net.fortuna.ical4j.util.PropertyValidator;
michael@0: import net.fortuna.ical4j.util.Strings;
michael@0:
michael@4: import org.apache.commons.lang3.ObjectUtils;
michael@4: import org.apache.commons.lang3.builder.HashCodeBuilder;
michael@0:
michael@0: /**
michael@0: * $Id$ [Apr 5, 2004]
michael@0: *
michael@0: * Defines an iCalendar VTIMEZONE component.
michael@0: *
michael@0: *
michael@0: * 4.6.5 Time Zone Component
michael@0: *
michael@0: * Component Name: VTIMEZONE
michael@0: *
michael@0: * Purpose: Provide a grouping of component properties that defines a
michael@0: * time zone.
michael@0: *
michael@0: * Formal Definition: A "VTIMEZONE" calendar component is defined by the
michael@0: * following notation:
michael@0: *
michael@0: * timezonec = "BEGIN" ":" "VTIMEZONE" CRLF
michael@0: *
michael@0: * 2*(
michael@0: *
michael@0: * ; 'tzid' is required, but MUST NOT occur more
michael@0: * ; than once
michael@0: *
michael@0: * tzid /
michael@0: *
michael@0: * ; 'last-mod' and 'tzurl' are optional,
michael@0: * but MUST NOT occur more than once
michael@0: *
michael@0: * last-mod / tzurl /
michael@0: *
michael@0: * ; one of 'standardc' or 'daylightc' MUST occur
michael@0: * ..; and each MAY occur more than once.
michael@0: *
michael@0: * standardc / daylightc /
michael@0: *
michael@0: * ; the following is optional,
michael@0: * ; and MAY occur more than once
michael@0: *
michael@0: * x-prop
michael@0: *
michael@0: * )
michael@0: *
michael@0: * "END" ":" "VTIMEZONE" CRLF
michael@0: *
michael@0: * standardc = "BEGIN" ":" "STANDARD" CRLF
michael@0: *
michael@0: * tzprop
michael@0: *
michael@0: * "END" ":" "STANDARD" CRLF
michael@0: *
michael@0: * daylightc = "BEGIN" ":" "DAYLIGHT" CRLF
michael@0: *
michael@0: * tzprop
michael@0: *
michael@0: * "END" ":" "DAYLIGHT" CRLF
michael@0: *
michael@0: * tzprop = 3*(
michael@0: *
michael@0: * ; the following are each REQUIRED,
michael@0: * ; but MUST NOT occur more than once
michael@0: *
michael@0: * dtstart / tzoffsetto / tzoffsetfrom /
michael@0: *
michael@0: * ; the following are optional,
michael@0: * ; and MAY occur more than once
michael@0: *
michael@0: * comment / rdate / rrule / tzname / x-prop
michael@0: *
michael@0: * )
michael@0: *
michael@0: *
michael@0: * @author Ben Fortuna
michael@0: */
michael@0: public class VTimeZone extends CalendarComponent {
michael@0:
michael@0: private static final long serialVersionUID = 5629679741050917815L;
michael@0:
michael@0: private final Validator itipValidator = new ITIPValidator();
michael@0:
michael@0: private ComponentList observances;
michael@0:
michael@0: /**
michael@0: * Default constructor.
michael@0: */
michael@0: public VTimeZone() {
michael@0: super(VTIMEZONE);
michael@0: this.observances = new ComponentList();
michael@0: }
michael@0:
michael@0: /**
michael@0: * Constructs a new instance containing the specified properties.
michael@0: * @param properties a list of properties
michael@0: */
michael@0: public VTimeZone(final PropertyList properties) {
michael@0: super(VTIMEZONE, properties);
michael@0: this.observances = new ComponentList();
michael@0: }
michael@0:
michael@0: /**
michael@0: * Constructs a new vtimezone component with no properties and the specified list of type components.
michael@0: * @param observances a list of type components
michael@0: */
michael@0: public VTimeZone(final ComponentList observances) {
michael@0: super(VTIMEZONE);
michael@0: this.observances = observances;
michael@0: }
michael@0:
michael@0: /**
michael@0: * Constructor.
michael@0: * @param properties a list of properties
michael@0: * @param observances a list of timezone types
michael@0: */
michael@0: public VTimeZone(final PropertyList properties,
michael@0: final ComponentList observances) {
michael@0: super(VTIMEZONE, properties);
michael@0: this.observances = observances;
michael@0: }
michael@0:
michael@0: /**
michael@0: * {@inheritDoc}
michael@0: */
michael@0: public final String toString() {
michael@0: final StringBuffer b = new StringBuffer();
michael@0: b.append(BEGIN);
michael@0: b.append(':');
michael@0: b.append(getName());
michael@0: b.append(Strings.LINE_SEPARATOR);
michael@0: b.append(getProperties());
michael@0: b.append(observances);
michael@0: b.append(END);
michael@0: b.append(':');
michael@0: b.append(getName());
michael@0: b.append(Strings.LINE_SEPARATOR);
michael@0: return b.toString();
michael@0: }
michael@0:
michael@0: /**
michael@0: * {@inheritDoc}
michael@0: */
michael@0: public final void validate(final boolean recurse)
michael@0: throws ValidationException {
michael@0:
michael@0: /*
michael@0: * ; 'tzid' is required, but MUST NOT occur more ; than once tzid /
michael@0: */
michael@0: PropertyValidator.getInstance().assertOne(Property.TZID,
michael@0: getProperties());
michael@0:
michael@0: /*
michael@0: * ; 'last-mod' and 'tzurl' are optional, but MUST NOT occur more than once last-mod / tzurl /
michael@0: */
michael@0: PropertyValidator.getInstance().assertOneOrLess(Property.LAST_MODIFIED,
michael@0: getProperties());
michael@0: PropertyValidator.getInstance().assertOneOrLess(Property.TZURL,
michael@0: getProperties());
michael@0:
michael@0: /*
michael@0: * ; one of 'standardc' or 'daylightc' MUST occur ..; and each MAY occur more than once. standardc / daylightc /
michael@0: */
michael@0: if (getObservances().getComponent(Observance.STANDARD) == null
michael@0: && getObservances().getComponent(Observance.DAYLIGHT) == null) {
michael@0: throw new ValidationException("Sub-components ["
michael@0: + Observance.STANDARD + "," + Observance.DAYLIGHT
michael@0: + "] must be specified at least once");
michael@0: }
michael@0:
michael@0: for (final Iterator i = getObservances().iterator(); i.hasNext();) {
michael@0: ((Component) i.next()).validate(recurse);
michael@0: }
michael@0:
michael@0: /*
michael@0: * ; the following is optional, ; and MAY occur more than once x-prop
michael@0: */
michael@0:
michael@0: if (recurse) {
michael@0: validateProperties();
michael@0: }
michael@0: }
michael@0:
michael@0: /**
michael@0: * {@inheritDoc}
michael@0: */
michael@0: protected Validator getValidator(Method method) {
michael@0: return itipValidator;
michael@0: }
michael@0:
michael@0: /**
michael@0: * Common validation for all iTIP methods.
michael@0: *
michael@0: *
michael@0: * Component/Property Presence
michael@0: * ------------------- ----------------------------------------------
michael@0: * VTIMEZONE 0+ MUST be present if any date/time refers
michael@0: * to timezone
michael@0: * DAYLIGHT 0+ MUST be one or more of either STANDARD or
michael@0: * DAYLIGHT
michael@0: * COMMENT 0 or 1
michael@0: * DTSTART 1 MUST be local time format
michael@0: * RDATE 0+ if present RRULE MUST NOT be present
michael@0: * RRULE 0+ if present RDATE MUST NOT be present
michael@0: * TZNAME 0 or 1
michael@0: * TZOFFSET 1
michael@0: * TZOFFSETFROM 1
michael@0: * TZOFFSETTO 1
michael@0: * X-PROPERTY 0+
michael@0: * LAST-MODIFIED 0 or 1
michael@0: * STANDARD 0+ MUST be one or more of either STANDARD or
michael@0: * DAYLIGHT
michael@0: * COMMENT 0 or 1
michael@0: * DTSTART 1 MUST be local time format
michael@0: * RDATE 0+ if present RRULE MUST NOT be present
michael@0: * RRULE 0+ if present RDATE MUST NOT be present
michael@0: * TZNAME 0 or 1
michael@0: * TZOFFSETFROM 1
michael@0: * TZOFFSETTO 1
michael@0: * X-PROPERTY 0+
michael@0: * TZID 1
michael@0: * TZURL 0 or 1
michael@0: * X-PROPERTY 0+
michael@0: *
michael@0: */
michael@0: private class ITIPValidator implements Validator {
michael@0:
michael@0: private static final long serialVersionUID = 1L;
michael@0:
michael@0: /**
michael@0: * {@inheritDoc}
michael@0: */
michael@0: public void validate() throws ValidationException {
michael@0: for (final Iterator i = getObservances().iterator(); i.hasNext();) {
michael@0: final Observance observance = (Observance) i.next();
michael@0: PropertyValidator.getInstance().assertOne(Property.DTSTART, observance.getProperties());
michael@0: PropertyValidator.getInstance().assertOne(Property.TZOFFSETFROM, observance.getProperties());
michael@0: PropertyValidator.getInstance().assertOne(Property.TZOFFSETTO, observance.getProperties());
michael@0:
michael@0: PropertyValidator.getInstance().assertOneOrLess(Property.TZNAME, observance.getProperties());
michael@0: }
michael@0: }
michael@0: }
michael@0:
michael@0: /**
michael@0: * @return Returns the types.
michael@0: */
michael@0: public final ComponentList getObservances() {
michael@0: return observances;
michael@0: }
michael@0:
michael@0: /**
michael@0: * Returns the latest applicable timezone observance for the specified date.
michael@0: * @param date the latest possible date for a timezone observance onset
michael@0: * @return the latest applicable timezone observance for the specified date or null if there are no applicable
michael@0: * observances
michael@0: */
michael@0: public final Observance getApplicableObservance(final Date date) {
michael@0: Observance latestObservance = null;
michael@0: Date latestOnset = null;
michael@0: for (final Iterator i = getObservances().iterator(); i.hasNext();) {
michael@0: final Observance observance = (Observance) i.next();
michael@0: final Date onset = observance.getLatestOnset(date);
michael@0: if (latestOnset == null
michael@0: || (onset != null && onset.after(latestOnset))) {
michael@0: latestOnset = onset;
michael@0: latestObservance = observance;
michael@0: }
michael@0: }
michael@0: return latestObservance;
michael@0: }
michael@0:
michael@0: /**
michael@0: * @return the mandatory timezone identifier property
michael@0: */
michael@0: public final TzId getTimeZoneId() {
michael@0: return (TzId) getProperty(Property.TZID);
michael@0: }
michael@0:
michael@0: /**
michael@0: * @return the optional last-modified property
michael@0: */
michael@0: public final LastModified getLastModified() {
michael@0: return (LastModified) getProperty(Property.LAST_MODIFIED);
michael@0: }
michael@0:
michael@0: /**
michael@0: * @return the optional timezone url property
michael@0: */
michael@0: public final TzUrl getTimeZoneUrl() {
michael@0: return (TzUrl) getProperty(Property.TZURL);
michael@0: }
michael@0:
michael@0: /**
michael@0: * {@inheritDoc}
michael@0: */
michael@0: public boolean equals(final Object arg0) {
michael@0: if (arg0 instanceof VTimeZone) {
michael@0: return super.equals(arg0)
michael@0: && ObjectUtils.equals(observances, ((VTimeZone) arg0)
michael@0: .getObservances());
michael@0: }
michael@0: return super.equals(arg0);
michael@0: }
michael@0:
michael@0: /**
michael@0: * {@inheritDoc}
michael@0: */
michael@0: public int hashCode() {
michael@0: return new HashCodeBuilder().append(getName()).append(getProperties())
michael@0: .append(getObservances()).toHashCode();
michael@0: }
michael@0:
michael@0: /**
michael@0: * Overrides default copy method to add support for copying observance sub-components.
michael@0: * @return a copy of the instance
michael@0: * @throws ParseException where an error occurs parsing data
michael@0: * @throws IOException where an error occurs reading data
michael@0: * @throws URISyntaxException where an invalid URI is encountered
michael@0: * @see net.fortuna.ical4j.model.Component#copy()
michael@0: */
michael@0: public Component copy() throws ParseException, IOException, URISyntaxException {
michael@0: final VTimeZone copy = (VTimeZone) super.copy();
michael@0: copy.observances = new ComponentList(observances);
michael@0: return copy;
michael@0: }
michael@0: }