blob: 9b751a3e8bee1dff8512cca98847d49d3fb9355c [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<title>Schedule</title>
<link rel="stylesheet" type="text/css" href="../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../script.js"></script>
<link rel="shortcut icon" href="/img/jakarta-favicon.ico">
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="Schedule";
}
}
catch(err) {
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../index-all.html">Index</a></li>
<li><a href="../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../jakarta/ejb/RemoveException.html" title="class in jakarta.ejb"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../jakarta/ejb/ScheduleExpression.html" title="class in jakarta.ejb"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../index.html?jakarta/ejb/Schedule.html" target="_top">Frames</a></li>
<li><a href="Schedule.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Required&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">jakarta.ejb</div>
<h2 title="Annotation Type Schedule" class="title">Annotation Type Schedule</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>@Target(value=METHOD)
@Retention(value=RUNTIME)
@Repeatable(value=<a href="../../jakarta/ejb/Schedules.html" title="annotation in jakarta.ejb">Schedules.class</a>)
public @interface <span class="memberNameLabel">Schedule</span></pre>
<div class="block">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.
<p>
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.
<p>
There are seven elements that constitute a schedule specification which are listed below. In addition, the
<code>timezone</code> element may be used to specify a non-default time zone in whose context the schedule
specification is to be evaluated; the <code>persistent</code> element may be used to specify a non-persistent timer,
and the <code>info</code> element may be used to specify additional information that may be retrieved when the timer
callback occurs.
<p>
The elements that specify the calendar-based schedule itself are as follows:
<ul>
<li>second : one or more seconds within a minute
<p>
Allowable values: [0,59]
<li>minute : one or more minutes within an hour
<p>
Allowable values : [0,59]
<li>hour : one or more hours within a day
<p>
Allowable values : [0,23]
<li>dayOfMonth : one or more days within a month
<p>
Allowable values:
<ul>
<li>[1,31]
<li>[-7, -1]
<li>"Last"
<li>{"1st", "2nd", "3rd", "4th", "5th", "Last"} {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}
</ul>
<p>
"Last" means the last day of the month
<p>
-x (where x is in the range [-7, -1]) means x day(s) before the last day of the month
<p>
"1st","2nd", etc. applied to a day of the week identifies a single occurrence of that day within the month.
<li>month : one or more months within a year
<p>
Allowable values :
<ul>
<li>[1,12]
<li>{"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", Dec"}
</ul>
<li>dayOfWeek : one or more days within a week
<p>
Allowable values :
<ul>
<li>[0,7]
<li>{"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}
</ul>
<p>
"0" and "7" both refer to Sunday
<li>year : a particular calendar year
<p>
Allowable values : a four-digit calendar year
<p>
</ul>
<p>
Each element supports values expressed in one of the following forms
<ul>
<li>Single Value. This constrains the attribute to only one of its possible values.
<pre>
Example: second = "10"
Example: month = "Sep"
</pre>
<li>Wild Card. "*" represents all allowable values for a given attribute.
<pre>
Example: second = "*"
Example: dayOfWeek = "*"
</pre>
<li>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.
<pre>
Example: second = "10,20,30"
Example: dayOfWeek = "Mon,Wed,Fri"
Example: minute = "0-10,30,40"
</pre>
<li>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 <code>x</code> is larger than <code>y</code> in a range <code>"x-y"</code>, the range is
equivalent to <code>"x-max, min-y"</code>, where <code>max</code> is the largest value of the corresponding attribute
and <code>min</code> is the smallest. The range <code>"x-x"</code>, where both range values are the same, evaluates
to the single value <code>x</code>. The day of the week range <code>"0-7"</code> is equivalent to <code>"*"</code>.
<pre>
Example: second = "1-10"
Example: dayOfWeek = "Fri-Mon"
Example: dayOfMonth = "27-3" (Equivalent to "27-Last , 1-3")
</pre>
<li>Increments. The forward slash constrains an attribute based on a starting point and an interval, and is used to
specify every <code>N</code> seconds, minutes, or hours within the minute, hour, or day, respectively. For the
expression <code>x/y</code>, the attribute is constrained to every <code>y</code>th value within the set of allowable
values beginning at time <code>x</code>. The <code>x</code> value is inclusive. The wild card character
(<code>*</code>) can be used in the <code>x</code> position, and is equivalent to <code>0</code>. The use of
increments is only supported within the <code>second</code>, <code>minute</code>, and <code>hour</code> elements. For
the <code>second</code> and <code>minute</code> elements, <code>x</code> and <code>y</code> must each be in the range
<code>[0,59]</code>. For the <code>hour</code> element, <code>x</code> and <code>y</code> must each be in the range
<code>[0,23]</code>.
<pre>
Example: minute = "&#8727;/5" (Every five minutes within the hour)
</pre>
This is equivalent to: <code>minute = "0,5,10,15,20,25,30,35,40,45,50,55"</code>
<pre>
Example: second = "30/10" (Every 10 seconds within the minute, starting at second 30)
</pre>
This is equivalent to: <code>second = "30,40,50"</code>
<p>
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.
<pre>
Example : ( minute = "&#8727;/14", hour="1,2")
</pre>
<p>
This is equivalent to: <code>(minute = "0,14,28,42,56", hour = "1,2")</code> (Every 14 minutes within the hour, for
the hours of 1 and 2 a.m.)
</ul>
<p>
The following additional rules apply to the schedule specification elements:
<ul>
<li>If the <code>dayOfMonth</code> element has a non-wildcard value and the <code>dayOfWeek</code> element has a
non-wildcard value, then any day matching either the <code>dayOfMonth</code> value or the <code>dayOfWeek</code>
value will be considered to apply.
<li>Whitespace is ignored, except for string constants and numeric values.
<li>All string constants (e.g., <code>"Sun"</code>, <code>"Jan"</code>, <code>"1st"</code>, etc.) are case
insensitive.
</ul>
<p>
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.
<p>
The timeout callback method to which the <code>Schedule</code> annotation is applied must have one of the following
signatures, where <code>&lt;METHOD&gt;</code> designates the method name:
<pre>
void &#060;METHOD&#062;()
void &#060;METHOD&#062;(Timer timer)
</pre>
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.</div>
<dl>
<dt><span class="simpleTagLabel">Since:</span></dt>
<dd>EJB 3.1</dd>
<dt><span class="simpleTagLabel">Examples (en):</span></dt>
<dd><a href="../../../../../tomee-9.0/examples/schedule-methods.html">schedule-methods</a>, <a href="../../../../../tomee-9.0/examples/schedule-methods-meta.html">schedule-methods-meta</a>, <a href="../../../../../tomee-9.0/examples/rest-example.html">rest-example</a>, <a href="../../../../../tomee-9.0/examples/cdi-events.html">cdi-events</a></dd>
<dt><span class="simpleTagLabel">Examples (pt):</span></dt>
<dd><a href="../../../../../tomee-9.0/pt/examples/cdi-events.html">cdi-events</a></dd>
</dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.optional.element.summary">
<!-- -->
</a>
<h3>Optional Element Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Optional Element Summary table, listing optional elements, and an explanation">
<caption><span>Optional Elements</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Optional Element and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#dayOfMonth--">dayOfMonth</a></span></code>
<div class="block">Specifies one or more days within a month.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#dayOfWeek--">dayOfWeek</a></span></code>
<div class="block">Specifies one or more days within a week.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#hour--">hour</a></span></code>
<div class="block">Specifies one or more hours within a day.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#info--">info</a></span></code>
<div class="block">Specifies an information string that is associated with the timer</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#minute--">minute</a></span></code>
<div class="block">Specifies one or more minutes with an hour.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#month--">month</a></span></code>
<div class="block">Specifies one or more months within a year.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#persistent--">persistent</a></span></code>
<div class="block">Specifies whether the timer that is created is persistent.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#second--">second</a></span></code>
<div class="block">Specifies one or more seconds with in a minute.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#timezone--">timezone</a></span></code>
<div class="block">Specifies the time zone within which the schedule is evaluated.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/ejb/Schedule.html#year--">year</a></span></code>
<div class="block">Specifies one or more years.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.element.detail">
<!-- -->
</a>
<h3>Element Detail</h3>
<a name="second--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>second</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;second</pre>
<div class="block">Specifies one or more seconds with in a minute.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a <code>String</code> object.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>"0"</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="minute--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>minute</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;minute</pre>
<div class="block">Specifies one or more minutes with an hour.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a <code>String</code> object.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>"0"</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="hour--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>hour</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;hour</pre>
<div class="block">Specifies one or more hours within a day.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a <code>String</code> object.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>"0"</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="dayOfMonth--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>dayOfMonth</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;dayOfMonth</pre>
<div class="block">Specifies one or more days within a month.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a <code>String</code> object.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>"*"</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="month--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>month</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;month</pre>
<div class="block">Specifies one or more months within a year.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a <code>String</code> object.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>"*"</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="dayOfWeek--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>dayOfWeek</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;dayOfWeek</pre>
<div class="block">Specifies one or more days within a week.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a <code>String</code> object.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>"*"</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="year--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>year</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;year</pre>
<div class="block">Specifies one or more years.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a <code>String</code> object.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>"*"</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="timezone--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>timezone</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;timezone</pre>
<div class="block">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.
<p>
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.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a <code>String</code> object.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="info--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>info</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;info</pre>
<div class="block">Specifies an information string that is associated with the timer</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a <code>String</code> object.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="persistent--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>persistent</h4>
<pre>public abstract&nbsp;boolean&nbsp;persistent</pre>
<div class="block">Specifies whether the timer that is created is persistent.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a boolean.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>true</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../index-all.html">Index</a></li>
<li><a href="../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../jakarta/ejb/RemoveException.html" title="class in jakarta.ejb"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../jakarta/ejb/ScheduleExpression.html" title="class in jakarta.ejb"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../index.html?jakarta/ejb/Schedule.html" target="_top">Frames</a></li>
<li><a href="Schedule.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Required&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>