SHOW Signed

net.rim.blackberry.api.pim
Class RepeatRule

java.lang.Object
  |
  +--net.rim.blackberry.api.pim.RepeatRule

public class RepeatRule

extends Object

Contains the repeating rule functionality for event items. The RepeatRule class defines when and how often an event is repeated, for example, yearly, monthly or daily.

You can use the RepeatRule object to create a recurring event by allowing you to specify a recurrence pattern for the event. The RepeatRule allows you to specify the frequency, interval and number of recurrences for each event.

Below, a RepeatRule is created and associated with a new event. The event will repeat on the 28th day of every month.

         RepeatRule recurring = new RepeatRule();
         recurring.setInt(RepeatRule.FREQUENCY, RepeatRule.MONTHLY); 
         recurring.setInt(RepeatRule.DAY_IN_MONTH, 28); 
 
         events = EventList.open(EventList.READ_WRITE);
         Event event = events.createEvent();
         event.setRepeat(recurring);
 

For more information about this class or about the personal information management (PIM) API, refer to The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Since:

PDAP 1.0

See Also:

Event, EventList

Field Summary

	static int	APRIL Represents the constant for the month: April.
	static int	AUGUST Represents the constant for the month: August.
	static int	COUNT Represents the number of times the event will occur.
	static int	DAILY Indicates that the frequency of the event occurs daily.
	static int	DAY_IN_MONTH Represents the day in the month that this event will occur.
	static int	DAY_IN_WEEK Represents the day in the week that this event will occur.
	static int	DAY_IN_YEAR Represents the day in the year that this event will occur.
	static int	DECEMBER Represents the constant for the month: December.
	static int	END Represents the end date of an event.
	static int	FEBRUARY Represents the constant for the month: February.
	static int	FIFTH Represents the fifth week of the month.
	static int	FIFTHLAST Represents the fifth last week of the month.
	static int	FIRST Represents the first week of the month.
	static int	FOURTH Represents the fourth week of the month.
	static int	FOURTHLAST Represents the fourth last week of the month.
	static int	FREQUENCY Represents the frequency of the event.
	static int	FRIDAY Represents the constant for the day: Friday.
	static int	INTERVAL The interval represents the amount of times between events, or the number of times the frequency repeats.
	static int	JANUARY Represents the constant for the month: January.
	static int	JULY Represents the constant for the month: July.
	static int	JUNE Represents the constant for the month: June.
	static int	LAST Represents the last week of the month.
	static int	MARCH Represents the constant for the month: March.
	static int	MAY Represents the constant for the month: May.
	static int	MONDAY Represents the constant for the day: Monday.
	static int	MONTH_IN_YEAR Represents the month in the year that this event will occur.
	static int	MONTHLY Indicates that the frequency of the event occurs monthly.
	static int	NOVEMBER Represents the constant for the month: November.
	static int	OCTOBER Represents the constant for the month: October.
	static int	SATURDAY Represents the constant for the day: Saturday.
	static int	SECOND Represents the second week of the month.
	static int	SECONDLAST Represents the second last week of the month.
	static int	SEPTEMBER Represents the constant for the month: September.
	static int	SUNDAY Represents the constant for the day: Sunday.
	static int	THIRD Represents the third week of the month.
	static int	THIRDLAST Represents the third last week of the month.
	static int	THURSDAY Represents the constant for the day: Thursday.
	static int	TUESDAY Represents the constant for the day: Tuesday.
	static int	WEDNESDAY Represents the constant for the day: Wednesday.
	static int	WEEK_IN_MONTH Represents the week in the month that this event will occur.
	static int	WEEKLY Indicates that the frequency of the event occurs weekly.
	static int	YEARLY Indicates that the frequency of the event occurs yearly.

Constructor Summary

RepeatRule() Creates a new RepeatRule instance.

Method Summary

	void	addExceptDate(long date) Adds a date for which the event will not occur.
	Enumeration	dates(long startDate, long subsetBeginning, long subsetEnding) Returns an enumeration of event dates, ordered by date, between the specified subsetBeginning and subsetEnding parameters.
	long	getDate(int field) Returns the date of the specified field.
	long[]	getExceptDates() Returns an array containing the dates on which the RepeatRule will not occur.
	int[]	getFields() Returns an array of integers representing the fields in the RepeatRule.
	int	getInt(int field) Returns an integer representing a RepeatRule field value.
	void	removeExceptDate(long date) Removes an excepted date from the RepeatRule.
	void	setDate(int field, long value) Sets a date for the specified field.
	void	setInt(int field, int value) Sets an integer that specifies a RepeatRule field and value.

Methods inherited from class java.lang.Object

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

Field Detail

COUNT

public static final int COUNT

Represents the number of times the event will occur.

This value is determined using Event.START and RepeatRule.END

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

DAY_IN_MONTH

public static final int DAY_IN_MONTH

Represents the day in the month that this event will occur.

This index is 1-based. In other words, the value 15 represents the 15th day of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

DAY_IN_WEEK

public static final int DAY_IN_WEEK

Represents the day in the week that this event will occur.

This index is 1-based. In other words, the value 2 represents the 2nd day of the week. Values can be OR'd together to indicate a multple day event.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

DAY_IN_YEAR

public static final int DAY_IN_YEAR

Represents the day in the year that this event will occur.

This index is 1-based. In other words, the value 200 represents the 200th day of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

END

public static final int END

Represents the end date of an event.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FREQUENCY

public static final int FREQUENCY

Represents the frequency of the event.

This value can be YEARLY, MONTHLY, WEEKLY, DAILY.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

INTERVAL

public static final int INTERVAL

The interval represents the amount of times between events, or the number of times the frequency repeats.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

MONTH_IN_YEAR

public static final int MONTH_IN_YEAR

Represents the month in the year that this event will occur.

This index is 1-based. In other words, the value 6 represents the 6th month of the year. Values can be OR'd together to set multple months.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

WEEK_IN_MONTH

public static final int WEEK_IN_MONTH

Represents the week in the month that this event will occur.

This index is 1-based. In other words, the value 2 represents the 2nd week of the month. Values can be OR'd together to set multple weeks.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

DAILY

public static final int DAILY

Indicates that the frequency of the event occurs daily.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

WEEKLY

public static final int WEEKLY

Indicates that the frequency of the event occurs weekly.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

MONTHLY

public static final int MONTHLY

Indicates that the frequency of the event occurs monthly.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

YEARLY

public static final int YEARLY

Indicates that the frequency of the event occurs yearly.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FIRST

public static final int FIRST

Represents the first week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

SECOND

public static final int SECOND

Represents the second week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

THIRD

public static final int THIRD

Represents the third week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FOURTH

public static final int FOURTH

Represents the fourth week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FIFTH

public static final int FIFTH

Represents the fifth week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

LAST

public static final int LAST

Represents the last week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

SECONDLAST

public static final int SECONDLAST

Represents the second last week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

THIRDLAST

public static final int THIRDLAST

Represents the third last week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FOURTHLAST

public static final int FOURTHLAST

Represents the fourth last week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FIFTHLAST

public static final int FIFTHLAST

Represents the fifth last week of the month.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

SATURDAY

public static final int SATURDAY

Represents the constant for the day: Saturday.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FRIDAY

public static final int FRIDAY

Represents the constant for the day: Friday.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

THURSDAY

public static final int THURSDAY

Represents the constant for the day: Thursday.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

WEDNESDAY

public static final int WEDNESDAY

Represents the constant for the day: Wednesday.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

TUESDAY

public static final int TUESDAY

Represents the constant for the day: Tuesday.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

MONDAY

public static final int MONDAY

Represents the constant for the day: Monday.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

SUNDAY

public static final int SUNDAY

Represents the constant for the day: Sunday.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

JANUARY

public static final int JANUARY

Represents the constant for the month: January.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FEBRUARY

public static final int FEBRUARY

Represents the constant for the month: February.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

MARCH

public static final int MARCH

Represents the constant for the month: March.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

APRIL

public static final int APRIL

Represents the constant for the month: April.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

MAY

public static final int MAY

Represents the constant for the month: May.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

JUNE

public static final int JUNE

Represents the constant for the month: June.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

JULY

public static final int JULY

Represents the constant for the month: July.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

AUGUST

public static final int AUGUST

Represents the constant for the month: August.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

SEPTEMBER

public static final int SEPTEMBER

Represents the constant for the month: September.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

OCTOBER

public static final int OCTOBER

Represents the constant for the month: October.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NOVEMBER

public static final int NOVEMBER

Represents the constant for the month: November.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

DECEMBER

public static final int DECEMBER

Represents the constant for the month: December.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Constructor Detail

RepeatRule

public RepeatRule()

Creates a new RepeatRule instance.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Method Detail

dates

public Enumeration dates(long startDate,
                         long subsetBeginning,
                         long subsetEnding)

Returns an enumeration of event dates, ordered by date, between the specified subsetBeginning and subsetEnding parameters.

Excepted dates (as excepted by the addExceptDate(long) method, are events which will not occur.

Parameters:

startDate - The start date for which to begin.

subsetBeginning - The starting date for which to return event dates.

subsetEnding - The ending date for which to return end dates. The value null specifies that no more events occur.

Returns:

An enumeration of event dates given the start date and end date.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

addExceptDate

public void addExceptDate(long date)

Adds a date for which the event will not occur.

For example, weekly pickup hockey will not occur during the third and fourth week of the twelfth month.

Parameters:

date - The date on which the event will be excepted.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

removeExceptDate

public void removeExceptDate(long date)

Removes an excepted date from the RepeatRule.

Parameters:

date - The date on which the previously excepted date will occur.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getExceptDates

public long[] getExceptDates()

Returns an array containing the dates on which the RepeatRule will not occur.

Returns:

An array of longs representing the excepted dates.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getInt

public int getInt(int field)

Returns an integer representing a RepeatRule field value.

The value can be one of the following: COUNT, DAYNUMBER, FREQUENCY, INTERVAL, MONTH_IN_YEAR, WEEK_IN_MONTH, DAY_IN_WEEK, DAY_IN_YEAR.

Parameters:

field - The field for which to return the integer value.

Returns:

An integer representing the field value.

Throws:

IllegalArgumentException - Thrown if the specifed field is not valid.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setInt

public void setInt(int field,
                   int value)

Sets an integer that specifies a RepeatRule field and value.

Parameters:

field - An integer represnting the field to set.

value - An integer representing the value to set. Setting the field to null clears it.

Throws:

IllegalArgumentException - Thrown if field is not one of the the valid RepeatRule fields for this method, or if value is not a valid value for field

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getDate

public long getDate(int field)

Returns the date of the specified field.

The field value is currently limited to END.

Parameters:

field - The field for which to return the date value.

Returns:

A long (MS format) representing the date. The value 0 indicates that the field has not been set.

Throws:

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

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setDate

public void setDate(int field,
                    long value)

Sets a date for the specified field.

The field value is currently limited to END.

Parameters:

field - The field for which to set the date.

value - The long value to set the date to.

Throws:

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

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getFields

public int[] getFields()

Returns an array of integers representing the fields in the RepeatRule.

Returns:

An integer array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.