<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">

<div>
        <table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
                <tbody>
                        <tr>

                                <td>

                                        <table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
                                                <tbody>
                                                        <tr>
                                                                <td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
                                                                        <h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
                                                                        <!-- To have a header image/logo replace the name below with your img tag -->
                                                                        <!-- Email clients will render the images when the message is read so any image -->
                                                                        <!-- must be made available on a public server, so that all recipients can load the image. -->
                                                                        <a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
                                                                </td>

                                                        </tr>
                                                        <tr>
                                                                <td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px;  -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
    EJB3.1 in JBoss AS 6.0.0.M4
</h3>
<span style="margin-bottom: 10px;">
    modified by <a href="http://community.jboss.org/people/wolfc">Carlo de Wolf</a> in <i>EJB 3.0</i> - <a href="http://community.jboss.org/docs/DOC-15643">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">

<div class="jive-rendered-content"><h5><span>Overview</span></h5><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>JBoss AS 6.0.0.M4 introduces support for EJB3.1 Timer Service and EJB3.1 Asynchronous invocations.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h5><span>What to download and how to use</span></h5><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>You can download JBoss AS 6.0.0.M4 from <a class="jive-link-external-small" href="http://www.jboss.org/jbossas/downloads.html">here</a>. After downloading the AS, start and stop it once to make sure it boots without any issues.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>In the next steps we will see a simple EJB3.1 timerservice example (mainly the calendar expression support)</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h5><span>EJB3.1 Timer Service:</span></h5><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>Note that the examples shown below are just for the sake of illustrating the usage of timerservice API and as such don't hold much meaning.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>Let's deploy a very simple stateless session bean which exposes a remote business interface view</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><pre class="jive-pre"><code class="jive-code jive-java"><font color="navy"><b>package</b></font> org.jboss.ejb3.timerservice.example;
&#160;
<font color="navy"><b>public</b></font> <font color="navy"><b>interface</b></font> SchedulerOps
<font color="navy">{</font>
&#160;
&#160;&#160; <font color="darkgreen">/**
&#160;&#160;&#160; * Schedules a timer for the passed schedule&#160;&#160;&#160; *&#160;&#160; 
&#160;&#160;&#160; * @param schedule The calendar expression based schedule
&#160;&#160;&#160; * 
&#160;&#160;&#160; * 
&#160;&#160;&#160; */</font>
&#160;&#160; <font color="navy"><b>void</b></font> scheduleTask(ScheduleExpression schedule);
&#160;&#160; 
&#160;&#160; 
<font color="navy">}</font>
&#160;
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><pre class="jive-pre"><code class="jive-code jive-java"><font color="navy"><b>package</b></font> org.jboss.ejb3.timerservice.example;
&#160;
<font color="navy"><b>import</b></font> java.util.Date;
&#160;
<font color="navy"><b>import</b></font> javax.annotation.Resource;
<font color="navy"><b>import</b></font> javax.ejb.Remote;
<font color="navy"><b>import</b></font> javax.ejb.ScheduleExpression;
<font color="navy"><b>import</b></font> javax.ejb.Stateless;
<font color="navy"><b>import</b></font> javax.ejb.Timeout;
<font color="navy"><b>import</b></font> javax.ejb.Timer;
<font color="navy"><b>import</b></font> javax.ejb.TimerConfig;
<font color="navy"><b>import</b></font> javax.ejb.TimerService;
&#160;
<font color="navy"><b>import</b></font> org.jboss.ejb3.annotation.RemoteBinding;
&#160;
@Stateless
@Remote (SchedulerOps.class)
@RemoteBinding (jndiBinding = <font color="red">"myscheduler"</font>)
<font color="navy"><b>public</b></font> <font color="navy"><b>class</b></font> Scheduler <font color="navy"><b>implements</b></font> SchedulerOps
<font color="navy">{</font>
&#160;
&#160;&#160; @Resource
&#160;&#160; <font color="navy"><b>private</b></font> TimerService timerService;
&#160;&#160; 
&#160;&#160; @Override
&#160;&#160; <font color="navy"><b>public</b></font> <font color="navy"><b>void</b></font> scheduleTask(ScheduleExpression schedule)
&#160;&#160; <font color="navy">{</font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// Use the injected timerservice to create a timer instance,</font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// for the passed schedule</font>
&#160;&#160;&#160;&#160;&#160; Timer timer = this.timerService.createCalendarTimer(calendarSchedule);
&#160;&#160;&#160;&#160;&#160; 
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// that's it, we are done. When the scheduled timeout occurs, the </font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// timeout callback method on this bean will be invoked by the server</font>
&#160;&#160; <font color="navy">}</font>
&#160;&#160; 
&#160;&#160; <font color="darkgreen">/**
&#160;&#160;&#160; * This timeout callback method will be invoked when the timer schedule
&#160;&#160;&#160; * expires
&#160;&#160;&#160; * 
&#160;&#160;&#160; * @param timer The {@link Timer} for which the timeout occurred
&#160;&#160;&#160; */</font>
&#160;&#160; @Timeout
&#160;&#160; <font color="navy"><b>private</b></font> <font color="navy"><b>void</b></font> timeout(Timer timer)
&#160;&#160; <font color="navy">{</font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// Let's just print out to System.out</font>
&#160;&#160;&#160;&#160;&#160; System.out.println(<font color="red">"Timeout method invoked at "</font> + <font color="navy"><b>new</b></font> Date() + <font color="red">" for bean "</font> + this.getClass().getSimpleName());
&#160;&#160; <font color="navy">}</font>
&#160;
<font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>In the example above, we have a SchedulerOps interface which is exposed as the remote view for the Scheduler Stateless session bean. The SchedulerOps interface allows scheduling timers based on a javax.ejb.ScheduleExpression. ScheduleExpression is used to express calendar based timeout expressions. Later in this wiki, we'll see how we create a calendar based schedule.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>In order to create and operate on timers, we are injecting the TimerService into the bean, through the use of @javax.annotation.Resource annotation:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><pre class="jive-pre"><code class="jive-code jive-java">
&#160;&#160; @Resource
&#160;&#160; <font color="navy"><b>private</b></font> TimerService timerService;
&#160;
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>The important scheduleTask method looks like this:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><pre class="jive-pre"><code class="jive-code jive-java">@Override
&#160;&#160; <font color="navy"><b>public</b></font> <font color="navy"><b>void</b></font> scheduleTask(ScheduleExpression schedule)
&#160;&#160; <font color="navy">{</font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// Use the injected timerservice to create a timer instance,</font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// for the passed schedule</font>
&#160;&#160;&#160;&#160;&#160; Timer timer = this.timerService.createCalendarTimer(calendarSchedule);
&#160;&#160;&#160;&#160;&#160; 
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// that's it, we are done. When the scheduled timeout occurs, the </font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// timeout callback method on this bean will be invoked by the server</font>
&#160;&#160; <font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>We use the injected timerservice to create a calendar timer. A calendar timer is a Timer which is created based on a calendar schedule expression.</p><p>Please refer to the EJB3.1 spec for more details on ScheduleExpression.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>For example, if we want to schedule a timer to fire every Friday at 5:45 in the morning, then we can create the following ScheduleExpression:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><pre class="jive-pre"><code class="jive-code jive-java">&#160;&#160;&#160;&#160;&#160;ScheduleExpression everyFridayFiveFortyFive = <font color="navy"><b>new</b></font> ScheduleExpression();
&#160;&#160;&#160;&#160;&#160;everyFridayFiveFortyFive.dayOfWeek(<font color="red">"Fri"</font>).hour(5).minute(45);
&#160;&#160;&#160;&#160;&#160;
</code></pre><p>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>Now that we created a timer in our bean, the timer will be started after the bean's method completes(remember, timers are transactional, so the timer start waits for the transaction to complete). When the schedulded timeout occur, the server will invoke the timeout callback method on the bean. In our example, we have annotated our timeout() method as the timeout callback method (note the @Timeout annotation):</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><pre class="jive-pre"><code class="jive-code jive-java">&#160;&#160; <font color="darkgreen">/**
&#160;&#160;&#160; * This timeout callback method will be invoked when the timer schedule
&#160;&#160;&#160; * expires
&#160;&#160;&#160; * 
&#160;&#160;&#160; * @param timer The {@link Timer} for which the timeout occurred
&#160;&#160;&#160; */</font>
&#160;&#160; @Timeout
&#160;&#160; <font color="navy"><b>private</b></font> <font color="navy"><b>void</b></font> timeout(Timer timer)
&#160;&#160; <font color="navy">{</font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// Let's just print out to System.out</font>
&#160;&#160;&#160;&#160;&#160; System.out.println(<font color="red">"Timeout method invoked at "</font> + <font color="navy"><b>new</b></font> Date() + <font color="red">" for bean "</font> + this.getClass().getSimpleName());
&#160;&#160; <font color="navy">}</font>
&#160;
&#160;
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>Here's how the client code is going to schedule the timer through the bean:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><pre class="jive-pre"><code class="jive-code jive-java"><font color="navy"><b>package</b></font> org.jboss.ejb3.timerservice.example.client;
 
<font color="navy"><b>import</b></font> javax.naming.Context;
<font color="navy"><b>import</b></font> javax.naming.InitialContext;
<font color="navy"><b>import</b></font> javax.naming.NamingException;
<font color="navy"><b>import</b></font> org.jboss.ejb3.timerservice.example.*;
 
<font color="navy"><b>public</b></font> <font color="navy"><b>class</b></font> Client
<font color="navy">{</font>
&#160;&#160; <font color="navy"><b>public</b></font> <font color="navy"><b>static</b></font> <font color="navy"><b>void</b></font> main(String[] args) <font color="navy"><b>throws</b></font> Exception
&#160;&#160; <font color="navy">{</font>
&#160;&#160;&#160;&#160;&#160;
&#160;&#160;&#160;&#160;&#160; Context ctx = <font color="navy"><b>new</b></font> InitialContext();
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// lookup the bean</font>
&#160;&#160;&#160;&#160;&#160; SchedulerOps scheduler = (SchedulerOps) ctx.lookup(<font color="red">"myscheduler"</font>);
&#160;&#160;&#160;&#160;&#160; 
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// create a schedule</font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// Every Tue at 2 and 4 in the afternoon during the month of August</font>
&#160;&#160;&#160;&#160;&#160; ScheduleExpression everyTueAtTwoAndFourInNoonDuringAugust = <font color="navy"><b>new</b></font> ScheduleExpression();
&#160;&#160;&#160;&#160;&#160; everyTueAtTwoAndFourInNoonDuringAugust.dayOfMonth(<font color="red">"Tue"</font>).hour(<font color="red">"14,16"</font>).month(<font color="red">"Aug"</font>);
&#160;&#160;&#160;&#160;&#160; 
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// schedule our task</font>
&#160;&#160;&#160;&#160;&#160; scheduler.scheduleTask(everyTueAtTwoAndFourInNoonDuringAugust);
&#160;&#160;&#160;&#160;&#160; 
&#160;&#160; <font color="navy">}</font>
 
<font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>In the client code, we first lookup the SchedulerOps remote business view of the bean. Then we create a calendar schedule which is expected to expire every Tuesday at 2 and 4 in the noon during the month of August. We then invoke the scheduleTask method on the bean. That's it! When the scheduled timeout occurs, you will see the timeout() method on the bean being called.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h5><span>Auto timers</span></h5><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>In the above example, we used a remote business view and a method on that interface just to create a timer. That can be avoided if we use auto timers. Auto timers are created automatically by the EJB container when a bean is deployed. The container looks for the presence of&#160; @javax.ejb.Schedule or @javax.ejb.Schedules (or their xml equivalents) to decide whether auto timers are to be created.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> &#160;</p><p>Here's an example of the same (using annotations):</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><pre class="jive-pre"><code class="jive-code jive-java"><font color="navy"><b>package</b></font> org.jboss.ejb3.timerservice.example;
&#160;
<font color="navy"><b>import</b></font> javax.ejb.Schedule;
<font color="navy"><b>import</b></font> javax.ejb.ScheduleExpression;
<font color="navy"><b>import</b></font> javax.ejb.Stateless;
<font color="navy"><b>import</b></font> javax.ejb.Timeout;
<font color="navy"><b>import</b></font> javax.ejb.Timer;
<font color="navy"><b>import</b></font> javax.ejb.TimerConfig;
<font color="navy"><b>import</b></font> javax.ejb.TimerService;
<font color="navy"><b>import</b></font> javax.naming.Context;
<font color="navy"><b>import</b></font> javax.naming.InitialContext;
&#160;
@Stateless
<font color="navy"><b>public</b></font> <font color="navy"><b>class</b></font> AutoTimerBean 
<font color="navy">{</font>
&#160;
&#160;&#160; <font color="darkgreen">/**
&#160;&#160;&#160; * This method will be invoked every day at 5:00:00 in the morning
&#160;&#160;&#160; * @param timer The timer instance
&#160;&#160;&#160; */</font>
&#160;&#160; @Schedule (hour = <font color="red">"5"</font>)
&#160;&#160; <font color="navy"><b>private</b></font> <font color="navy"><b>void</b></font> executeEveryDayAtFive(Timer timer)
&#160;&#160; <font color="navy">{</font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// do some task here. </font>
&#160;&#160;&#160;&#160;&#160; System.out.println(<font color="red">"Auto-timer method invoked at "</font> + <font color="navy"><b>new</b></font> Date() + <font color="red">" for bean "</font> + this.getClass().getSimpleName());
&#160;&#160;&#160;&#160;&#160; 
&#160;&#160; <font color="navy">}</font>
&#160;
<font color="navy">}</font>
&#160;
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>As you can see we have a Stateless (no-interface view) bean which has the executeEveryDayAtFive method. This method is annotated with @Schedule. The server will automatically create the timer when the bean is deployed. The schedule for the timer is passed through the annotation's attribute values. The method on which the @Schedule is used, will be considered the timeout callback method for that auto timer and will be invoked when the timeout occurs.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>The example above creates an auto timer which is expected to fire every day at 5 in the morning.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>Let's quickly see the use of @javax.ejb.Schedules (note the 's' in the end of that annotation name). That allows you to create multiple auto timers with different schedules for the same timeout callback method.</p><pre class="jive-pre"><code class="jive-code jive-java">&#160;&#160; <font color="darkgreen">/**
&#160;&#160;&#160; * Multiple auto timers with different schedules will be created for this
&#160;&#160;&#160; * timeout callback method
&#160;&#160;&#160; * @param timer The timer instance
&#160;&#160;&#160; */</font>
&#160;&#160; @Schedules (
&#160;&#160; <font color="navy">{</font>
&#160;&#160;&#160;&#160;&#160; @Schedule(hour=<font color="red">"8"</font>, minute=<font color="red">"15"</font>),
&#160;&#160;&#160;&#160;&#160; @Schedule(dayOfMonth=<font color="red">"Mon"</font>, info=<font color="red">"test"</font>)
&#160;&#160; <font color="navy">}</font>
&#160;&#160; )
&#160;&#160; <font color="navy"><b>private</b></font> <font color="navy"><b>void</b></font> multiAutoTimeoutMethod(Timer timer)
&#160;&#160; <font color="navy">{</font>
&#160;&#160;&#160;&#160;&#160; <font color="darkgreen">// do some task here. for now, let's just print out to System.out</font>
&#160;&#160;&#160;&#160;&#160; System.out.println(<font color="red">"Multi auto-timeout method invoked at "</font> + <font color="navy"><b>new</b></font> Date() + <font color="red">" for timer "</font> + timer);
&#160;&#160;&#160;&#160;&#160; 
&#160;&#160; <font color="navy">}</font>
</code></pre><p>In this example above, we have used @Schedules to create 2 auto timers, each with a different schedule. Note that you can even pass an optional "info" to the created timers. That info will be available through the javax.ejb.Timer in the timeout callback method. In this example, multiAutoTimeoutMethod method will be invoked when either of the scheduled timeout occurs.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h5><span>What next?</span></h5><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>Those were just some examples on EJB3.1 timerservice to get you started. Download <a class="jive-link-external-small" href="http://www.jboss.org/jbossas/downloads.html">JBossAS 6.0.0.M4</a> and try out your own application and/or examples and let us know how it goes. If you run into any issues, feel free to start a discussion in our <a class="jive-link-external-small" href="http://community.jboss.org/community/ejb3">EJB3 user forum</a> or ping us on <a class="jive-link-external-small" href="http://www.jboss.org/ejb3/chat.html">IRC</a>. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> &#160;</p><h5><span>I have some tutorial for singleton beans, Can I contribute?</span></h5><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>Similar to our other EJB3 tutorials, we are going to include a tutorial for EJB3.1 Timer Service. Infact, the example that is posted here in the wiki, can perhaps be just added as a tutorial in SVN. If anyone of you wants to contribute a different tutorial and a chapter in our guide, then feel free to let us know - either through the forums or IRC.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> &#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p></div>

<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
    <p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-15643">going to Community</a></p>

        <p style="margin: 0;">Create a new document in EJB 3.0 at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2029">Community</a></p>
</div></td>
                        </tr>
                    </tbody>
                </table>


                </td>
            </tr>
        </tbody>
    </table>

</div>

</body>
</html>