PDAP Public Review Draft

javax.microedition.pim
Class EventRepeat

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

public class EventRepeat
extends java.lang.Object

Represents a description for a repeating pattern for an Event element. 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 used on an Event to determine how often the Event occurs.

The following table shows the valid values for the fields that can be set in EventRepeat:
Field IDs Set Method Valid Values
COUNT setInt any positive int
FREQUENCY setInt DAILY, WEEKLY, MONTHLY, YEARLY
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
DAY_IN_WEEK setInt SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY
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(EventRepeat.FREQUENCY, EventRepeat.DAILY);
To specify the associated event occurs every day for the next five days:
      setInt(EventRepeat.FREQUENCY, EventRepeat.DAILY);
      setInt(EventRepeat.COUNT, 5);
To specify this event occurs every week on Monday and Tuesday:
      setInt(EventRepeat.FREQUENCY, EventRepeat.WEEKLY);
      setInt(EventRepeat.DAY_IN_WEEK, EventRepeat.MONDAY | EventRepeat.TUESDAY);
To specify the associated event occurs every third week on Friday:
      setInt(EventRepeat.FREQUENCY, EventRepeat.WEEKLY);
      setInt(EventRepeat.INTERVAL, 3);
      setInt(EventRepeat.DAY_IN_WEEK, EventRepeat.FRIDAY);
To specify the associated event occurs every month on the Wednesday of the second week until the end of the current year:
      setInt(EventRepeat.FREQUENCY, EventRepeat.MONTHLY);
      setInt(EventRepeat.WEEK_IN_MONTH, EventRepeat.SECOND);
      setInt(EventRepeat.DAY_IN_WEEK, EventRepeat.WEDNESDAY);
      java.util.Calendar cal = Calendar.getInstance();
      cal.set(Calendar.MONTH, 12);
      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(EventRepeat.END, cal.getTime().getTime());
To specify the associated event occurs every year on the Sunday of the second week in May:
      setInt(EventRepeat.FREQUENCY, EventRepeat.YEARLY);
      setInt(EventRepeat.MONTH_IN_YEAR, EventRepeat.MAY);
      setInt(EventRepeat.WEEK_IN_MONTH, EventRepeat.SECOND);
      setInt(EventRepeat.DAY_IN_WEEK, EventRepeat.SUNDAY);
To specify the associated event occurs every year on the 4th of July:
      setInt(EventRepeat.FREQUENCY, EventRepeat.YEARLY);
      setInt(EventRepeat.MONTH_IN_YEAR, EventRepeat.JULY);
      setInt(EventRepeat.DAY_IN_MONTH, 4);
To specify the associated event occurs every year on the first day:
      setInt(EventRepeat.FREQUENCY, EventRepeat.YEARLY);
      setInt(EventRepeat.DAY_IN_YEAR, 1);

Since:
PDAP 1.0

Field Summary
static int APRIL
          Constant for the month of April.
static int AUGUST
          Constant for the month of August.
static int COUNT
          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 EventRepeat.END.
static int DAILY
          Used for frequency when the Event happens every day.
static int DAY_IN_MONTH
          The day of the month an Event occurs; for example, 15.
static int DAY_IN_WEEK
          The days of the week an Event occurs.
static int DAY_IN_YEAR
          The day of the year an Event occurs; for example, 134.
static int DECEMBER
          Constant for the month of December.
static int END
          The ending date of the repeating event.
static int FEBRUARY
          Constant for the month of February.
static int FIFTH
          Constant for the fifth week of the month.
static int FIFTHLAST
          Constant for the fifth to last week of the month.
static int FIRST
          Constant for the first week of the month.
static int FOURTH
          Constant for the fourth week of the month.
static int FOURTHLAST
          Constant for the fourth to last week of the month.
static int FREQUENCY
          The frequency of the Repeat.
static int FRIDAY
          Constant for the day of week Friday.
static int INTERVAL
          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.
static int JULY
          Constant for the month of July.
static int JUNE
          Constant for the month of June.
static int LAST
          Constant for the last week of the month.
static int MARCH
          Constant for the month of March.
static int MAY
          Constant for the month of May.
static int MONDAY
          Constant for the day of week Monday.
static int MONTH_IN_YEAR
          The month an event occurs.
static int MONTHLY
          Used for frequency when the Event happens every month.
static int NOVEMBER
          Constant for the month of November.
static int OCTOBER
          Constant for the month of October.
static int SATURDAY
          Constant for the day of week Saturday.
static int SECOND
          Constant for the second week of the month.
static int SECONDLAST
          Constant for the second to last week of the month.
static int SEPTEMBER
          Constant for the month of September.
static int SUNDAY
          Constant for the day of week Sunday.
static int THIRD
          Constant for the third week of the month.
static int THIRDLAST
          Constant for the third to last week of the month.
static int THURSDAY
          Constant for the day of week Thursday.
static int TUESDAY
          Constant for the day of week Tuesday.
static int WEDNESDAY
          Constant for the day of week Wednesday.
static int WEEK_IN_MONTH
          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
EventRepeat()
           
 
Method Summary
 void addExceptDate(long date)
          Add a Date for which this RepeatPattern should not occur.
 Enumeration dates(long startDate, long beginning, long ending)
          Returns an Enumeration of Dates on which an Event would occur.
 long getDate(int fieldID)
          Retrieves a Date field.
 long[] getExceptDates()
          Returns the Dates for which this RepeatPattern should not occur.
 int getInt(int fieldID)
          Retrieves an int field.
 void removeExceptDate(long date)
          Remove a Date for which this RepeatPattern should not occur.
 void setDate(int fieldID, long value)
          Sets a Date field.
 void setInt(int fieldID, int value)
          Sets an int field.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COUNT

public static final int COUNT
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 EventRepeat.END. COUNT controls the number of times the event occurs during the period is used with EventRepeat interval and the frequency to calculate when the event will occur. EventRepeat.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.

Value 1 is assigned to COUNT.


FREQUENCY

public static final int FREQUENCY
The frequency of the Repeat. This is a value of either DAILY, WEEKLY, MONTHLY or YEARLY.

Value 2 is assigned to FREQUENCY.


INTERVAL

public static final int INTERVAL
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.

Value 3 is assigned to INTERVAL.


END

public static final int END
The ending date of the repeating event. Value 4 is assigned to END.

MONTH_IN_YEAR

public static final int MONTH_IN_YEAR
The month an event occurs. To set multiple months, OR the values together (e.g. JANUARY | FEBRUARY ).

Value 5 is assigned to MONTH_IN_YEAR.


WEEK_IN_MONTH

public static final int WEEK_IN_MONTH
Which week in a month a particular event occurs. To set multiple weeks, OR the values together (e.g. FIRST | LAST | SECOND | SECONDLAST).

Value 6 is assigned to WEEK_IN_MONTH.


DAY_IN_WEEK

public static final int DAY_IN_WEEK
The days of the week an Event occurs. To set multiple days, OR the values together (e.g. MONDAY | THURSDAY).

Value 7 is assigned to DAY_IN_WEEK.


DAY_IN_MONTH

public static final int DAY_IN_MONTH
The day of the month an Event occurs; for example, 15. This value is 1 based.

Value 8 is assigned to DAY_IN_MONTH.


DAY_IN_YEAR

public static final int DAY_IN_YEAR
The day of the year an Event occurs; for example, 134.

Value 9 is assigned to DAY_IN_YEAR.


DAILY

public static final int DAILY
Used for frequency when the Event happens every day.

Value 0x10 is assigned to DAILY.


WEEKLY

public static final int WEEKLY
Used for frequency when the Event happens every week.

Value 0x11 is assigned to WEEKLY.


MONTHLY

public static final int MONTHLY
Used for frequency when the Event happens every month.

Value 0x12 is assigned to MONTHLY.


YEARLY

public static final int YEARLY
Used for frequency when the Event happens every year.

Value 0x13 is assigned to YEARLY.


FIRST

public static final int FIRST
Constant for the first week of the month.

Value 0x1 is assigned to FIRST.


SECOND

public static final int SECOND
Constant for the second week of the month.

Value 0x2 is assigned to SECOND.


THIRD

public static final int THIRD
Constant for the third week of the month.

Value 0x4 is assigned to THIRD.


FOURTH

public static final int FOURTH
Constant for the fourth week of the month.

Value 0x8 is assigned to FOURTH.


FIFTH

public static final int FIFTH
Constant for the fifth week of the month.

Value 0x10 is assigned to FIFTH.


LAST

public static final int LAST
Constant for the last week of the month.

Value 0x20 is assigned to LAST.


SECONDLAST

public static final int SECONDLAST
Constant for the second to last week of the month.

Value 0x40 is assigned to SECONDLAST.


THIRDLAST

public static final int THIRDLAST
Constant for the third to last week of the month.

Value 0x80 is assigned to THIRDLAST.


FOURTHLAST

public static final int FOURTHLAST
Constant for the fourth to last week of the month.

Value 0x100 is assigned to FOURTHLAST.


FIFTHLAST

public static final int FIFTHLAST
Constant for the fifth to last week of the month.

Value 0x200 is assigned to FIFTHLAST.


SATURDAY

public static final int SATURDAY
Constant for the day of week Saturday.

Value 0x400 is assigned to SATURDAY.


FRIDAY

public static final int FRIDAY
Constant for the day of week Friday.

Value 0x800 is assigned to FRIDAY.


THURSDAY

public static final int THURSDAY
Constant for the day of week Thursday.

Value 0x1000 is assigned to THURSDAY.


WEDNESDAY

public static final int WEDNESDAY
Constant for the day of week Wednesday.

Value 0x2000 is assigned to WEDNESDAY.


TUESDAY

public static final int TUESDAY
Constant for the day of week Tuesday.

Value 0x4000 is assigned to TUESDAY.


MONDAY

public static final int MONDAY
Constant for the day of week Monday.

Value 0x8000 is assigned to MONDAY.


SUNDAY

public static final int SUNDAY
Constant for the day of week Sunday.

Value 0x10000 is assigned to SUNDAY.


JANUARY

public static final int JANUARY
Constant for the month of January.

Value 0x20000 is assigned to JANUARY.


FEBRUARY

public static final int FEBRUARY
Constant for the month of February.

Value 0x40000 is assigned to FEBRUARY.


MARCH

public static final int MARCH
Constant for the month of March.

Value 0x80000 is assigned to MARCH.


APRIL

public static final int APRIL
Constant for the month of April.

Value 0x100000 is assigned to APRIL.


MAY

public static final int MAY
Constant for the month of May.

Value 0x200000 is assigned to MAY.


JUNE

public static final int JUNE
Constant for the month of June.

Value 0x400000 is assigned to JUNE.


JULY

public static final int JULY
Constant for the month of July.

Value 0x800000 is assigned to JULY.


AUGUST

public static final int AUGUST
Constant for the month of August.

Value 0x1000000 is assigned to AUGUST.


SEPTEMBER

public static final int SEPTEMBER
Constant for the month of September.

Value 0x2000000 is assigned to SEPTEMBER.


OCTOBER

public static final int OCTOBER
Constant for the month of October.

Value 0x4000000 is assigned to OCTOBER.


NOVEMBER

public static final int NOVEMBER
Constant for the month of November.

Value 0x8000000 is assigned to NOVEMBER.


DECEMBER

public static final int DECEMBER
Constant for the month of December.

Value 0x10000000 is assigned to DECEMBER.

Constructor Detail

EventRepeat

public EventRepeat()
Method Detail

dates

public Enumeration dates(long startDate,
                         long beginning,
                         long ending)
Returns an Enumeration of Dates on which an Event would occur. The sequence of the items is by date. Exceptional dates are not returned by this Enumeration.
Parameters:
startDate - the start date for the sequence
beginning - the beginning of the period for which events should be returned
ending - the end of the period for which events should be returned or null to specify all events until there are no more occurences.
Returns:
an Enumeration of Dates in long ms format for the given parameters

addExceptDate

public void addExceptDate(long date)
Add a Date for which this RepeatPattern should not occur.
Parameters:
the - date in long ms format to add to the list of except dates

removeExceptDate

public void removeExceptDate(long date)
Remove a Date for which this RepeatPattern should not occur. If the date was in the list of except dates, it is removed.
Parameters:
the - date in long ms format to remove from the list of except dates

getExceptDates

public long[] getExceptDates()
Returns the Dates for which this RepeatPattern should not occur.
Returns:
the Dates in long ms format for which this RepeatPattern should not occur

getInt

public int getInt(int fieldID)
Retrieves an int field. The field values can be one of COUNT, DAYNUMBER, FREQUENCY, INTERVAL, MONTH_IN_YEAR, WEEK_IN_MONTH, DAY_IN_WEEK, DAY_IN_YEAR.
Parameters:
fieldID - The field ID to get, for example COUNT.
Returns:
an int representing the value of the field.
Throws:
java.lang.IllegalArgumentException - if fieldID is not one of the the valid EventRepeat field IDs for this method.

setInt

public void setInt(int fieldID,
                   int value)
Sets an int 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:
fieldID - The field ID to set, for example COUNT.
value - The value to set the field to.
Throws:
java.lang.IllegalArgumentException - if fieldID is not one of the the valid EventRepeat field IDs for this method.

getDate

public long getDate(int fieldID)
Retrieves a Date field. The field value is currently limited to END.
Parameters:
fieldID - The field ID to get.
Returns:
a Date in long ms format representing the value of the field or 0 to indicate the field has not been set.
Throws:
java.lang.IllegalArgumentException - if fieldID is not one of the the valid EventRepeat field IDs for this method.

setDate

public void setDate(int fieldID,
                    long value)
Sets a Date field. The field value is currently limited to END.
Parameters:
fieldID - The field ID to set.
value - The value to set the field to. Setting a field to null has the effect of clearing it.
Throws:
java.lang.IllegalArgumentException - if fieldID is not one of the the valid EventRepeat field IDs for this method or value is null.

PDAP 1.0 Spec, Rev. 0.16