org.dmfs.rfc5545.recur

Class RecurrenceRule

java.lang.Object

org.dmfs.rfc5545.recur.RecurrenceRule

public final class RecurrenceRule
extends java.lang.Object

Builder and parser for recurrence rule strings that comply with RFC 2445 or RFC 5545.

The goal of this implementation is to satisfy the following qualities:

• correctness: The instances returned by the iterator shall be correct for all common cases, i.e. they follow all rules defined in RFC 5545/RFC 2445.
• completeness: The iterator shall support all valid combinations defined by RFC 5545 and RFC 2445 and return reasonable results for edge cases that are not explicitly mentioned.
• performance: The iterator shall be as efficient (in speed and memory utilization) as possible.

TODO: Add validator and a validator log.

TODO: Add proper implementation of the Object.equals(Object) method.

TODO: Add support for jCal rules.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RecurrenceRule.Part Enumeration of valid recurrence rule parts.
static class	RecurrenceRule.RfcMode Enumeration of supported rule versions.
static class	RecurrenceRule.Skip Values of the new SKIP parameter as added in tools.ietf.org/html/draft-daboo-icalendar-rscale-03
static class	RecurrenceRule.WeekdayNum This class represents the position of a Weekday in a specific range.

Field Summary

Fields

Modifier and Type	Field and Description
RecurrenceRule.RfcMode	mode The parser mode.

Constructor Summary

Constructors

Constructor and Description
RecurrenceRule(Freq freq) Create a new recurrence rule with the given base frequency.
RecurrenceRule(Freq freq, RecurrenceRule.RfcMode mode) Create a new recurrence rule with the given base frequency using a custom RecurrenceRule.RfcMode.
RecurrenceRule(java.lang.String recur) Create a new recurrence rule from String using the RecurrenceRule.RfcMode RecurrenceRule.RfcMode.RFC5545_LAX.
RecurrenceRule(java.lang.String recur, RecurrenceRule.RfcMode mode) Create a new recurrence rule from String using a custom RecurrenceRule.RfcMode.

Method Summary

Modifier and Type	Method and Description
java.util.List<RecurrenceRule.WeekdayNum>	getByDayPart() Return the value of the BYDAY part of the rule if there is any.
java.util.List<java.lang.Integer>	getByPart(RecurrenceRule.Part part) Returns a specific by-rule.
java.lang.Integer	getCount() Get the number if instances in the recurrence set.
Freq	getFreq() Return the base frequency of this recurrence rule.
int	getInterval() Get the INTERVAL of this rule.
RecurrenceRule.Skip	getSkip() Return value of the skip part of this rule.
org.dmfs.rfc5545.DateTime	getUntil() Get the last date an instance my have.
org.dmfs.rfc5545.Weekday	getWeekStart() Get the start of the week as defined in the rule.
java.lang.String	getXPart(java.lang.String xname) Returns a specific x-part.
boolean	hasPart(RecurrenceRule.Part part) Checks if a specific part is present in this rule.
boolean	hasXPart(java.lang.String xname) Returns whether a specific x-part is present in the rule.
boolean	isInfinite() Returns whether this recurrence rule recurs forever.
RecurrenceRuleIterator	iterator(org.dmfs.rfc5545.DateTime start) Get a new RuleIterator that iterates all instances of this rule.
RecurrenceRuleIterator	iterator(long start, java.util.TimeZone timezone) Get a new RuleIterator that iterates all instances of this rule.
void	setByDayPart(java.util.List<RecurrenceRule.WeekdayNum> value) Set the BYDAY part of this rule.
void	setByPart(RecurrenceRule.Part part, java.lang.Integer... values) Set a specific by-rule.
void	setByPart(RecurrenceRule.Part part, java.util.List<java.lang.Integer> value) Set a specific by-rule.
void	setCount(int count) Set the number of instances in the recurrence set.
void	setFreq(Freq freq, boolean silent) Set the base frequency of this recurrence rule.
void	setInterval(int interval) Set the INTERVAL of this rule.
void	setSkip(RecurrenceRule.Skip skip) Set the skip part of this recurrence rule.
void	setUntil(org.dmfs.rfc5545.DateTime until) Set the latest possible date of an instance.
void	setWeekStart(org.dmfs.rfc5545.Weekday wkst) Set the start of the week.
void	setWeekStart(org.dmfs.rfc5545.Weekday wkst, boolean keepWkStMo) Set the start of the week.
void	setXPart(java.lang.String xname, java.lang.String value) Sets an x-part. x-parts are supported by RFC 2445 only.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

mode

public final RecurrenceRule.RfcMode mode

The parser mode. This can not be changed once the rule has been created.

Constructor Detail

RecurrenceRule

public RecurrenceRule(java.lang.String recur)
               throws InvalidRecurrenceRuleException

Create a new recurrence rule from String using the RecurrenceRule.RfcMode RecurrenceRule.RfcMode.RFC5545_LAX. The parser will be quite tolerant and skip any invalid parts to produce a valid recurrence rule.

Parameters:

recur - A recurrence rule string as defined in RFC 5545.

Throws:

InvalidRecurrenceRuleException - If an unrecoverable error occurs when parsing the rule (like FREQ is missing, or mutually exclusive parts have been found).

RecurrenceRule

public RecurrenceRule(java.lang.String recur,
                      RecurrenceRule.RfcMode mode)
               throws InvalidRecurrenceRuleException

Create a new recurrence rule from String using a custom RecurrenceRule.RfcMode.

Parameters:

recur - A recurrence rule string as defined in RFC 5545.

mode - A RecurrenceRule.RfcMode to change the parsing behaviour in case of errors.

Throws:

InvalidRecurrenceRuleException - If the rule is invalid with respect to the chosen mode or if an unrecoverable error occurs when parsing the rule (like FREQ is missing, or mutually exclusive parts have been found).

RecurrenceRule

public RecurrenceRule(Freq freq)

Create a new recurrence rule with the given base frequency. This constructor will use RecurrenceRule.RfcMode.RFC5545_STRICT, so created rules will have to comply with RFC 5545, otherwise an exception is thrown.

Parameters:

freq - The Freq values that specified the base frequency for this rule.

RecurrenceRule

public RecurrenceRule(Freq freq,
                      RecurrenceRule.RfcMode mode)

Create a new recurrence rule with the given base frequency using a custom RecurrenceRule.RfcMode.

Parameters:

freq - The Freq values that specified the base frequency for this rule.

mode - A RecurrenceRule.RfcMode to change the behavior in case of errors.

Method Detail

getFreq

public Freq getFreq()

Return the base frequency of this recurrence rule.

Returns:

The Freq value of this rule.

setFreq

public void setFreq(Freq freq,
                    boolean silent)

Set the base frequency of this recurrence rule.

TODO: check if the rule is still valid afterwards (honor the silent parameter)

Parameters:

freq - The new Freq value of this rule.

silent - true to drop RecurrenceRule.Parts that are no longer valid with the new frequency silently, false to throw an exception in that case.

getSkip

public RecurrenceRule.Skip getSkip()

Return value of the skip part of this rule.

Returns:

The RecurrenceRule.Skip value of this rule.

setSkip

public void setSkip(RecurrenceRule.Skip skip)

Set the skip part of this recurrence rule. Consider to set a RecurrenceRule.Part.RSCALE value when setting a SKIP rule, otherwise it will default to GREGORIAN calendar.

Parameters:

skip - The new RecurrenceRule.Skip value of this rule, null and RecurrenceRule.Skip.OMIT will remove the SKIP part, the later one is the default anyway.

getInterval

public int getInterval()

Get the INTERVAL of this rule.

Returns:

The INTERVAL of this rule or 1 if no INTERVAL has been specified.

setInterval

public void setInterval(int interval)

Set the INTERVAL of this rule. The interval must be a positive integer. A value of 1 will just remove the INTERVAL part since that's the default value anyway.

Parameters:

interval - The new interval of this rule.

Throws:

java.lang.IllegalArgumentException - if interval is not a positive integer value.

getUntil

public org.dmfs.rfc5545.DateTime getUntil()

Get the last date an instance my have. If the rule has an UNTIL part the result is a DateTime set to the correct time. The time zone is either UTC or floating.

Returns:

A DateTime set to the UNTIL value if an UNTIL part is present, null otherwise.

setUntil

public void setUntil(org.dmfs.rfc5545.DateTime until)

Set the latest possible date of an instance. This will remove any COUNT rule if present. If the time zone of until is not UTC and until is not floating it's automatically converted to UTC.

Parameters:

until - The UNTIL part of this rule or null to let the instances recur forever.

getCount

public java.lang.Integer getCount()

Get the number if instances in the recurrence set. If this rule has no COUNT limit this will return null

Returns:

The number of instances or null.

setCount

public void setCount(int count)

Set the number of instances in the recurrence set. This will remove any UNTIL rule if present.

Parameters:

count - The number if instances.

isInfinite

public boolean isInfinite()

Returns whether this recurrence rule recurs forever.

Returns:

true if this rule contains neither an RecurrenceRule.Part.UNTIL nor a RecurrenceRule.Part.COUNT part, false otherwise.

hasPart

public boolean hasPart(RecurrenceRule.Part part)

Checks if a specific part is present in this rule.

Parameters:

part - The part if interest.

Returns:

true if this rule has this part, false otherwise

getByPart

public java.util.List<java.lang.Integer> getByPart(RecurrenceRule.Part part)

Returns a specific by-rule. part may be one of RecurrenceRule.Part.BYSECOND, RecurrenceRule.Part.BYMINUTE, RecurrenceRule.Part.BYHOUR, RecurrenceRule.Part.BYMONTHDAY, RecurrenceRule.Part.BYYEARDAY, RecurrenceRule.Part.BYWEEKNO, RecurrenceRule.Part.BYMONTH, or RecurrenceRule.Part.BYSETPOS.

To get RecurrenceRule.Part.BYDAY use getByDayPart().

Parameters:

part - The by-rule to return.

Returns:

A list of integer values.

setByPart

public void setByPart(RecurrenceRule.Part part,
                      java.util.List<java.lang.Integer> value)
               throws InvalidRecurrenceRuleException

Set a specific by-rule. part may be one of RecurrenceRule.Part.BYSECOND, RecurrenceRule.Part.BYMINUTE, RecurrenceRule.Part.BYHOUR, RecurrenceRule.Part.BYMONTHDAY, RecurrenceRule.Part.BYYEARDAY, RecurrenceRule.Part.BYWEEKNO, RecurrenceRule.Part.BYMONTH, or RecurrenceRule.Part.BYSETPOS.

To set RecurrenceRule.Part.BYDAY use setByDayPart(List).

Parameters:

part - The by-rule to set.

value - A list of integers that specify the rule or null (or an empty list) to remove the part.

Throws:

InvalidRecurrenceRuleException - if the list would become invalid by adding this part (this respects the current RecurrenceRule.RfcMode.

setByPart

public void setByPart(RecurrenceRule.Part part,
                      java.lang.Integer... values)
               throws InvalidRecurrenceRuleException

Set a specific by-rule. part may be one of RecurrenceRule.Part.BYSECOND, RecurrenceRule.Part.BYMINUTE, RecurrenceRule.Part.BYHOUR, RecurrenceRule.Part.BYMONTHDAY, RecurrenceRule.Part.BYYEARDAY, RecurrenceRule.Part.BYWEEKNO, RecurrenceRule.Part.BYMONTH, or RecurrenceRule.Part.BYSETPOS.

To set RecurrenceRule.Part.BYDAY use setByDayPart(List).

Parameters:

part - The by-rule to set.

values - Integers that specify the rule or null (or an empty list) to remove the part.

Throws:

InvalidRecurrenceRuleException - if the list would become invalid by adding this part (this respects the current RecurrenceRule.RfcMode.

setByDayPart

public void setByDayPart(java.util.List<RecurrenceRule.WeekdayNum> value)

Set the BYDAY part of this rule.

Parameters:

value - A List of RecurrenceRule.WeekdayNums or null or an empty List to remove the part

getByDayPart

public java.util.List<RecurrenceRule.WeekdayNum> getByDayPart()

Return the value of the BYDAY part of the rule if there is any.

Returns:

A List of RecurrenceRule.WeekdayNums if the part is present or null if there is no such part.

getWeekStart

public org.dmfs.rfc5545.Weekday getWeekStart()

Get the start of the week as defined in the rule. If no WKST part is set this method will return the default value, which is Weekday.MO.

Returns:

A Weekday.

setWeekStart

public void setWeekStart(org.dmfs.rfc5545.Weekday wkst)

Set the start of the week. If the start is set to Weekday.MO the WKST part is effectively removed, since that's the default value. This value is important for rules having a BYWEEKNO or BYDAY part.

Parameters:

wkst - The start of the week to use when calculating the instances.

setWeekStart

public void setWeekStart(org.dmfs.rfc5545.Weekday wkst,
                         boolean keepWkStMo)

Set the start of the week. If the start is set to Weekday.MO the WKST part is effectively removed (unless keepWkStMo == true), since that's the default value. This value is important for rules having a BYWEEKNO or BYDAY part.

Parameters:

wkst - The start of the week to use when calculating the instances.

keepWkStMo - set to true to keep the WKST field if the value is Weekday.MO. Since Monday is the default adding it is not necessary, but some implementations might be broken and use a different weekstart if it's not explicitly specified.

setXPart

public void setXPart(java.lang.String xname,
                     java.lang.String value)

Sets an x-part. x-parts are supported by RFC 2445 only. If mode is set to RecurrenceRule.RfcMode.RFC5545_LAX a call to this method will do nothing. If mode is set to RecurrenceRule.RfcMode.RFC5545_STRICT this method will throw an UnsupportedOperationException.

Note that calling this method in RFC 2445 mode will override any existing x-part of the same name.

Parameters:

xname - The name of the x-part. Must be a valid identifier.

value - The value of the x-part. Must be a valid name.

Throws:

java.lang.UnsupportedOperationException - if mode is set to RecurrenceRule.RfcMode.RFC5545_STRICT.

hasXPart

public boolean hasXPart(java.lang.String xname)

Returns whether a specific x-part is present in the rule. Since RFC 5545 doesn't support x-parts this method will always return false if mode equals RecurrenceRule.RfcMode.RFC5545_LAX or RecurrenceRule.RfcMode.RFC5545_STRICT.

Parameters:

xname - The name of the x-part to check for.

Returns:

true if the part is present, false otherwise.

getXPart

public java.lang.String getXPart(java.lang.String xname)

Returns a specific x-part. Since RFC 5545 doesn't support x-parts this method will always return null if mode equals RecurrenceRule.RfcMode.RFC5545_LAX or RecurrenceRule.RfcMode.RFC5545_STRICT.

Parameters:

xname - The name of the x-part to return.

Returns:

The value of the x-part or null.

iterator

public RecurrenceRuleIterator iterator(long start,
                                       java.util.TimeZone timezone)

Get a new RuleIterator that iterates all instances of this rule.

Note: If the rule contains an UNTIL part with a floating value, you have to provide null as the timezone.

Parameters:

start - The time of the first instance in milliseconds since the epoch.

timezone - The TimeZone of the first instance or null for floating times.

Returns:

A RecurrenceRuleIterator.

iterator

public RecurrenceRuleIterator iterator(org.dmfs.rfc5545.DateTime start)

Get a new RuleIterator that iterates all instances of this rule.

Note: if an UNTIL part is present and it's value is a floating time then start must be floating as well and vice versa. The same applies if the UNTIL value is an all-day value

Parameters:

start - The first instance.

Returns:

A RuleIterator.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object