jakarta.ejb.Schedule Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jakarta.ejb-api Show documentation
Jakarta Enterprise Beans API
There is a newer version: 4.0.1
/*
 * 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 jakarta.ejb;

import java.lang.annotation.Repeatable;
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)
@Repeatable(Schedules.class)
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;
}