| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| |
| <meta charset="UTF-8"> |
| <title>Singleton Example</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="page-header"> |
| <small><a href="./index.html">Home</a></small><br> |
| <h1>Singleton Example |
| |
| <div style="float: right; position: relative; bottom: -10px; "> |
| <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> |
| |
| <h1>Overview</h1> |
| |
| <p>As the name implies a javax.ejb.Singleton is a session bean with a guarantee that there is at most one instance in the application.</p> |
| |
| <p>What it gives that is completely missing in EJB 3.0 and prior versions is the ability to have an EJB that is notified when the application starts and notified when the application stops. So you can do all sorts of things that you previously could only do with a load-on-startup servlet. It also gives you a place to hold data that pertains to the entire application and all users using it, without the need for a static. Additionally, Singleton beans can be invoked by several threads at one time similar to a Servlet.</p> |
| |
| <p>See the Singleton Beans Javadocs linked at the bottom for a full description.</p> |
| |
| <h1>The Code</h1> |
| |
| <p>PropertyRegistryBean</p> |
| |
| <p>Here we see a bean that uses the Bean-Managed Concurrency option as well as the @Startup annotation which causes the bean to be instantiated by the container when the application starts. Singleton beans with @ConcurrencyManagement(BEAN) are responsible for their own thread-safety. The bean shown is a simple properties "registry" and provides a place where options could be set and retrieved by all beans in the application.</p> |
| |
| <pre><code> |
| import static javax.ejb.ConcurrencyManagementType.BEAN; |
| import javax.ejb.Singleton; |
| import javax.ejb.ConcurrencyManagement; |
| import javax.ejb.Startup; |
| import javax.annotation.PostConstruct; |
| import javax.annotation.PreDestroy; |
| import java.util.Properties; |
| @Singleton |
| @ConcurrencyManagement(BEAN) |
| @Startup |
| public class PropertyRegistryBean implements PropertyRegistry { |
| // Note the java.util.Properties object is a thread-safe |
| // collections that uses synchronization. If it didn't |
| // you would have to use some form of synchronization |
| // to ensure the PropertyRegistryBean is thread-safe. |
| private final Properties properties = new Properties(); |
| |
| // The @Startup method ensures that this method is |
| // called when the application starts up. |
| @PostConstruct |
| public void applicationStartup() { |
| properties.putAll(System.getProperties()); |
| } |
| @PreDestroy |
| public void applicationShutdown() { |
| properties.clear(); |
| } |
| public String getProperty(String key) { |
| return properties.getProperty(key); |
| } |
| |
| public String setProperty(String key, String value) { |
| return (String) properties.setProperty(key, value); |
| } |
| |
| public String removeProperty(String key) { |
| return (String) properties.remove(key); |
| } |
| </div> |
| </code></pre> |
| |
| <p>ComponentRegistryBean</p> |
| |
| <p>Here we see a bean that uses the Container-Managed Concurrency option, the default. With @ConcurrencyManagement(CONTAINER) the container controls whether multi-threaded access should be allowed to the bean (@Lock(READ)) or if single-threaded access should be enforced (@Lock(WRITE)).</p> |
| |
| <pre><code> |
| import static javax.ejb.LockType.READ; |
| import static javax.ejb.LockType.WRITE; |
| import javax.ejb.Lock; |
| import javax.ejb.Singleton; |
| import java.util.HashMap; |
| import java.util.Map; |
| import java.util.Collection; |
| import java.util.ArrayList; |
| |
| @Singleton |
| @Lock(READ) |
| public class ComponentRegistryBean implements ComponentRegistry { |
| |
| private final Map<Class, Object> components = new HashMap<Class, Object>(); |
| |
| public <T> T getComponent(Class<T> type) { |
| return (T) components.get(type); |
| } |
| |
| public Collection<?> getComponents() { |
| return new ArrayList(components.values()); |
| } |
| |
| @Lock(WRITE) |
| public <T> T setComponent(Class<T> type, T value) { |
| return (T) components.put(type, value); |
| } |
| |
| @Lock(WRITE) |
| public <T> T removeComponent(Class<T> type) { |
| return (T) components.remove(type); |
| } |
| </div> |
| </code></pre> |
| |
| <p>Unless specified explicitly on the bean class or a method, the default @Lock value is @Lock(WRITE). The code above uses the @Lock(READ) annotation on bean class to change the default so that multi-threaded access is granted by default. We then only need to apply the @Lock(WRITE) annotation to the methods that modify the state of the bean.</p> |
| |
| <p>Essentially @Lock(READ) allows multithreaded access to the Singleton bean instance unless someone is invoking an @Lock(WRITE) method. With @Lock(WRITE), the thread invoking the bean will be guaranteed to have exclusive access to the Singleton bean instance for the duration of its invocation. This combination allows the bean instance to use data types that are not normally thread safe. Great care must still be used, though.</p> |
| |
| <p>In the example we see ComponentRegistryBean using a java.util.HashMap which is not synchronized. To make this ok we do three things:</p> |
| |
| <ol> |
| <li>Encapsulation. We don't expose the HashMap instance directly; including its iterators, key set, value set or entry set.</li> |
| <li>We use @Lock(WRITE) on the methods that mutate the map such as the put() and remove() methods.</li> |
| <li>We use @Lock(READ) on the get() and values() methods as they do not change the map state and are guaranteed not to be called at the same as any of the @Lock(WRITE) methods, so we know the state of the HashMap is no being mutated and therefore safe for reading.</li> |
| </ol> |
| |
| <p>The end result is that the threading model for this bean will switch from multi-threaded access to single-threaded access dynamically as needed depending on the which methods are being invoked. This gives Singletons a bit of an advantage over Servlets for processing multi-threaded requests.</p> |
| |
| <p>See the Singleton Beans page for more advanced details on Container-Managed Concurrency. |
| Test Case</p> |
| |
| <pre><code> |
| public class ComponentRegistryBeanTest extends TestCase { |
| public void test() throws Exception { |
| Properties props = new Properties(); |
| props.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.LocalInitialContextFactory"); |
| InitialContext context = new InitialContext(props); |
| // Both references below will point to the exact same instance |
| ComponentRegistry one = (ComponentRegistry) context.lookup("ComponentRegistryBeanLocal"); |
| ComponentRegistry two = (ComponentRegistry) context.lookup("ComponentRegistryBeanLocal"); |
| URI expectedUri = new URI("foo://bar/baz"); |
| one.setComponent(URI.class, expectedUri); |
| URI actualUri = two.getComponent(URI.class); |
| assertSame(expectedUri, actualUri); |
| Date expectedDate = new Date(); |
| two.setComponent(Date.class, expectedDate); |
| Date actualDate = one.getComponent(Date.class); |
| assertSame(expectedDate, actualDate); |
| </div>} |
| </code></pre> |
| |
| <h1>Running</h1> |
| |
| <p>Running the example is fairly simple. In the "simple-singleton" directory run:</p> |
| |
| <p>$ mvn clean install</p> |
| |
| <p>Which should create output like the following.</p> |
| |
| <h1>Tests</h1> |
| |
| <pre><code> |
| Running org.superbiz.registry.ComponentRegistryBeanTest |
| Apache OpenEJB 3.1-SNAPSHOT build: 20080820-09:53 |
| http://tomee.apache.org/ |
| INFO - openejb.home = /Users/dblevins/work/openejb3/examples/simple-singleton |
| INFO - openejb.base = /Users/dblevins/work/openejb3/examples/simple-singleton |
| INFO - Configuring Service(id=Default Security Service, type=SecurityService, provider-id=Default Security Service) |
| INFO - Configuring Service(id=Default Transaction Manager, type=TransactionManager, provider-id=Default Transaction Manager) |
| INFO - Found EjbModule in classpath: /Users/dblevins/work/openejb3/examples/simple-singleton/target/classes |
| INFO - Beginning load: /Users/dblevins/work/openejb3/examples/simple-singleton/target/classes |
| INFO - Configuring enterprise application: classpath.ear |
| INFO - Configuring Service(id=Default Singleton Container, type=Container, provider-id=Default Singleton Container) |
| INFO - Auto-creating a container for bean ComponentRegistryBean: Container(type=SINGLETON, id=Default Singleton Container) |
| INFO - Enterprise application "classpath.ear" loaded. |
| INFO - Assembling app: classpath.ear |
| INFO - Jndi(name=ComponentRegistryBeanLocal) --> Ejb(deployment-id=ComponentRegistryBean) |
| INFO - Jndi(name=PropertyRegistryBeanLocal) --> Ejb(deployment-id=PropertyRegistryBean) |
| INFO - Created Ejb(deployment-id=ComponentRegistryBean, ejb-name=ComponentRegistryBean, container=Default Singleton Container) |
| INFO - Created Ejb(deployment-id=PropertyRegistryBean, ejb-name=PropertyRegistryBean, container=Default Singleton Container) |
| INFO - Deployed Application(path=classpath.ear) |
| Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.879 sec |
| Running org.superbiz.registry.PropertiesRegistryBeanTest |
| Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.009 sec |
| |
| Results : |
| |
| Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 |
| </code></pre> |
| |
| <p></div></p> |
| |
| |
| |
| |
| <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 © 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> |
