TimeFence

  • The TimeFence class is used to create time-based fences.

  • Time fences can be defined relative to semantic time instants like sunrise or sunset, specific daily intervals, or absolute time intervals.

  • Predefined constants are available for days of the week and common time intervals like morning, afternoon, evening, night, weekday, weekend, and holiday.

  • Some methods for specific days of the week are deprecated in favor of a more general method.
public final class TimeFence extends Object

Use this class to create time-based fences.

Constant Summary

int DAY_OF_WEEK_FRIDAY Corresponds to Friday
int DAY_OF_WEEK_MONDAY Corresponds to Monday
int DAY_OF_WEEK_SATURDAY Corresponds to Saturday
int DAY_OF_WEEK_SUNDAY Corresponds to Sunday
int DAY_OF_WEEK_THURSDAY Corresponds to Thursday
int DAY_OF_WEEK_TUESDAY Corresponds to Tuesday
int DAY_OF_WEEK_WEDNESDAY Corresponds to Wednesday
int TIME_INSTANT_SUNRISE Denotes sunrise at the device location.
int TIME_INSTANT_SUNSET Denotes sunset at the device location.
int TIME_INTERVAL_AFTERNOON Denotes the period of a day that is classified as afternoon (for example 12 noon - 4PM)
int TIME_INTERVAL_EVENING Denotes the period of a day that is classified as evening (for example 4PM - 9PM)
int TIME_INTERVAL_HOLIDAY Denotes a government-sanctioned holiday (implying that most schools and offices are closed) for the device locale at the current time (internationalized properly).
int TIME_INTERVAL_MORNING Denotes the period of a day that is classified as morning (for example 8AM - 12 noon)
int TIME_INTERVAL_NIGHT Denotes the period of a day that is classified as night (for example 9PM - 8AM)
int TIME_INTERVAL_WEEKDAY Denotes a weekday for the device locale at the current time (internationalized properly).
int TIME_INTERVAL_WEEKEND Denotes a weekend for the device locale at the current time (internationalized properly).

Public Method Summary

static AwarenessFence
aroundTimeInstant(int timeInstant, long startOffsetMillis, long stopOffsetMillis)
This is a time fence that is in the TRUE state during a time interval defined with respect to TIME_INSTANT_SUNRISE or TIME_INSTANT_SUNSET instants.
static AwarenessFence
inDailyInterval(TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)
This fence is in the TRUE state during the interval specified by startTimeOfDayMillis and stopTimeOfDayMillis in the given timeZone.
static AwarenessFence
inFridayInterval(TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)
DEPRECATED.
static AwarenessFence
inInterval(long startTimeMillis, long stopTimeMillis)
This fence is in the TRUE state when the current time is within the absolute times indicated by startTimeMillis and stopTimeMillis.
static AwarenessFence
inIntervalOfDay(int dayOfWeek, TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)
This fence is in the TRUE state on dayOfWeek during the interval specified by startTimeOfDayMillis to stopTimeOfDayMillis in the given timeZone.
static AwarenessFence
inMondayInterval(TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)
DEPRECATED.
static AwarenessFence
inSaturdayInterval(TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)
DEPRECATED.
static AwarenessFence
inSundayInterval(TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)
DEPRECATED.
static AwarenessFence
inThursdayInterval(TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)
DEPRECATED.
static AwarenessFence
inTimeInterval(int timeInterval)
This fence is in the TRUE state if the day attributes for the present day/time is one of the attributes specified in the given dayAttributes.
static AwarenessFence
inTuesdayInterval(TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)
DEPRECATED.
static AwarenessFence
inWednesdayInterval(TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)
DEPRECATED.

Inherited Method Summary

Constants

public static final int DAY_OF_WEEK_FRIDAY

Corresponds to Friday

Constant Value: 6

public static final int DAY_OF_WEEK_MONDAY

Corresponds to Monday

Constant Value: 2

public static final int DAY_OF_WEEK_SATURDAY

Corresponds to Saturday

Constant Value: 7

public static final int DAY_OF_WEEK_SUNDAY

Corresponds to Sunday

Constant Value: 1

public static final int DAY_OF_WEEK_THURSDAY

Corresponds to Thursday

Constant Value: 5

public static final int DAY_OF_WEEK_TUESDAY

Corresponds to Tuesday

Constant Value: 3

public static final int DAY_OF_WEEK_WEDNESDAY

Corresponds to Wednesday

Constant Value: 4

public static final int TIME_INSTANT_SUNRISE

Denotes sunrise at the device location.

Constant Value: 1

public static final int TIME_INSTANT_SUNSET

Denotes sunset at the device location.

Constant Value: 2

public static final int TIME_INTERVAL_AFTERNOON

Denotes the period of a day that is classified as afternoon (for example 12 noon - 4PM)

Constant Value: 5

public static final int TIME_INTERVAL_EVENING

Denotes the period of a day that is classified as evening (for example 4PM - 9PM)

Constant Value: 6

public static final int TIME_INTERVAL_HOLIDAY

Denotes a government-sanctioned holiday (implying that most schools and offices are closed) for the device locale at the current time (internationalized properly). As an example, in the U.S., some examples of holidays are Thanksgiving day, Christmas day, Independence day.

Constant Value: 3

public static final int TIME_INTERVAL_MORNING

Denotes the period of a day that is classified as morning (for example 8AM - 12 noon)

Constant Value: 4

public static final int TIME_INTERVAL_NIGHT

Denotes the period of a day that is classified as night (for example 9PM - 8AM)

Constant Value: 7

public static final int TIME_INTERVAL_WEEKDAY

Denotes a weekday for the device locale at the current time (internationalized properly). As an example, in the U.S., weekdays are understood to be Monday, Tuesday, Wednesday, Thursday, Friday.

Constant Value: 1

public static final int TIME_INTERVAL_WEEKEND

Denotes a weekend for the device locale at the current time (internationalized properly). As an example, in the U.S., weekdays are understood to be Saturday and Sunday.

Constant Value: 2

Public Methods

public static AwarenessFence aroundTimeInstant (int timeInstant, long startOffsetMillis, long stopOffsetMillis)

This is a time fence that is in the TRUE state during a time interval defined with respect to TIME_INSTANT_SUNRISE or TIME_INSTANT_SUNSET instants. For example, if it is relative to TIME_INSTANT_SUNRISE, and sunrise time is denoted by variable T, then this fence is in the TRUE state during the period [T + startOffsetMillis, T + stopOffsetMillis].

Parameters
timeInstant is the desired semantic time label around which fence triggers are defined to happen. This value should be one of the following supported labels: TIME_INSTANT_SUNRISE, TIME_INSTANT_SUNSET.
startOffsetMillis is the offset from the beginning of the semantic time period. It can be specified as a positive or negative offset value but should be between -24 to 24 hours inclusive (expressed in millis)
stopOffsetMillis is the offset from the end of the semantic time period. It can be specified as a positive or negative offset value but should be between -24 to 24 hours inclusive (expressed in millis) constraint: startOffsetMillis < stopOffsetMillis
Returns
  • AwarenessFence that is TRUE when the current time falls within the interval specified based on the semantic time label and offsets.
Throws
IllegalStateException if startOffsetMillis >= stopOffsetMillis or if the absolute value of startOffsetMillis or stopOffsetMillis is greater than 24 * 60 * 60 * 1000 which is the millis equivalent of 24 hours.
IllegalArgumentException if an unknown or invalid semantic time label is provided

public static AwarenessFence inDailyInterval (TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)

This fence is in the TRUE state during the interval specified by startTimeOfDayMillis and stopTimeOfDayMillis in the given timeZone. If the timeZone is null, the current device time zone is used. The fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).

Note: prior to Play services 11.0.1 a null value for the timeZone parameter throws a NullPointerException.

Parameters
timeZone The time zone to use. If set to null, current device time zone is used, and the fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).
startTimeOfDayMillis Milliseconds since the start of the day. 12:00 am is 0L. The maximum value is the number of milliseconds in a day, namely 24L * 60L * 60L * 1000L.
stopTimeOfDayMillis milliseconds since the start of the day. Same range as startTimeOfDayMillis. This time must be greater than or equal to startTimeOfDayMillis.
Returns

public static AwarenessFence inFridayInterval (TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)

DEPRECATED. Use inIntervalOfDay(int, TimeZone, long, long) instead.

This fence is in the TRUE state for Friday in the interval specified by startTimeOfDayMillis and stopTimeOfDayMillis in the given timeZone. If the timeZone is null, the current device time zone is used. The fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).

Note: prior to Play services 11.0.1 a null value for the timeZone parameter throws a NullPointerException.

Parameters
timeZone The time zone to use. If set to null, current device time zone is used, and the fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).
startTimeOfDayMillis Milliseconds since the start of the day. 12:00 am is 0L. The maximum value is the number of milliseconds in a day, namely 24L * 60L * 60L * 1000L.
stopTimeOfDayMillis Milliseconds since the start of the day, This time must be greater than or equal to startTimeOfDayMillis.
Returns

public static AwarenessFence inInterval (long startTimeMillis, long stopTimeMillis)

This fence is in the TRUE state when the current time is within the absolute times indicated by startTimeMillis and stopTimeMillis.

Parameters
startTimeMillis Milliseconds since epoch for the start of the interval. Must be greater than or equal to 0L.
stopTimeMillis Milliseconds since epoch for the end of the interval. Must be greater than or equal to startTimeMillis.
Returns

public static AwarenessFence inIntervalOfDay (int dayOfWeek, TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)

This fence is in the TRUE state on dayOfWeek during the interval specified by startTimeOfDayMillis to stopTimeOfDayMillis in the given timeZone. If the timeZone is null, the current device time zone is used. The fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).

Note: prior to Play services 11.0.1 a null value for the timeZone parameter throws a NullPointerException.

Parameters
dayOfWeek is the day of the week. Valid values for this parameter are: DAY_OF_WEEK_SUNDAY, DAY_OF_WEEK_MONDAY, DAY_OF_WEEK_TUESDAY, DAY_OF_WEEK_WEDNESDAY, DAY_OF_WEEK_THURSDAY, DAY_OF_WEEK_FRIDAY, DAY_OF_WEEK_SATURDAY.
timeZone The time zone to use. If set to null, current device time zone is used, and the fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).
startTimeOfDayMillis Milliseconds since the start of the day. 12:00 am is 0L. The maximum value is the number of milliseconds in a day, namely 24L * 60L * 60L * 1000L.
stopTimeOfDayMillis Milliseconds since the start of the day, This time must be greater than or equal to startTimeOfDayMillis.
Returns

public static AwarenessFence inMondayInterval (TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)

DEPRECATED. Use inIntervalOfDay(int, TimeZone, long, long) instead.

This fence is in the TRUE state for Monday in the interval specified by startTimeOfDayMillis and stopTimeOfDayMillis in the given timeZone. If the timeZone is null, the current device time zone is used. The fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).

Note: prior to Play services 11.0.1 a null value for the timeZone parameter throws a NullPointerException.

Parameters
timeZone The time zone to use. If set to null, current device time zone is used, and the fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).
startTimeOfDayMillis Milliseconds since the start of the day. 12:00 am is 0L. The maximum value is the number of milliseconds in a day, namely 24L * 60L * 60L * 1000L.
stopTimeOfDayMillis Milliseconds since the start of the day, This time must be greater than or equal to startTimeOfDayMillis.
Returns

public static AwarenessFence inSaturdayInterval (TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)

DEPRECATED. Use inIntervalOfDay(int, TimeZone, long, long) instead.

This fence is in the TRUE state for Saturday in the interval specified by startTimeOfDayMillis and stopTimeOfDayMillis in the given timeZone. If the timeZone is null, the current device time zone is used. The fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).

Note: prior to Play services 11.0.1 a null value for the timeZone parameter throws a NullPointerException.

Parameters
timeZone The time zone to use. If set to null, current device time zone is used, and the fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).
startTimeOfDayMillis Milliseconds since the start of the day. 12:00 am is 0L. The maximum value is the number of milliseconds in a day, namely 24L * 60L * 60L * 1000L.
stopTimeOfDayMillis Milliseconds since the start of the day, This time must be greater than or equal to startTimeOfDayMillis.
Returns

public static AwarenessFence inSundayInterval (TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)

DEPRECATED. Use inIntervalOfDay(int, TimeZone, long, long) instead.

This fence is in the TRUE state for Sunday in the interval specified by startTimeOfDayMillis and stopTimeOfDayMillis in the given timeZone. If the timeZone is null, the current device time zone is used. The fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).

Note: prior to Play services 11.0.1 a null value for the timeZone parameter throws a NullPointerException.

Parameters
timeZone The time zone to use. If set to null, current device time zone is used, and the fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).
startTimeOfDayMillis Milliseconds since the start of the day. 12:00 am is 0L. The maximum value is the number of milliseconds in a day, namely 24L * 60L * 60L * 1000L.
stopTimeOfDayMillis Milliseconds since the start of the day, This time must be greater than or equal to startTimeOfDayMillis.
Returns

public static AwarenessFence inThursdayInterval (TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)

DEPRECATED. Use inIntervalOfDay(int, TimeZone, long, long) instead.

This fence is in the TRUE state for Thursday in the interval specified by startTimeOfDayMillis and stopTimeOfDayMillis in the given timeZone. If the timeZone is null, the current device time zone is used. The fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).

Note: prior to Play services 11.0.1 a null value for the timeZone parameter throws a NullPointerException.

Parameters
timeZone The time zone to use. If set to null, current device time zone is used, and the fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).
startTimeOfDayMillis Milliseconds since the start of the day. 12:00 am is 0L. The maximum value is the number of milliseconds in a day, namely 24L * 60L * 60L * 1000L.
stopTimeOfDayMillis Milliseconds since the start of the day, This time must be greater than or equal to startTimeOfDayMillis.
Returns

public static AwarenessFence inTimeInterval (int timeInterval)

This fence is in the TRUE state if the day attributes for the present day/time is one of the attributes specified in the given dayAttributes.

Parameters
timeInterval is the desired attributes of the day for which this fence will trigger. Some sample attributes are TIME_INTERVAL_MORNING, TIME_INTERVAL_AFTERNOON, TIME_INTERVAL_EVENING, TIME_INTERVAL_NIGHT, TIME_INTERVAL_WEEKDAY, TIME_INTERVAL_WEEKEND, TIME_INTERVAL_HOLIDAY.
Returns
  • AwarenessFence that triggers when the day attributes of the present moment is the specified attribute .

public static AwarenessFence inTuesdayInterval (TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)

DEPRECATED. Use inIntervalOfDay(int, TimeZone, long, long) instead.

This fence is in the TRUE state for Tuesday in the interval specified by startTimeOfDayMillis and stopTimeOfDayMillis in the given timeZone. If the timeZone is null, the current device time zone is used. The fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).

Note: prior to Play services 11.0.1 a null value for the timeZone parameter throws a NullPointerException.

Parameters
timeZone The time zone to use. If set to null, current device time zone is used, and the fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).
startTimeOfDayMillis Milliseconds since the start of the day. 12:00 am is 0L. The maximum value is the number of milliseconds in a day, namely 24L * 60L * 60L * 1000L.
stopTimeOfDayMillis Milliseconds since the start of the day, This time must be greater than or equal to startTimeOfDayMillis.
Returns

public static AwarenessFence inWednesdayInterval (TimeZone timeZone, long startTimeOfDayMillis, long stopTimeOfDayMillis)

DEPRECATED. Use inIntervalOfDay(int, TimeZone, long, long) instead.

This fence is in the TRUE state for Wednesday in the interval specified by startTimeOfDayMillis and stopTimeOfDayMillis in the given timeZone. If the timeZone is null, the current device time zone is used. The fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).

Note: prior to Play services 11.0.1 a null value for the timeZone parameter throws a NullPointerException.

Parameters
timeZone The time zone to use. If set to null, current device time zone is used, and the fence re-adjusts to account for changes to the time zone (e.g. due to location change, or user-triggered change to Date & time settings).
startTimeOfDayMillis Milliseconds since the start of the day. 12:00 am is 0L. The maximum value is the number of milliseconds in a day, namely 24L * 60L * 60L * 1000L.
stopTimeOfDayMillis Milliseconds since the start of the day, This time must be greater than or equal to startTimeOfDayMillis.
Returns