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;
michael@0: 
michael@0: import java.io.IOException;
michael@0: import java.io.Serializable;
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.parameter.Value;
michael@0: import net.fortuna.ical4j.model.property.DateProperty;
michael@0: import net.fortuna.ical4j.model.property.DtStart;
michael@0: import net.fortuna.ical4j.model.property.Duration;
michael@0: import net.fortuna.ical4j.model.property.ExDate;
michael@0: import net.fortuna.ical4j.model.property.ExRule;
michael@0: import net.fortuna.ical4j.model.property.RDate;
michael@0: import net.fortuna.ical4j.model.property.RRule;
michael@0: import net.fortuna.ical4j.util.Strings;
michael@0: 
michael@4: import org.apache.commons.lang3.builder.EqualsBuilder;
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 component. Subclasses of this class provide additional validation and typed values for specific
michael@0:  * iCalendar components.
michael@0:  * @author Ben Fortuna
michael@0:  */
michael@0: public abstract class Component implements Serializable {
michael@0: 
michael@0:     private static final long serialVersionUID = 4943193483665822201L;
michael@0: 
michael@0:     /**
michael@0:      * Component start token.
michael@0:      */
michael@0:     public static final String BEGIN = "BEGIN";
michael@0: 
michael@0:     /**
michael@0:      * Component end token.
michael@0:      */
michael@0:     public static final String END = "END";
michael@0: 
michael@0:     /**
michael@0:      * Component token.
michael@0:      */
michael@0:     public static final String VEVENT = "VEVENT";
michael@0: 
michael@0:     /**
michael@0:      * Component token.
michael@0:      */
michael@0:     public static final String VTODO = "VTODO";
michael@0: 
michael@0:     /**
michael@0:      * Component token.
michael@0:      */
michael@0:     public static final String VJOURNAL = "VJOURNAL";
michael@0: 
michael@0:     /**
michael@0:      * Component token.
michael@0:      */
michael@0:     public static final String VFREEBUSY = "VFREEBUSY";
michael@0: 
michael@0:     /**
michael@0:      * Component token.
michael@0:      */
michael@0:     public static final String VTIMEZONE = "VTIMEZONE";
michael@0: 
michael@0:     /**
michael@0:      * Component token.
michael@0:      */
michael@0:     public static final String VALARM = "VALARM";
michael@0: 
michael@0:     /**
michael@0:      * Component token.
michael@0:      */
michael@0:     public static final String VAVAILABILITY = "VAVAILABILITY";
michael@0: 
michael@0:     /**
michael@0:      * Component token.
michael@0:      */
michael@0:     public static final String VVENUE = "VVENUE";
michael@0: 
michael@0:     /**
michael@0:      * Component token.
michael@0:      */
michael@0:     public static final String AVAILABLE = "AVAILABLE";
michael@0: 
michael@0:     /**
michael@0:      * Prefix for non-standard components.
michael@0:      */
michael@0:     public static final String EXPERIMENTAL_PREFIX = "X-";
michael@0: 
michael@0:     private String name;
michael@0: 
michael@0:     private PropertyList properties;
michael@0: 
michael@0:     /**
michael@0:      * Constructs a new component containing no properties.
michael@0:      * @param s a component name
michael@0:      */
michael@0:     protected Component(final String s) {
michael@0:         this(s, new PropertyList());
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Constructor made protected to enforce the use of <code>ComponentFactory</code> for component instantiation.
michael@0:      * @param s component name
michael@0:      * @param p a list of properties
michael@0:      */
michael@0:     protected Component(final String s, final PropertyList p) {
michael@0:         this.name = s;
michael@0:         this.properties = p;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * {@inheritDoc}
michael@0:      */
michael@0:     public String toString() {
michael@0:         final StringBuffer buffer = new StringBuffer();
michael@0:         buffer.append(BEGIN);
michael@0:         buffer.append(':');
michael@0:         buffer.append(getName());
michael@0:         buffer.append(Strings.LINE_SEPARATOR);
michael@0:         buffer.append(getProperties());
michael@0:         buffer.append(END);
michael@0:         buffer.append(':');
michael@0:         buffer.append(getName());
michael@0:         buffer.append(Strings.LINE_SEPARATOR);
michael@0: 
michael@0:         return buffer.toString();
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * @return Returns the name.
michael@0:      */
michael@0:     public final String getName() {
michael@0:         return name;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * @return Returns the properties.
michael@0:      */
michael@0:     public final PropertyList getProperties() {
michael@0:         return properties;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Convenience method for retrieving a list of named properties.
michael@0:      * @param name name of properties to retrieve
michael@0:      * @return a property list containing only properties with the specified name
michael@0:      */
michael@0:     public final PropertyList getProperties(final String name) {
michael@0:         return getProperties().getProperties(name);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Convenience method for retrieving a named property.
michael@0:      * @param name name of the property to retrieve
michael@0:      * @return the first matching property in the property list with the specified name
michael@0:      */
michael@0:     public final Property getProperty(final String name) {
michael@0:         return getProperties().getProperty(name);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Perform validation on a component and its properties.
michael@0:      * @throws ValidationException where the component is not in a valid state
michael@0:      */
michael@0:     public final void validate() throws ValidationException {
michael@0:         validate(true);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Perform validation on a component.
michael@0:      * @param recurse indicates whether to validate the component's properties
michael@0:      * @throws ValidationException where the component is not in a valid state
michael@0:      */
michael@0:     public abstract void validate(final boolean recurse)
michael@0:             throws ValidationException;
michael@0: 
michael@0:     /**
michael@0:      * Invoke validation on the component properties in its current state.
michael@0:      * @throws ValidationException where any of the component properties is not in a valid state
michael@0:      */
michael@0:     protected final void validateProperties() throws ValidationException {
michael@0:         for (final Iterator i = getProperties().iterator(); i.hasNext();) {
michael@0:             final Property property = (Property) i.next();
michael@0:             property.validate();
michael@0:         }
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * {@inheritDoc}
michael@0:      */
michael@0:     public boolean equals(final Object arg0) {
michael@0:         if (arg0 instanceof Component) {
michael@0:             final Component c = (Component) arg0;
michael@0:             return new EqualsBuilder().append(getName(), c.getName())
michael@0:                 .append(getProperties(), c.getProperties()).isEquals();
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:                 .toHashCode();
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Create a (deep) copy of this component.
michael@0:      * @return the component copy
michael@0:      * @throws IOException where an error occurs reading the component data
michael@0:      * @throws ParseException where parsing component data fails
michael@0:      * @throws URISyntaxException where component data contains an invalid URI
michael@0:      */
michael@0:     public Component copy() throws ParseException, IOException,
michael@0:             URISyntaxException {
michael@0: 
michael@0:         // Deep copy properties..
michael@0:         final PropertyList newprops = new PropertyList(getProperties());
michael@0: 
michael@0:         return ComponentFactory.getInstance().createComponent(getName(),
michael@0:                 newprops);
michael@0:     }
michael@0:     
michael@0:     /**
michael@0:      * Calculates the recurrence set for this component using the specified period.
michael@0:      * The recurrence set is derived from a combination of the component start date,
michael@0:      * recurrence rules and dates, and exception rules and dates. Note that component
michael@0:      * transparency and anniversary-style dates do not affect the resulting
michael@0:      * intersection.
michael@0:      * <p>If an explicit DURATION is not specified, the effective duration of each
michael@0:      *  returned period is derived from the DTSTART and DTEND or DUE properties.
michael@0:      * If the component has no DURATION, DTEND or DUE, the effective duration is set
michael@0:      *  to PT0S</p>
michael@0:      * @param period a range to calculate recurrences for
michael@0:      * @return a list of periods
michael@0:      */
michael@0:     public final PeriodList calculateRecurrenceSet(final Period period) {
michael@0:         
michael@0: //        validate();
michael@0:         
michael@0:         final PeriodList recurrenceSet = new PeriodList();
michael@0: 
michael@0:         final DtStart start = (DtStart) getProperty(Property.DTSTART);
michael@0:         DateProperty end = (DateProperty) getProperty(Property.DTEND);
michael@0:         if (end == null) {
michael@0:             end = (DateProperty) getProperty(Property.DUE);
michael@0:         }
michael@0:         Duration duration = (Duration) getProperty(Property.DURATION);
michael@0:         
michael@0:         // if no start date specified return empty list..
michael@0:         if (start == null) {
michael@0:             return recurrenceSet;
michael@0:         }
michael@0: 
michael@0:         final Value startValue = (Value) start.getParameter(Parameter.VALUE);
michael@0:         
michael@0:         // initialise timezone..
michael@0: //        if (startValue == null || Value.DATE_TIME.equals(startValue)) {
michael@0:         if (start.isUtc()) {
michael@0:             recurrenceSet.setUtc(true);
michael@0:         }
michael@0:         else if (start.getDate() instanceof DateTime) {
michael@0:             recurrenceSet.setTimeZone(((DateTime) start.getDate()).getTimeZone());
michael@0:         }
michael@0:         
michael@0:         // if an explicit event duration is not specified, derive a value for recurring
michael@0:         // periods from the end date..
michael@0:         Dur rDuration;
michael@0:         // if no end or duration specified, end date equals start date..
michael@0:         if (end == null && duration == null) {
michael@0:             rDuration = new Dur(start.getDate(), start.getDate());
michael@0:         }
michael@0:         else if (duration == null) {
michael@0:             rDuration = new Dur(start.getDate(), end.getDate());
michael@0:         }
michael@0:         else {
michael@0:             rDuration = duration.getDuration();
michael@0:         }
michael@0:         
michael@0:         // add recurrence dates..
michael@0:         for (final Iterator i = getProperties(Property.RDATE).iterator(); i.hasNext();) {
michael@0:             final RDate rdate = (RDate) i.next();
michael@0:             final Value rdateValue = (Value) rdate.getParameter(Parameter.VALUE);
michael@0:             if (Value.PERIOD.equals(rdateValue)) {
michael@0:                 for (final Iterator j = rdate.getPeriods().iterator(); j.hasNext();) {
michael@0:                     final Period rdatePeriod = (Period) j.next();
michael@0:                     if (period.intersects(rdatePeriod)) {
michael@0:                         recurrenceSet.add(rdatePeriod);
michael@0:                     }
michael@0:                 }
michael@0:             }
michael@0:             else if (Value.DATE_TIME.equals(rdateValue)) {
michael@0:                 for (final Iterator j = rdate.getDates().iterator(); j.hasNext();) {
michael@0:                     final DateTime rdateTime = (DateTime) j.next();
michael@0:                     if (period.includes(rdateTime)) {
michael@0:                         recurrenceSet.add(new Period(rdateTime, rDuration));
michael@0:                     }
michael@0:                 }
michael@0:             }
michael@0:             else {
michael@0:                 for (final Iterator j = rdate.getDates().iterator(); j.hasNext();) {
michael@0:                     final Date rdateDate = (Date) j.next();
michael@0:                     if (period.includes(rdateDate)) {
michael@0:                         recurrenceSet.add(new Period(new DateTime(rdateDate), rDuration));
michael@0:                     }
michael@0:                 }
michael@0:             }
michael@0:         }
michael@0:         
michael@0:         // allow for recurrence rules that start prior to the specified period
michael@0:         // but still intersect with it..
michael@0:         final DateTime startMinusDuration = new DateTime(period.getStart());
michael@0:         startMinusDuration.setTime(rDuration.negate().getTime(
michael@0:                 period.getStart()).getTime());
michael@0:             
michael@0:         // add recurrence rules..
michael@0:         for (final Iterator i = getProperties(Property.RRULE).iterator(); i.hasNext();) {
michael@0:             final RRule rrule = (RRule) i.next();
michael@0:             final DateList rruleDates = rrule.getRecur().getDates(start.getDate(),
michael@0:                     new Period(startMinusDuration, period.getEnd()), startValue);
michael@0:             for (final Iterator j = rruleDates.iterator(); j.hasNext();) {
michael@0:                 final Date rruleDate = (Date) j.next();
michael@0:                 recurrenceSet.add(new Period(new DateTime(rruleDate), rDuration));
michael@0:             }
michael@0:         }
michael@0:     
michael@0:         // add initial instance if intersection with the specified period..
michael@0:         Period startPeriod = null;
michael@0:         if (end != null) {
michael@0:             startPeriod = new Period(new DateTime(start.getDate()),
michael@0:                     new DateTime(end.getDate()));
michael@0:         }
michael@0:         else {
michael@0:             /*
michael@0:              * PeS: Anniversary type has no DTEND nor DUR, define DUR 
michael@0:              * locally, otherwise we get NPE
michael@0:              */
michael@0:             if (duration == null) {
michael@0:                 duration = new Duration(rDuration);
michael@0:             }
michael@0: 
michael@0:             startPeriod = new Period(new DateTime(start.getDate()),
michael@0:                     duration.getDuration());
michael@0:         }
michael@0:         if (period.intersects(startPeriod)) {
michael@0:             recurrenceSet.add(startPeriod);
michael@0:         }
michael@0:         
michael@0:         // subtract exception dates..
michael@0:         for (final Iterator i = getProperties(Property.EXDATE).iterator(); i.hasNext();) {
michael@0:             final ExDate exdate = (ExDate) i.next();
michael@0:             for (final Iterator j = recurrenceSet.iterator(); j.hasNext();) {
michael@0:                 final Period recurrence = (Period) j.next();
michael@0:                 // for DATE-TIME instances check for DATE-based exclusions also..
michael@0:                 if (exdate.getDates().contains(recurrence.getStart())
michael@0:                         || exdate.getDates().contains(new Date(recurrence.getStart()))) {
michael@0:                     j.remove();
michael@0:                 }
michael@0:             }
michael@0:         }
michael@0:         
michael@0:         // subtract exception rules..
michael@0:         for (final Iterator i = getProperties(Property.EXRULE).iterator(); i.hasNext();) {
michael@0:             final ExRule exrule = (ExRule) i.next();
michael@0:             final DateList exruleDates = exrule.getRecur().getDates(start.getDate(),
michael@0:                     period, startValue);
michael@0:             for (final Iterator j = recurrenceSet.iterator(); j.hasNext();) {
michael@0:                 final Period recurrence = (Period) j.next();
michael@0:                 // for DATE-TIME instances check for DATE-based exclusions also..
michael@0:                 if (exruleDates.contains(recurrence.getStart())
michael@0:                         || exruleDates.contains(new Date(recurrence.getStart()))) {
michael@0:                     j.remove();
michael@0:                 }
michael@0:             }
michael@0:         }
michael@0: 
michael@0:         return recurrenceSet;
michael@0:     }
michael@0: }