javax.microedition.pim
Class RepeatRule

java.lang.Object
  |
  +--javax.microedition.pim.RepeatRule

public class RepeatRule

extends java.lang.Object

Represents a description for a repeating pattern for an Event item. The fields are a subset of the capabilities of the RRULE field in VEVENT defined by the vCalendar 1.0 specification from the Internet Mail Consortium (http://www.imc.org). It is use to determine how often an associated Event occurs.

The fields of a Repeat Rule can conceptually be grouped into two categories:

• Frequency of a Repeat Rule
• Fields that modify or refine the Frequency of a Repeat Rule

This means that a Repeat Rule's calculation of applicable dates start with a repeating frequency (such as weekly, daily, yearly, or monthly) and then other fields refine or modify the repeat characteristics according to the field (e.g. the COUNT field specifies that only X repeat occurrences happen at the given frequency). The first category contains only FREQUENCY, while all other repeat rule fields are classified in the second category. This classification of the fields aids in understanding of the relationship of the fields and allows for a method to query for supported fields (see EventList.getSupportedRepeatRuleFields(int) ).

A repeat rule typically needs to have its frequency set first and foremost. The following table shows the valid values for the frequency fields that can be set in RepeatRule:

Fields	Set Method	Valid Values
FREQUENCY	setInt	DAILY, WEEKLY, MONTHLY, YEARLY

The following table shows the valid values for the fields that modify or refine the frequency of a RepeatRule:

Fields	Set Method	Valid Values
COUNT	setInt	any positive int
INTERVAL	setInt	any positive int
END	setDate	any valid Date
MONTH_IN_YEAR	setInt	JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER (Note: that these are constants defined in the RepeatRule class and are not the same as those in the Calendar class)
DAY_IN_WEEK	setInt	SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY (Note: that these are constants defined in the RepeatRule class and are not the same as those in the Calendar class)
WEEK_IN_MONTH	setInt	FIRST, SECOND, THIRD, FOURTH, FIFTH, LAST, SECONDLAST, THIRDLAST, FOURTHLAST, FIFTHLAST
DAY_IN_MONTH	setInt	1-31
DAY_IN_YEAR	setInt	1-366

Examples

The following examples demonstrate some possible repeat values.

To specify the associated event occurs every day:

      setInt(RepeatRule.FREQUENCY, RepeatRule.DAILY);

To specify the associated event occurs every day for the next five days:

      setInt(RepeatRule.FREQUENCY, RepeatRule.DAILY);
      setInt(RepeatRule.COUNT, 5);

To specify this event occurs every week on Monday and Tuesday:

      setInt(RepeatRule.FREQUENCY, RepeatRule.WEEKLY);
      setInt(RepeatRule.DAY_IN_WEEK, RepeatRule.MONDAY | RepeatRule.TUESDAY);

To specify the associated event occurs every third week on Friday:

      setInt(RepeatRule.FREQUENCY, RepeatRule.WEEKLY);
      setInt(RepeatRule.INTERVAL, 3);
      setInt(RepeatRule.DAY_IN_WEEK, RepeatRule.FRIDAY);

To specify the associated event occurs every month on the Wednesday of the second week until the end of the current year:

      setInt(RepeatRule.FREQUENCY, RepeatRule.MONTHLY);
      setInt(RepeatRule.WEEK_IN_MONTH, RepeatRule.SECOND);
      setInt(RepeatRule.DAY_IN_WEEK, RepeatRule.WEDNESDAY);
      java.util.Calendar cal = Calendar.getInstance();
      cal.set(Calendar.MONTH, Calendar.DECEMBER);
      cal.set(Calendar.DAY_OF_MONTH, 31);
      cal.set(Calendar.AM_PM, Calendar.PM);
      cal.set(Calendar.HOUR_OF_DAY, 23);
      cal.set(Calendar.MINUTE, 59);
      setDate(RepeatRule.END, cal.getTime().getTime());

To specify the associated event occurs every year on the Sunday of the second week in May:

      setInt(RepeatRule.FREQUENCY, RepeatRule.YEARLY);
      setInt(RepeatRule.MONTH_IN_YEAR, RepeatRule.MAY);
      setInt(RepeatRule.WEEK_IN_MONTH, RepeatRule.SECOND);
      setInt(RepeatRule.DAY_IN_WEEK, RepeatRule.SUNDAY);

To specify the associated event occurs every year on the 4th of July:

      setInt(RepeatRule.FREQUENCY, RepeatRule.YEARLY);
      setInt(RepeatRule.MONTH_IN_YEAR, RepeatRule.JULY);
      setInt(RepeatRule.DAY_IN_MONTH, 4);

To specify the associated event occurs every year on the first day:

      
      setInt(RepeatRule.FREQUENCY, RepeatRule.YEARLY);
      setInt(RepeatRule.DAY_IN_YEAR, 1);

To check if a particular Repeat Rule frquency value is supported for events for a certain event list:

      // Check if RepeatRule.DAILY is supported in the default event list
 
      EventList el = PIM.openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
      int[] supported_fields = el.getSupportedRepeatRuleFields(RepeatRule.DAILY);
      if (supported_fields.length > 0) {
          System.out.println("RepeatRule.DAILY is supported in default event list");
      }
			

To check if a particular Repeat Rule field is supported for events for a certain event list:

      // Check if RepeatRule.INTERVAL is supported for DAILY frequency events
 
      EventList el = PIM.openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
      int[] supported_fields = el.getSupportedRepeatRuleFields(RepeatRule.DAILY);
      int i = 0;
      while (i < supported_fields.length)
      if (supported_fields[i] & RepeatRule.INTERVAL != 0) {
          System.out.println("INTERVAL supported in default event list");
          break;
      }
			

Since:

PIM 1.0

Field Summary

static int	APRIL Constant for the month of April used with MONTH_IN_YEAR field.
static int	AUGUST Constant for the month of August used with MONTH_IN_YEAR field.
static int	COUNT Field specifying the number of times this event repeats including the first time, starting from the first time the event starts (derived from Event.START) and continuing to the last date of the repeat (defined by RepeatRule.END).
static int	DAILY Used for frequency when the Event happens every day.
static int	DAY_IN_MONTH Field specifying the day of the month an Event occurs; for example, 15.
static int	DAY_IN_WEEK Field specifying the days of the week an Event occurs.
static int	DAY_IN_YEAR Field specifying the day of the year an Event occurs; for example, 134.
static int	DECEMBER Constant for the month of December used with MONTH_IN_YEAR field.
static int	END Field specifying the ending date of the repeating event.
static int	FEBRUARY Constant for the month of February used with MONTH_IN_YEAR field.
static int	FIFTH Constant for the fifth week of the month used with WEEK_OF_MONTH field.
static int	FIFTHLAST Constant for the fifth to last week of the month used with WEEK_OF_MONTH field.
static int	FIRST Constant for the first week of the month used with WEEK_OF_MONTH field.
static int	FOURTH Constant for the fourth week of the month used with WEEK_OF_MONTH field.
static int	FOURTHLAST Constant for the fourth to last week of the month used with WEEK_OF_MONTH field.
static int	FREQUENCY Field specifying the frequency of the Repeat.
static int	FRIDAY Constant for the day of week Friday used with DAY_IN_WEEK field.
static int	INTERVAL Field specifying the number of iterations of the frequency between occurring dates, or how often the frequency repeats.
static int	JANUARY Constant for the month of January used with MONTH_IN_YEAR field.
static int	JULY Constant for the month of July used with MONTH_IN_YEAR field.
static int	JUNE Constant for the month of June used with MONTH_IN_YEAR field.
static int	LAST Constant for the last week of the month used with WEEK_OF_MONTH field.
static int	MARCH Constant for the month of March used with MONTH_IN_YEAR field.
static int	MAY Constant for the month of May used with MONTH_IN_YEAR field.
static int	MONDAY Constant for the day of week Monday used with DAY_IN_WEEK field.
static int	MONTH_IN_YEAR Field specifying the month in which an event occurs.
static int	MONTHLY Used for frequency when the Event happens every month.
static int	NOVEMBER Constant for the month of November used with MONTH_IN_YEAR field.
static int	OCTOBER Constant for the month of October used with MONTH_IN_YEAR field.
static int	SATURDAY Constant for the day of week Saturday used with DAY_IN_WEEK field.
static int	SECOND Constant for the second week of the month used with WEEK_OF_MONTH field.
static int	SECONDLAST Constant for the second to last week of the month used with WEEK_OF_MONTH field.
static int	SEPTEMBER Constant for the month of September used with MONTH_IN_YEAR field.
static int	SUNDAY Constant for the day of week Sunday used with DAY_IN_WEEK field.
static int	THIRD Constant for the third week of the month used with WEEK_OF_MONTH field.
static int	THIRDLAST Constant for the third to last week of the month used with WEEK_OF_MONTH field.
static int	THURSDAY Constant for the day of week Thursday used with DAY_IN_WEEK field.
static int	TUESDAY Constant for the day of week Tuesday used with DAY_IN_WEEK field.
static int	WEDNESDAY Constant for the day of week Wednesday used with DAY_IN_WEEK field.
static int	WEEK_IN_MONTH Field specifying which week in a month a particular event occurs.
static int	WEEKLY Used for frequency when the Event happens every week.
static int	YEARLY Used for frequency when the Event happens every year.

Constructor Summary

RepeatRule()
Default constructor.

Method Summary

void	addExceptDate(long date) Add a Date for which this RepeatRule should not occur.
java.util.Enumeration	dates(long startDate, long subsetBeginning, long subsetEnding) Returns an Enumeration of dates on which an Event would occur.
boolean	equals(java.lang.Object obj) Compares this RepeatRule with a given RepeatRule for content equality.
long	getDate(int field) Retrieves a Date field.
java.util.Enumeration	getExceptDates() Returns the Dates for which this RepeatRule should not occur.
int[]	getFields() Returns a list of fields that currently have values assigned to it.
int	getInt(int field) Retrieves an integer field.
void	removeExceptDate(long date) Remove a Date for which this RepeatRule should not occur.
void	setDate(int field, long value) Sets a Date field.
void	setInt(int field, int value) Sets an integer field.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FREQUENCY

public static final int FREQUENCY

Field specifying the frequency of the Repeat. This field has a value of either DAILY, WEEKLY, MONTHLY or YEARLY. The default data value associated with this field in RepeatRule is DAILY. This field can be checked for support by EventList.getSupportedRepeatRuleFields(int).

See Also:

Constant Field Values

DAY_IN_MONTH

public static final int DAY_IN_MONTH

Field specifying the day of the month an Event occurs; for example, 15. This value is 1 based from the first day of the month. This field can be checked for support in the bit array values returned by EventList.getSupportedRepeatRuleFields(int).

See Also:

Constant Field Values

DAY_IN_WEEK

public static final int DAY_IN_WEEK

Field specifying the days of the week an Event occurs. To set multiple days, OR the values together (e.g. MONDAY | THURSDAY). Retrieval of data for this field can contain multiple days OR'd together in the same manner as setting the value. This field can be checked for support in the bit array values returned by EventList.getSupportedRepeatRuleFields(int).

See Also:

Constant Field Values

DAY_IN_YEAR

public static final int DAY_IN_YEAR

Field specifying the day of the year an Event occurs; for example, 134. This value is 1 based from the first day of the beginning of the year. This field can be checked for support in the bit array values returned by EventList.getSupportedRepeatRuleFields(int).

See Also:

Constant Field Values

MONTH_IN_YEAR

public static final int MONTH_IN_YEAR

Field specifying the month in which an event occurs. To set multiple months, OR the values together (e.g. RepeatRule.JANUARY | RepeatRule.FEBRUARY ). Retrieval of data for this field can contain multiple months OR'd together in the same manner as setting the value. This field can be checked for support in the bit array values returned by EventList.getSupportedRepeatRuleFields(int).

See Also:

Constant Field Values

WEEK_IN_MONTH

public static final int WEEK_IN_MONTH

Field specifying which week in a month a particular event occurs. To set multiple weeks, OR the values together (e.g. FIRST | LAST | SECOND | SECONDLAST). Retrieval of data for this field can contain multiple weeks OR'd together in the same manner as setting the value. This field can be checked for support in the bit array values returned by EventList.getSupportedRepeatRuleFields(int).

See Also:

Constant Field Values

COUNT

public static final int COUNT

Field specifying the number of times this event repeats including the first time, starting from the first time the event starts (derived from Event.START) and continuing to the last date of the repeat (defined by RepeatRule.END). COUNT controls the number of times the event occurs during the period and is used with RepeatRule interval and the frequency to calculate when the event occurs. RepeatRule.END overrides this data if the end is reached prior to the count finishing. If COUNT is 0 and END is null, the event repeats forever. This field can be checked for support in the bit array values returned by EventList.getSupportedRepeatRuleFields(int).

See Also:

Constant Field Values

END

public static final int END

Field specifying the ending date of the repeating event. Data for this field is expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970). This field can be checked for support in the bit array values returned by EventList.getSupportedRepeatRuleFields(int).

See Also:

Constant Field Values

INTERVAL

public static final int INTERVAL

Field specifying the number of iterations of the frequency between occurring dates, or how often the frequency repeats. For example, for every other day the FREQUENCY is DAILY and INTERVAL is 2. The default value for data associated with this field is 1. This field can be checked for support in the bit array values returned by EventList.getSupportedRepeatRuleFields(int).

See Also:

Constant Field Values

DAILY

public static final int DAILY

Used for frequency when the Event happens every day.

See Also:

Constant Field Values

WEEKLY

public static final int WEEKLY

Used for frequency when the Event happens every week.

See Also:

Constant Field Values

MONTHLY

public static final int MONTHLY

Used for frequency when the Event happens every month.

See Also:

Constant Field Values

YEARLY

public static final int YEARLY

Used for frequency when the Event happens every year.

See Also:

Constant Field Values

FIRST

public static final int FIRST

Constant for the first week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

SECOND

public static final int SECOND

Constant for the second week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

THIRD

public static final int THIRD

Constant for the third week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

FOURTH

public static final int FOURTH

Constant for the fourth week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

FIFTH

public static final int FIFTH

Constant for the fifth week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

LAST

public static final int LAST

Constant for the last week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

SECONDLAST

public static final int SECONDLAST

Constant for the second to last week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

THIRDLAST

public static final int THIRDLAST

Constant for the third to last week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

FOURTHLAST

public static final int FOURTHLAST

Constant for the fourth to last week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

FIFTHLAST

public static final int FIFTHLAST

Constant for the fifth to last week of the month used with WEEK_OF_MONTH field.

See Also:

Constant Field Values

SATURDAY

public static final int SATURDAY

Constant for the day of week Saturday used with DAY_IN_WEEK field.

See Also:

Constant Field Values

FRIDAY

public static final int FRIDAY

Constant for the day of week Friday used with DAY_IN_WEEK field.

See Also:

Constant Field Values

THURSDAY

public static final int THURSDAY

Constant for the day of week Thursday used with DAY_IN_WEEK field.

See Also:

Constant Field Values

WEDNESDAY

public static final int WEDNESDAY

Constant for the day of week Wednesday used with DAY_IN_WEEK field.

See Also:

Constant Field Values

TUESDAY

public static final int TUESDAY

Constant for the day of week Tuesday used with DAY_IN_WEEK field.

See Also:

Constant Field Values

MONDAY

public static final int MONDAY

Constant for the day of week Monday used with DAY_IN_WEEK field.

See Also:

Constant Field Values

SUNDAY

public static final int SUNDAY

Constant for the day of week Sunday used with DAY_IN_WEEK field.

See Also:

Constant Field Values

JANUARY

public static final int JANUARY

Constant for the month of January used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

FEBRUARY

public static final int FEBRUARY

Constant for the month of February used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

MARCH

public static final int MARCH

Constant for the month of March used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

APRIL

public static final int APRIL

Constant for the month of April used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

MAY

public static final int MAY

Constant for the month of May used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

JUNE

public static final int JUNE

Constant for the month of June used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

JULY

public static final int JULY

Constant for the month of July used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

AUGUST

public static final int AUGUST

Constant for the month of August used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

SEPTEMBER

public static final int SEPTEMBER

Constant for the month of September used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

OCTOBER

public static final int OCTOBER

Constant for the month of October used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

NOVEMBER

public static final int NOVEMBER

Constant for the month of November used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

DECEMBER

public static final int DECEMBER

Constant for the month of December used with MONTH_IN_YEAR field.

See Also:

Constant Field Values

Constructor Detail

RepeatRule

public RepeatRule()

Default constructor.

Method Detail

dates

public java.util.Enumeration dates(long startDate,
                                   long subsetBeginning,
                                   long subsetEnding)

Returns an Enumeration of dates on which an Event would occur. A start date is specified form which the repeating rule is applied to generate dates. Then a beginning date and a start date is also provided to return only a subset of all possible occurrences of an Event within the given timeframe. The sequence of the items is by date. Exceptional dates are not included in the returned Enumeration.
For example, an Event may happen every Monday during a year starting on January 1st. However, one wants to know occurrences of the Event during the month of June only. The startDate parameter specifies the anchor point for the Event from which it begins repeating, and the subsetBeginning and subsetEnding parameters would limit the Events returned to those only in June in this example.

Parameters:

startDate - the start date for the sequence, from which the repeat rule is applied to generate possible occurrence dates. This value must be expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

subsetBeginning - the beginning date of the period for which events should be returned. This value must be expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

subsetEnding - the end date of the period for which events should be returned. This value must be expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Returns:

an Enumeration of dates for the given parameters, with the Enumeration containing java.util.Date instances.

Throws:

java.lang.IllegalArgumentException - if beginning is greater than ending.

addExceptDate

public void addExceptDate(long date)

Add a Date for which this RepeatRule should not occur. This value may be rounded off to the date only from a date time stamp if the underlying platform implementation only supports date fields with dates only and not date time stamps.

Parameters:

date - the date to add to the list of except dates, expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

removeExceptDate

public void removeExceptDate(long date)

Remove a Date for which this RepeatRule should not occur. If the date was in the list of except dates, it is removed.

Parameters:

date - the date to remove from the list of except dates expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

getExceptDates

public java.util.Enumeration getExceptDates()

Returns the Dates for which this RepeatRule should not occur.

Returns:

an Enumeration of dates for which this RepeatRule should not occur, with the Enumeration containing java.util.Date instances.

getInt

public int getInt(int field)

Retrieves an integer field. The field values can be one of COUNT, DAY_IN_MONTH, FREQUENCY, INTERVAL, MONTH_IN_YEAR, WEEK_IN_MONTH, DAY_IN_WEEK, DAY_IN_YEAR. getFields() should be checked prior to invoking the method to ensure the field has a value associated with it.

Parameters:

field - The field to get, for example COUNT.

Returns:

an int representing the value of the field.

Throws:

java.lang.IllegalArgumentException - if field is not one of the the valid RepeatRule fields for this method.

FieldEmptyException - if the field does is a valid integer field but does not have any data values assigned to it.

setInt

public void setInt(int field,
                   int value)

Sets an integer field. The field value can be one of COUNT, DAYNUMBER, FREQUENCY, INTERVAL, MONTH_IN_YEAR, WEEK_IN_MONTH, DAY_IN_WEEK, DAY_IN_YEAR.

Parameters:

field - The field to set, for example COUNT.

value - The value to set the field to.

Throws:

java.lang.IllegalArgumentException - if field is not one of the the valid RepeatRule fields for this method, or the value provided is not a valid value for the given field.

getDate

public long getDate(int field)

Retrieves a Date field. The field value is currently limited to END. getFields() should be checked prior to invoking the method to ensure the field has a value associated with it.

Parameters:

field - The field to get.

Returns:

a Date representing the value of the field, expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Throws:

java.lang.IllegalArgumentException - if field is not one of the the valid RepeatRule fields for this method.

FieldEmptyException - if the field does is a valid date field but does not have any data values assigned to it.

setDate

public void setDate(int field,
                    long value)

Sets a Date field. The field value is currently limited to END. This field may be rounded off to the date only from a date time stamp if the underlying platform implementation only supports date fields with dates only and not date time stamps.

Parameters:

field - The field to set.

value - The value to set the field to, expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Throws:

java.lang.IllegalArgumentException - if field is not one of the the valid RepeatRule fields for this method.

getFields

public int[] getFields()

Returns a list of fields that currently have values assigned to it. If a field is not "set", the field is not included in the return value.

Returns:

an array of fields that have values currently assigned to them. If no fields have values set, an array of zero length is returned.

equals

public boolean equals(java.lang.Object obj)

Compares this RepeatRule with a given RepeatRule for content equality. For RepeatRules, dates are considered equal if one or both of the dates compared contains a date only with no timestamp and the date values are equal regardless of the time qualifier. This rule accounts for platform dependent rounding off of dates from date time stamps to dates only. For example, a date value of 3/14/03 with no time stamp is considered equal to a date value of 3/14/03 with a time stamp. If the application requires that dates be exactly equal, comparisons should be made explicitly outside of this method.

Overrides:

equals in class java.lang.Object

Parameters:

obj - another RepeatRule object to compare against

Returns:

true if the contents of the RepeatRules are equivalent, false otherwise.