javax.ejb.Schedule Maven / Gradle / Ivy
/*
* Copyright (c) 2006, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package javax.ejb;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.*;
import java.lang.annotation.Retention;
import static java.lang.annotation.RetentionPolicy.*;
/**
* Schedule a timer for automatic creation with a timeout schedule based
* on a cron-like time expression. The annotated method is
* used as the timeout callback method.
*
* All elements of this annotation are optional. If none are specified
* a persistent timer will be created with callbacks occuring every day
* at midnight in the default time zone associated with the container in
* which the application is executing.
*
* There are seven elements that constitute a schedule specification which are
* listed below. In addition, the timezone element may be used
* to specify a non-default time zone in whose context the schedule
* specification is to be evaluated; the persistent element
* may be used to specify a non-persistent timer, and the info
* element may be used to specify additional information that may be retrieved
* when the timer callback occurs.
*
* The elements that specify the calendar-based schedule itself are as
* follows:
*
*
* - second : one or more seconds within a minute
*
Allowable values: [0,59]
*
*
- minute : one or more minutes within an hour
*
Allowable values : [0,59]
*
*
- hour : one or more hours within a day
*
Allowable values : [0,23]
*
*
- dayOfMonth : one or more days within a month
*
Allowable values:
*
* - [1,31]
*
- [-7, -1]
*
- "Last"
*
- {"1st", "2nd", "3rd", "4th", "5th", "Last"} {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}
*
* "Last" means the last day of the month
*
-x (where x is in the range [-7, -1]) means x day(s) before the last day of the month
*
"1st","2nd", etc. applied to a day of the week identifies a single occurrence of that day within the month.
*
*
- month : one or more months within a year
*
Allowable values :
*
*
* - [1,12]
*
- {"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", Dec"}
*
*
*
- dayOfWeek : one or more days within a week
*
Allowable values :
*
*
* - [0,7]
*
- {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}
*
* "0" and "7" both refer to Sunday
*
*
- year : a particular calendar year
*
Allowable values : a four-digit calendar year
*
*
*
*
*
* Each element supports values expressed in one of the following forms
*
*
* - Single Value. This constrains the attribute to only one of
* its possible values.
*
* Example: second = "10"
* Example: month = "Sep"
*
*
- Wild Card. "*" represents all allowable values for a given attribute.
*
* Example: second = "*"
* Example: dayOfWeek = "*"
*
* - List. This constrains the attribute to two or more allowable values
* or ranges, with a comma used as a separator character within the string.
* Each item in the list must be a single value or range. List items cannot
* be lists, wild cards, or increments. Duplicate values are ignored.
*
* Example: second = "10,20,30"
* Example: dayOfWeek = "Mon,Wed,Fri"
* Example: minute = "0-10,30,40"
*
* - Range. This constrains the attribute to an inclusive range of values,
* with a dash separating both ends of the range. Each side of the range
* must be a single attribute value. Members of a range cannot be lists,
* wild cards, ranges, or increments. If
x is larger than
* y in a range "x-y", the range is equivalent
* to "x-max, min-y", where max is the largest
* value of the corresponding attribute and min is the smallest.
* The range "x-x", where both range values are the same,
* evaluates to the single value x. The day of the week range
* "0-7" is equivalent to "*".
*
*
* Example: second = "1-10"
* Example: dayOfWeek = "Fri-Mon"
* Example: dayOfMonth = "27-3" (Equivalent to "27-Last , 1-3")
*
* - Increments. The forward slash constrains an attribute based on a
* starting point and an interval, and is used to specify every
N
* seconds, minutes, or hours within the minute, hour, or day, respectively.
* For the expression x/y, the attribute is constrained to
* every yth value within the set of allowable values beginning
* at time x. The x value is inclusive. The
* wild card character (*) can be used in the x
* position, and is equivalent to 0. The use of increments
* is only supported within the second, minute,
* and hour elements. For the second and
* minute elements, x and y must
* each be in the range [0,59]. For the hour
* element, x and y must each be in the range
* [0,23].
*
*
* Example: minute = "∗/5" (Every five minutes within the hour)
* This is equivalent to:
* minute = "0,5,10,15,20,25,30,35,40,45,50,55"
*
*
* Example: second = "30/10" (Every 10 seconds within the minute, starting at second 30)
* This is equivalent to: second = "30,40,50"
* Note that the set of matching increment values stops once the maximum
* value for that attribute is exceeded. It does not "roll over" past the
* boundary.
*
*
* Example : ( minute = "∗/14", hour="1,2")
* This is equivalent to: (minute = "0,14,28,42,56", hour = "1,2")
* (Every 14 minutes within the hour, for the hours of 1 and 2 a.m.)
*
*
*
* The following additional rules apply to the schedule specification elements:
*
* - If the
dayOfMonth element has a non-wildcard value and
* the dayOfWeek element has a non-wildcard value, then any
* day matching either the dayOfMonth value or the
* dayOfWeek value will be considered to apply.
* - Whitespace is ignored, except for string constants and numeric values.
*
- All string constants (e.g.,
"Sun", "Jan",
* "1st", etc.) are case insensitive.
*
*
* Schedule-based timer times are evaluated in the context of the default
* time zone associated with the container in which the application is
* executing. A schedule-based timer may optionally override this default
* and associate itself with a specific time zone. If the schedule-based
* timer is associated with a specific time zone, all its times are
* evaluated in the context of that time zone, regardless of the default
* time zone in which the container is executing.
*
* The timeout callback method to which the Schedule annotation is applied
* must have one of the following signatures, where <METHOD>
* designates the method name:
*
*
* void <METHOD>()
* void <METHOD>(Timer timer)
*
*
* A timeout callback method can have public, private, protected, or
* package level access. A timeout callback method must not be declared as
* final or static. Timeout callback methods must not throw application exceptions.
*
* @since EJB 3.1
*/
@Target(METHOD)
@Retention(RUNTIME)
public @interface Schedule {
/**
* Specifies one or more seconds with in a minute.
*/
String second() default "0";
/**
* Specifies one or more minutes with an hour.
*/
String minute() default "0";
/**
* Specifies one or more hours within a day.
*/
String hour() default "0";
/**
* Specifies one or more days within a month.
*/
String dayOfMonth() default "*";
/**
* Specifies one or more months within a year.
*/
String month() default "*";
/**
* Specifies one or more days within a week.
*/
String dayOfWeek() default "*";
/**
* Specifies one or more years.
*/
String year() default "*";
/**
* Specifies the time zone within which the schedule is evaluated.
* Time zones are specified as an ID string. The set of required
* time zone IDs is defined by the Zone Name(TZ) column of the public
* domain zoneinfo database.
*
* If a timezone is not specified, the schedule is evaluated in the context
* of the default timezone associated with the contianer in which the
* application is executing.
*/
String timezone() default "";
/**
* Specifies an information string that is associated with the timer
*/
String info() default "";
/**
* Specifies whether the timer that is created is persistent.
*/
boolean persistent() default true;
}