Google Git
Sign in
apache / tomee-site-pub / 476cf231b77b83a25b4407df84b6a5fd7c0d673a / . / examples-trunk / schedule-events / README.html
blob: dcdb75bafe3c4579f3da2861277e858865a53023 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Schedule CDI Events</title>
<meta name="description" content="Apache TomEE">
<meta name="author" content="Apache TomEE">
<meta name="google-translate-customization" content="f36a520c08f4c9-0a04e86a9c075ce9-g265f3196f697cf8f-10">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Expires" content="0">
<meta http-equiv="Cache-Control" content="no-store, no-cache, must-revalidate, max-age=0">
<!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<!-- Le styles -->
<link href="./../../resources/css/bootstrap.css" rel="stylesheet">
<link href="./../../resources/css/prettify.css" rel="stylesheet">
<!--link href="./../../resources/css/bootstrap-mods.css" rel="stylesheet"-->
<link href="./../../resources/css/main.css" rel="stylesheet">
<link href="./../../resources/font-awesome-4.6.3/css/font-awesome.min.css" rel="stylesheet">
<script type="text/javascript">
var t = encodeURIComponent(document.title.replace(/^\s+|\s+$/g,""));
var u = encodeURIComponent(""+document.URL);
function fbshare () {
window.open(
"http://www.facebook.com/sharer/sharer.php?u="+u,
'Share on Facebook',
'width=640,height=426');
};
function gpshare () {
window.open(
"https://plus.google.com/share?url="+u,
'Share on Google+',
'width=584,height=385');
};
function twshare () {
window.open(
"https://twitter.com/intent/tweet?url="+u+"&text="+t,
'Share on Twitter',
'width=800,height=526');
};
function pinshare () {
window.open("//www.pinterest.com/pin/create/button/?url="+u+"&media=http%3A%2F%2Ftomee.apache.org%2Fresources%2Fimages%2Ffeather-logo.png&description="+t,
'Share on Pinterest',
'width=800,height=526');
};
</script>
<!-- Le fav and touch icons -->
<link rel="shortcut icon" href="./../../favicon.ico">
<link rel="apple-touch-icon" href="./../../resources/images/apple-touch-icon.png">
<link rel="apple-touch-icon" sizes="72x72" href="./../../resources/images/apple-touch-icon-72x72.png">
<link rel="apple-touch-icon" sizes="114x114" href="./../../resources/images/apple-touch-icon-114x114.png">
<script src="./../../resources/js/prettify.js" type="text/javascript"></script>
<script src="./../../resources/js/jquery-latest.js"></script>
<script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
<script src="./../../resources/js/common.js"></script>
<script src="./../../resources/js/prettyprint.js"></script>
<!--script src="//assets.pinterest.com/js/pinit.js" type="text/javascript" async></script//-->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-2717626-1']);
_gaq.push(['_setDomainName', 'apache.org']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="topbar" data-dropdown="dropdown">
<div class="fill">
<div class="container">
<a class="brand" href="./../../index.html">Apache TomEE</a>
<ul class="nav">
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">
Apache
<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<!-- <li><a href="./../../misc/whoweare.html">Who we are?</a></li> -->
<!-- <li><a href="./../../misc/heritage.html">Heritage</a></li> -->
<li><a href="http://www.apache.org">Apache Home</a></li>
<!-- <li><a href="./../../misc/resources.html">Resources</a></li> -->
<li><a href="./../../misc/contact.html">Contact</a></li>
<li><a href="./../../misc/legal.html">Legal</a></li>
<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
<li class="divider"/>
<li><a href="http://www.apache.org/security">Security</a></li>
</ul>
</li>
<li><a href="./../../index.html">Home</a></li>
<li><a href="./../../downloads.html">Downloads</a></li>
<li><a href="./../../documentation.html">Documentation</a></li>
<li><a href="./../../examples-trunk/index.html">Examples</a></li>
<li><a href="./../../support.html">Support</a></li>
<li><a href="./../../contribute.html">Contribute</a></li>
<li><a href="./../../security/index.html">Security</a></li>
</ul>
<!-- Google CSE Search Box Begins -->
<FORM class="pull-right" id="searchbox_010475492895890475512:_t4iqjrgx90" action="http://www.google.com/cse">
<INPUT type="hidden" name="cx" value="010475492895890475512:_t4iqjrgx90">
<INPUT type="hidden" name="cof" value="FORID:0">
<INPUT size="18" width="130" style="width:130px" name="q" type="text" placeholder="Search">
</FORM>
<!--<SCRIPT type="text/javascript" src="http://www.google.com/coop/cse/brand?form=searchbox_010475492895890475512:_t4iqjrgx90"></SCRIPT>-->
<!-- Google CSE Search Box Ends -->
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="span8">
<small><a href="./../../index.html">Home</a>&nbsp;&raquo&nbsp;<a href="./../../examples-trunk/">Examples Trunk</a>&nbsp;&raquo&nbsp;<a href="./../../examples-trunk/schedule-events/">Schedule Events</a></small><br>
</div>
<div class="span8">
</div>
</div>
&nbsp;
<div class="page-header">
<h1>Schedule CDI Events
<div style="float: right; position: relative; bottom: -10px; ">
<div id="google_translate_element"></div><script type="text/javascript">
function googleTranslateElementInit() {
new google.translate.TranslateElement({pageLanguage: 'en', layout: google.translate.TranslateElement.InlineLayout.SIMPLE}, 'google_translate_element');
}
</script><script type="text/javascript" src="//translate.google.com/translate_a/element.js?cb=googleTranslateElementInit"></script>
<a onclick="javascript:gpshare()" class="gp-share sprite" title="Share on Google+">share [gp]</a>
<a onclick="javascript:fbshare()" class="fb-share sprite" title="Share on Facebook">share [fb]</a>
<a onclick="javascript:twshare()" class="tw-share sprite" title="Share on Twitter">share [tw]</a>
<a onclick="javascript:pinshare()" class="pin-share sprite" title="Share on Pinterest">share [pin]</a>
<a data-toggle="modal" href="#edit" class="edit-page" title="Contribute to this Page">contribute</a>
</div>
</h1>
</div>
<p>This example uses a nice CDI/EJB combination to schedule CDI Events. This is useful if you want CDI Events that fire regularly or at a specific time or calendar date.</p>
<p>Effectively this is a simple wrapper around the <code>BeanManager.fireEvent(Object,Annotations...)</code> method that adds <code>ScheduleExpression</code> into the mix.</p>
<h2>ScheduleExpression and @Timeout</h2>
<p>The logic here is simple, we effecitvely expose a method identical to <code>BeanManager.fireEvent(Object, Annotations...)</code> and wrap it as <code>scheduleEvent(ScheduleExpression, Object, Annotation...)</code></p>
<p>To do that we use the EJB <code>TimerService</code> (under the covers this is Quartz) and create an <code>@Timeout</code> method which will be run when the <code>ScheduleExpression</code> activates.</p>
<p>The <code>@Timeout</code> method, simply called <code>timeout</code>, takes the event and fires it.</p>
<pre><code>@Singleton
@Lock(LockType.READ)
public class Scheduler {
@Resource
private TimerService timerService;
@Resource
private BeanManager beanManager;
public void scheduleEvent(ScheduleExpression schedule, Object event, Annotation... qualifiers) {
timerService.createCalendarTimer(schedule, new TimerConfig(new EventConfig(event, qualifiers), false));
}
@Timeout
private void timeout(Timer timer) {
final EventConfig config = (EventConfig) timer.getInfo();
beanManager.fireEvent(config.getEvent(), config.getQualifiers());
}
// Doesn't actually need to be serializable, just has to implement it
private final class EventConfig implements Serializable {
private final Object event;
private final Annotation[] qualifiers;
private EventConfig(Object event, Annotation[] qualifiers) {
this.event = event;
this.qualifiers = qualifiers;
}
public Object getEvent() {
return event;
}
public Annotation[] getQualifiers() {
return qualifiers;
}
}
}
</code></pre>
<p>Then to use it, have <code>Scheduler</code> injected as an EJB and enjoy.</p>
<pre><code>public class SomeBean {
@EJB
private Scheduler scheduler;
public void doit() throws Exception {
// every five minutes
final ScheduleExpression schedule = new ScheduleExpression()
.hour("*")
.minute("*")
.second("*/5");
scheduler.scheduleEvent(schedule, new TestEvent("five"));
}
/**
* Event will fire every five minutes
*/
public void observe(@Observes TestEvent event) {
// process the event
}
}
</code></pre>
<h2>Test Case</h2>
<p>A working test case for the above would be as follows:</p>
<pre><code>import org.junit.Assert;
import org.junit.Before;
import org.junit.Test;
import javax.ejb.AccessTimeout;
import javax.ejb.EJB;
import javax.ejb.ScheduleExpression;
import javax.ejb.embeddable.EJBContainer;
import javax.enterprise.event.Observes;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
/**
* @version $Revision$ $Date$
*/
public class SchedulerTest {
public static final CountDownLatch events = new CountDownLatch(3);
@EJB
private Scheduler scheduler;
@Test
public void test() throws Exception {
final ScheduleExpression schedule = new ScheduleExpression()
.hour("*")
.minute("*")
.second("*/5");
scheduler.scheduleEvent(schedule, new TestEvent("five"));
Assert.assertTrue(events.await(1, TimeUnit.MINUTES));
}
@AccessTimeout(value = 1, unit = TimeUnit.MINUTES)
public void observe(@Observes TestEvent event) {
if ("five".equals(event.getMessage())) {
events.countDown();
}
}
public static class TestEvent {
private final String message;
public TestEvent(String message) {
this.message = message;
}
public String getMessage() {
return message;
}
}
@Before
public void setup() throws Exception {
EJBContainer.createEJBContainer().getContext().bind("inject", this);
}
}
</code></pre>
<h2>You must know</h2>
<ul>
<li>CDI Events are not multi-treaded</li>
</ul>
<p>If there are 10 observers and each of them take 7 minutes to execute, then the total execution time for the one event is 70 minutes. It would do you absolutely no good to schedule that event to fire more frequently than 70 minutes.</p>
<p>What would happen if you did? Depends on the <code>@Singleton</code> <code>@Lock</code> policy</p>
<ul>
<li><code>@Lock(WRITE)</code> is the default. In this mode the <code>timeout</code> method would essentially be locked until the previous invocation completes. Having it fire every 5 minutes even though you can only process one every 70 minutes would eventually cause all the pooled timer threads to be waiting on your Singleton.</li>
<li><code>@Lock(READ)</code> allows for parallel execution of the <code>timeout</code> method. Events will fire in parallel for a while. However since they actually are taking 70 minutes each, within an hour or so we'll run out of threads in the timer pool just like above.</li>
</ul>
<p>The elegant solution is to use <code>@Lock(WRITE)</code> then specify some short timeout like <code>@AccessTimeout(value = 1, unit = TimeUnit.MINUTES)</code> on the <code>timeout</code> method. When the next 5 minute invocation is triggered, it will wait up until 1 minute to get access to the Singleton before giving up. This will keep your timer pool from filling up with backed up jobs -- the "overflow" is simply discarded.</p>
<div class="page-header">&nbsp;</div>
<h4>APIs Used</h4>
<ul><li><a href="http://docs.oracle.com/javaee/6/api/javax/annotation/Resource.html">javax.annotation.Resource</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/AccessTimeout.html">javax.ejb.AccessTimeout</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/EJB.html">javax.ejb.EJB</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/Lock.html">javax.ejb.Lock</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/LockType.html">javax.ejb.LockType</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/ScheduleExpression.html">javax.ejb.ScheduleExpression</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/Singleton.html">javax.ejb.Singleton</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/Timeout.html">javax.ejb.Timeout</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/Timer.html">javax.ejb.Timer</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/TimerConfig.html">javax.ejb.TimerConfig</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/TimerService.html">javax.ejb.TimerService</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/ejb/embeddable/EJBContainer.html">javax.ejb.embeddable.EJBContainer</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/enterprise/event/Observes.html">javax.enterprise.event.Observes</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/enterprise/inject/spi/BeanManager.html">javax.enterprise.inject.spi.BeanManager</a></li>
</ul>
<h3>Source</h3>
<ul>
<li>Apache <a href="http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/schedule-events">schedule-events</a></li>
<li>Github <a href="https://github.com/apache/tomee/tree/trunk/examples/schedule-events">schedule-events</a></li>
</ul>
<pre>
svn co http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/schedule-events
cd schedule-events
mvn clean install
</pre>
<div id="edit" class="modal hide fade in" style="display: none; ">
<div class="modal-header">
<a class="close" data-dismiss="modal">x</a>
<h3>Thank you for contributing to the documentation!</h3>
</div>
<div class="modal-body">
<h4>Any help with the documentation is greatly appreciated.</h4>
<p>All edits are reviewed before going live, so feel free to do much more than fix typos or links. If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it. Don't be surprised if we like it so much we ask you for help with other pages :)</p>
<small>NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.</small>
<!--[if gt IE 6]>
<h4>Internet Explorer Users</h4>
<p>If you are not an Apache committer, click the Yes link and enter a <i>anonymous</i> for the username and leave the password empty</p>
<![endif]-->
</div>
<div class="modal-footer">
Do you have an Apache ID?
<a href="javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))" class="btn">Yes</a>
<a href="javascript:void(location.href='https://anonymous:@cms.apache.org/redirect?uri='+escape(location.href))" class="btn">No</a>
</div>
</div>
<script src="./../../resources/js/bootstrap-modal.js"></script>
<footer>
<p>Copyright &copy; 1999-2016 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation.
All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
</footer>
</div> <!-- /container -->
<!-- Javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="./../../resources/js/bootstrap-dropdown.js"></script>
</body>
</html>