[jboss-cvs] JBossAS SVN: r82979 - in projects/ejb3/trunk/docs/tutorial/guide/en: modules and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri Jan 16 07:53:55 EST 2009
Author: jaikiran
Date: 2009-01-16 07:53:54 -0500 (Fri, 16 Jan 2009)
New Revision: 82979
Added:
projects/ejb3/trunk/docs/tutorial/guide/en/modules/cachedentity.xml
projects/ejb3/trunk/docs/tutorial/guide/en/modules/dependency.xml
projects/ejb3/trunk/docs/tutorial/guide/en/modules/enterprise_app_ejb_injection.xml
projects/ejb3/trunk/docs/tutorial/guide/en/modules/jboss_deployment_descriptor.xml
projects/ejb3/trunk/docs/tutorial/guide/en/modules/joininheritance.xml
projects/ejb3/trunk/docs/tutorial/guide/en/modules/resource_ref.xml
projects/ejb3/trunk/docs/tutorial/guide/en/modules/timer.xml
Modified:
projects/ejb3/trunk/docs/tutorial/guide/en/master.xml
Log:
More tutorials added to the guide
Modified: projects/ejb3/trunk/docs/tutorial/guide/en/master.xml
===================================================================
--- projects/ejb3/trunk/docs/tutorial/guide/en/master.xml 2009-01-16 12:38:47 UTC (rev 82978)
+++ projects/ejb3/trunk/docs/tutorial/guide/en/master.xml 2009-01-16 12:53:54 UTC (rev 82979)
@@ -22,6 +22,13 @@
<!ENTITY singleinheritance SYSTEM "modules/singleinheritance.xml">
<!ENTITY stateful_deployment_descriptor SYSTEM "modules/stateful_deployment_descriptor.xml">
<!ENTITY stateless_deployment_descriptor SYSTEM "modules/stateless_deployment_descriptor.xml">
+<!ENTITY joininheritance SYSTEM "modules/joininheritance.xml">
+<!ENTITY resource_ref SYSTEM "modules/resource_ref.xml">
+<!ENTITY timer SYSTEM "modules/timer.xml">
+<!ENTITY dependency SYSTEM "modules/dependency.xml">
+<!ENTITY jboss_deployment_descriptor SYSTEM "modules/jboss_deployment_descriptor.xml">
+<!ENTITY cachedentity SYSTEM "modules/cachedentity.xml">
+<!ENTITY enterprise_app_ejb_injection SYSTEM "modules/enterprise_app_ejb_injection.xml">
<!ENTITY todo SYSTEM "modules/todo.xml">
]>
<book lang="en">
@@ -35,5 +42,5 @@
<title>Target Audience</title>
<para>This tutorial is meant for EJB3 application developers on JBoss Application Server. The tutorial walks you through the EJB 3.0 features and how they deploy to JBoss. Please check the <xref linkend="Installation">install guide</xref> for system requirements.</para>
</preface>
-&installing;&stateless;&stateful;&blob;&callbacks;&composite;&ejb21_client_adaptors;&embeddable;&entity;&extended_pc;&injection;&interceptor;&jndibinding;&mdb;&mdb_deployment_descriptor;&merge;&relationships;&secondary;&security;&singleinheritance;&stateful_deployment_descriptor;&stateless_deployment_descriptor;&todo;
+&installing;&stateless;&stateful;&blob;&cachedentity;&callbacks;&composite;&dependency;&ejb21_client_adaptors;&embeddable;&enterprise_app_ejb_injection;&entity;&extended_pc;&injection;&interceptor;&jboss_deployment_descriptor;&jndibinding;&joininheritance;&mdb;&mdb_deployment_descriptor;&merge;&relationships;&resource_ref;&secondary;&security;&singleinheritance;&stateful_deployment_descriptor;&stateless_deployment_descriptor;&timer;&todo;
</book>
Added: projects/ejb3/trunk/docs/tutorial/guide/en/modules/cachedentity.xml
===================================================================
--- projects/ejb3/trunk/docs/tutorial/guide/en/modules/cachedentity.xml (rev 0)
+++ projects/ejb3/trunk/docs/tutorial/guide/en/modules/cachedentity.xml 2009-01-16 12:53:54 UTC (rev 82979)
@@ -0,0 +1,214 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter id="Caching EJB3 Entities">
+ <title>Caching EJB3 Entities</title>
+ <para>
+ This tutorial shows you how to cache your entities using EJB 3.0 for JBoss
+
+ </para>
+ <sect5>
+ Caching primer :
+
+ <para>
+ To avoid roundtrips to the database, you can use a cache for your entities.
+ JBoss EJB3 uses Hibernate as the JPA implementation which has support for a second-level cache.
+ The Hibernate setup used for our JBoss EJB 3.0 implementation uses JBossCache as its underlying cache
+ implementation. With caching enabled:
+
+ <itemizedlist>
+ <listitem>
+ If you persist an entity (that has caching enabled) to the database via the entity manager
+ the entity will also be added to the cache. Subsequent requests to fetch the entity, with
+ this id, will be retrieved from cache and thus will save a database trip.
+ </listitem>
+
+ <listitem>
+ If you update an entity (that has caching enabled) and save the changes to the database via
+ the entity manager the entity will also be updated in the cache.
+ </listitem>
+
+ <listitem>
+ If you remove an entity (that has caching enabled) from the database via the entity manager
+ the entity will also be removed from the cache.
+ </listitem>
+
+ </itemizedlist>
+ JBossCache allows you to specify timeouts to cached entities. Entities not accessed within a certain
+ amount of time are dropped from the cache in order to save memory.
+ </para>
+
+ <para>
+ Furthermore, JBossCache supports clustering. If running within a cluster, and the cache is updated,
+ changes to the entries in one node will be replicated to the corresponding entries in the other nodes
+ in the cluster.
+ </para>
+ </sect5>
+
+ <sect5>
+ Enabling caching and choosing cache :
+ <para>
+ Take a look at <literal>META-INF/persistence.xml</literal> which sets up the caching for this deployment:
+ <programlisting>
+ <![CDATA[
+<property name="hibernate.cache.use_second_level_cache" value="true"/>
+<property name="hibernate.cache.use_query_cache" value="true"/>
+<property name="hibernate.cache.region.factory_class" value="org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory"/>
+<property name="hibernate.cache.region.jbc2.cachefactory" value="java:CacheManager"/>
+<property name="hibernate.cache.region.jbc2.cfg.entity" value="mvcc-entity"/>
+<property name="hibernate.cache.region.jbc2.cfg.query" value="local-query"/>
+ ]]>
+ </programlisting>
+ <note>
+ These properties in the persistence.xml enabling caching and also configure JBossCache as the Cache manager.
+ For more details about JBossCache and its configurations, have a look at the JBossCache project documentation.
+ </note>
+
+ <note>
+ We have intentionally set the <literal>hibernate.show_sql</literal> property in the persistence.xml to true.
+ When this property is set, Hibernate will print to STDOUT the sql queries that are fired to the database, when
+ the entity is being operated upon. This will, later on, help us in verifying whether the entity is being picked up
+ from cache or is being loaded from database through a SQL query.
+ </note>
+ </para>
+ </sect5>
+
+ <sect5>
+ Entities:
+
+ <para>
+ You define your entities <literal>org.jboss.tutorial.cachedentity.bean.Customer</literal> and <literal>org.jboss.tutorial.cachedentity.bean.Contact</literal> the normal way.
+ The default behaviour is to not cache anything, even with the settings shown above, in the persistence.xml.
+ A very simplified rule of thumb is that you will typically want to do caching for objects that rarely change,
+ and which are frequently read. We also annotate the classes with the <literal>@Cache</literal> annotation to
+ indicate that the entities should be cached.
+ <programlisting>
+ <![CDATA[
+ at Entity
+ at Cache (usage=CacheConcurrencyStrategy.TRANSACTIONAL)
+public class Customer implements java.io.Serializable
+{
+...
+ ]]>
+ </programlisting>
+
+ <programlisting>
+ <![CDATA[
+ at Entity
+ at Cache (usage=CacheConcurrencyStrategy.TRANSACTIONAL)
+public class Contact implements Serializable
+{
+...
+
+ ]]>
+ </programlisting>
+ This defines that the Customer and the Contact entities need to be cached. Any attempt to look up
+ <literal>Customer</literal> or <literal>Contact</literal> by their primary key, will first attempt
+ to read the entry from the cache. If it cannot be found it will try and load it up from the database.
+ </para>
+
+ <para>
+ You can also cache relationship collections. Any attempt to access the <literal>contacts</literal> collection of
+ <literal>Customer</literal> will attempt to load the data from the cache before hitting the database:
+ <programlisting>
+ <![CDATA[
+
+ at Entity
+ at Cache (usage=CacheConcurrencyStrategy.TRANSACTIONAL)
+public class Customer implements java.io.Serializable
+{
+...
+
+ @Cache (usage=CacheConcurrencyStrategy.TRANSACTIONAL)
+ @OneToMany(mappedBy="customer", fetch=FetchType.EAGER, cascade=CascadeType.ALL)
+ public Set<Contact> getContacts()
+ {
+ return contacts;
+ }
+...
+}
+ ]]>
+
+ </programlisting>
+
+ </para>
+ </sect5>
+
+ <sect5>
+ Client :
+ <para>
+ Open <literal>org.jboss.tutorial.cachedentity.client.CachedEntityRun</literal>. It takes two arguments, they are the
+ server:jndiport of the two nodes to use. If you look at the 'run' target of <literal>META-INF/build.xml</literal>
+ you will see that they both default to localhost:1099, so in this case node1 and node2 will be the same,
+ i.e. no clustering takes place.
+ </para>
+ </sect5>
+
+ <sect5>
+
+Building and Running
+ <para>
+ <note>
+ <para>
+ To build and run the example, make sure you have installed JBoss 5.x.
+ See the <xref linkend="JBossAS5">installation section</xref> for details.
+ </para>
+ </note>
+
+ <sect5>
+ Ant Users:
+ </sect5>
+ <para>
+ Make sure the "all" server configuration of JBossAS-5.x is running
+ </para>
+ <programlisting>
+ <![CDATA[
+$ ant
+$ ant run
+
+run:
+ [java] Saving customer to node1 = localhost:1099
+ [java] Looking for customer on node2 = localhost:1099 (should be available in cache)
+ [java] Found customer on node2 (cache). Customer details follow:
+ [java] Customer: id=1; name=JBoss
+ [java] Contact: id=2; name=Kabir
+ [java] Contact: id=1; name=Bill
+
+ ]]>
+ </programlisting>
+
+ <sect5>
+ Maven Users: <xref linkend="Maven_Users_TODO">TODO</xref>
+ </sect5>
+
+ <programlisting>
+$ mvn clean install
+ </programlisting>
+
+ </para>
+ </sect5>
+ <para>
+ On the server you will notice these logs:
+ <programlisting>
+ <![CDATA[
+02:14:04,528 INFO [STDOUT] Hibernate: insert into Customer (id, name) values (null, ?)
+02:14:04,529 INFO [STDOUT] Hibernate: call identity()
+02:14:04,542 INFO [STDOUT] Hibernate: insert into Contact (id, CUST_ID, name, tlf) values (null, ?, ?, ?)
+02:14:04,543 INFO [STDOUT] Hibernate: call identity()
+02:14:04,544 INFO [STDOUT] Hibernate: insert into Contact (id, CUST_ID, name, tlf) values (null, ?, ?, ?)
+02:14:04,545 INFO [STDOUT] Hibernate: call identity()
+02:14:04,545 INFO [EntityTestBean] Created customer named JBoss with 2 contacts
+02:14:04,634 INFO [EntityTestBean] Find customer with id = 1
+02:14:04,645 INFO [STDOUT] Hibernate: select customer0_.id as id0_1_, customer0_.name as name0_1_, contacts1_.CUST_ID as CUST4_3_, contacts1_.id as id3_, contacts1_.id as id1_0_, contacts1_.CUST_ID as CUST4_1_0_, contacts1_.name as name1_0_, contacts1_.tlf as tlf1_0_ from Customer customer0_ left outer join Contact contacts1_ on customer0_.id=contacts1_.CUST_ID where customer0_.id=?
+02:14:04,682 INFO [EntityTestBean] Customer with id = 1 found
+02:14:04,756 INFO [EntityTestBean] Find customer with id = 1
+02:14:04,801 INFO [EntityTestBean] Customer with id = 1 found
+
+ ]]>
+
+ </programlisting>
+ As you can see, the first time the customer with id = 1 was being requested through the entity manager, a database query was fired to
+ fetch it, since it was not available in cache. The Customer object was then loaded from the database and stored in the cache. As can be
+ seen in the next request to fetch the customer with the same id. This request to the entity manager, pulls up the entity from the cache
+ instead of firing a database query.
+ </para>
+
+</chapter>
Added: projects/ejb3/trunk/docs/tutorial/guide/en/modules/dependency.xml
===================================================================
--- projects/ejb3/trunk/docs/tutorial/guide/en/modules/dependency.xml (rev 0)
+++ projects/ejb3/trunk/docs/tutorial/guide/en/modules/dependency.xml 2009-01-16 12:53:54 UTC (rev 82979)
@@ -0,0 +1,79 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter id="Dependencies in EJB3">
+ <title>Introduction to specifying dependencies in EJB3 beans</title>
+
+ <para>
+ Dependencies of an EJB on a service or services, including other EJBs, may be specified through the
+ <literal><depends></literal> tag of the jboss.xml deployment descriptor. The <literal><depends></literal>
+ tag is analagous to the <literal>@org.jboss.ejb3.annotation.Depends</literal> annotation. The dependencies control
+ the deployment of EJBs such that an EJB will not deploy until all of it's dependencies have successfully deployed.
+
+ </para>
+
+ <sect5>
+ jboss-service.xml :
+ <para>
+ Take a look at <literal>META-INF/jboss-service.xml</literal>. This service deployment descriptor starts
+ a service based on <literal>org.jboss.tutorial.dependency.bean.DependedOn</literal>.
+ <programlisting>
+ <![CDATA[
+<server>
+ <mbean code="org.jboss.tutorial.dependency.bean.DependedOn" name="jboss.test:service=DependedOn"/>
+</server>
+ ]]>
+
+ </programlisting>
+ </para>
+ </sect5>
+
+ <sect5>
+ jboss.xml :
+ <para>
+ Take a look at <literal>META-INF/jboss.xml</literal>. This deployment descriptor indicates that the
+ <literal>HasXmlMBeanDependencyBean</literal> is dependent on the <literal>jboss.test:service=DependedOn</literal>
+ started by <literal>jboss-service.xml</literal>. The <literal>HasXmlMBeanDependencyBean</literal> will not
+ deploy until the <literal>jboss.test:service=DependedOn</literal> service has successfully started.
+ </para>
+
+ </sect5>
+
+ <sect5>
+
+Building and Running
+ <para>
+ <note>
+ <para>
+ To build and run the example, make sure you have installed JBoss 5.x.
+ See the <xref linkend="JBossAS5">installation section</xref> for details.
+ </para>
+ </note>
+
+ <sect5>
+ Ant Users:
+ </sect5>
+ <para>
+ Make sure your JBossAS-5.x is running
+ </para>
+ <programlisting>
+ <![CDATA[
+$ ant
+$ ant run
+
+run:
+ [java] Lookup and bean access succeeded
+
+ ]]>
+ </programlisting>
+
+ <sect5>
+ Maven Users: <xref linkend="Maven_Users_TODO">TODO</xref>
+ </sect5>
+
+ <programlisting>
+$ mvn clean install
+ </programlisting>
+
+ </para>
+ </sect5>
+
+</chapter>
\ No newline at end of file
Added: projects/ejb3/trunk/docs/tutorial/guide/en/modules/enterprise_app_ejb_injection.xml
===================================================================
--- projects/ejb3/trunk/docs/tutorial/guide/en/modules/enterprise_app_ejb_injection.xml (rev 0)
+++ projects/ejb3/trunk/docs/tutorial/guide/en/modules/enterprise_app_ejb_injection.xml 2009-01-16 12:53:54 UTC (rev 82979)
@@ -0,0 +1,164 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter id="Injecting EJB in Servlets">
+ <title>Introduction to EJB injection in Servlets</title>
+
+ <para>
+ This tutorial aims at showing how EJBs can be injected in a Servlet. In this tutorial we build an EAR file which
+ contains a EJB module (jar file) and a web module (war file).
+ </para>
+
+ <para>
+ Take a look at the <literal>META-INF/application.xml</literal> file:
+ <programlisting>
+ <![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE application PUBLIC
+ "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
+ "http://java.sun.com/dtd/application_1_3.dtd">
+<application>
+ <display-name>jboss-ejb3-tutorial-ejb_injection</display-name>
+ <description>Enterprise application showing injection of EJB in Servlet</description>
+ <module>
+ <web>
+ <web-uri>jboss-ejb3-tutorial-enterprise_webapp.war</web-uri>
+ <context-root>/jboss-ejb3-tutorial-enterprise_webapp</context-root>
+ </web>
+ </module>
+ <module>
+ <ejb>jboss-ejb3-tutorial-enterprise_ejb3app.jar</ejb>
+ </module>
+</application>
+
+ ]]>
+ </programlisting>
+ </para>
+
+ <sect5>
+ EJB module:
+ <para>
+ The EJB module in this tutorial consists of a EJB3 SLSB. Take a look at <literal>org.jboss.tutorial.enterprise_app_ejb_injection.bean.CalculatorBean</literal>:
+ <programlisting>
+ <![CDATA[
+ at Stateless(name="calculator")
+ at Remote(CalculatorRemote.class)
+ at Local(CalculatorLocal.class)
+public class CalculatorBean implements CalculatorRemote, CalculatorLocal
+{
+...
+ ]]>
+ </programlisting>
+ </para>
+ We will be using this bean in the servlet for performing the <literal>add</literal> and <literal>subtract</literal> operations.
+
+ <important>
+ <para>
+ When a EJB packaged in a jar file is deployed as part of an EAR, the default jndi-name for the business-remote interface
+ will be of the form EARName/BeanName/remote. Similarly the local business-remote will have the default jndi-name of the form
+ EARName/BeanName/local.
+ </para>
+ </important>
+ </sect5>
+
+ <sect5>
+ Web module:
+ <para>
+ The web module consists of a <literal>index.html</literal> and a servlet <literal>org.jboss.tutorial.enterprise_app_ejb_injection.servlet.CalculatorActionServlet</literal>.
+ Take a look at the <literal>WEB-INF/web.xml</literal> which configures the <literal>index.html</literal> as the welcome page and
+ also maps the servlet.
+ <programlisting>
+ <![CDATA[
+ <servlet>
+ <servlet-name>CalculatorActionServlet</servlet-name>
+ <servlet-class>org.jboss.tutorial.enterprise_app_ejb_injection.servlet.CalculatorActionServlet</servlet-class>
+ </servlet>
+
+<!-- The servlet and jsp page mappings -->
+<servlet-mapping>
+ <servlet-name>CalculatorActionServlet</servlet-name>
+ <url-pattern>/CalculatorAction</url-pattern>
+</servlet-mapping>
+
+<welcome-file-list>
+ <welcome-file>index.html</welcome-file>
+</welcome-file-list>
+
+ ]]>
+ </programlisting>
+
+ The <literal>org.jboss.tutorial.enterpise_app_ejb_injection.bean.CalculatorLocal</literal> will be injected in the
+ <literal>org.jboss.tutorial.enterprise_app_ejb_injection.servlet.CalculatorActionServlet</literal> using the <literal>@EJB</literal>
+ annotation:
+ <programlisting>
+ <![CDATA[
+private CalculatorLocal calculator;
+
+/**
+ * Injecting the EJB
+ */
+ at EJB(name = "calculator")
+public void setCalculator(CalculatorLocal calculator)
+{
+ this.calculator = calculator;
+}
+ ]]>
+ </programlisting>
+ <important>
+ <para>
+ For the injection to take place in a web module, your web.xml should use the 2.5 version of the web-app xsd:
+ <programlisting>
+ <![CDATA[
+<web-app version="2.5"
+ xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
+ ]]>
+ </programlisting>
+ </para>
+ </important>
+
+ </para>
+ </sect5>
+
+ <sect5>
+Building and Running
+ </sect5>
+
+ <note>
+ <para>
+ To build and run the example, make sure you have installed JBoss 5.x.
+ See the <xref linkend="JBossAS5">installation section</xref> for details.
+ </para>
+ </note>
+
+ <sect5>
+Ant Users:
+ </sect5>
+ <para>
+ Make sure your JBossAS-5.x is running
+ </para>
+ <programlisting>
+ <![CDATA[
+$ ant
+ ]]>
+ </programlisting>
+ <para>
+ This will deploy the ear into the JBossAS-5.x server ("default" configuration).
+ </para>
+ <sect5 id="AccessTheWebApp">
+ To access the servlet, open a web browser and enter <ulink url="http://localhost:8080/jboss-ejb3-tutorial-enterprise_webapp">http://localhost:8080/jboss-ejb3-tutorial-enterprise_webapp</ulink>.
+ This will bring up a page where you can enter two number and either click on <literal>Add</literal> or <literal>subtract</literal>.
+ </sect5>
+
+ <sect5>
+Maven Users: <xref linkend="Maven_Users_TODO">TODO</xref>
+ </sect5>
+
+ <programlisting>
+$ mvn clean package
+ </programlisting>
+ <para>
+ This will create the EAR in the <literal>target</literal> folder of the tutorial. Copy this EAR to the deploy folder of JBossAS-5.x
+ and start the server (if it's already not started). Then follow the steps mentioned above, to access the servlet from the web browser.
+ </para>
+
+</chapter>
\ No newline at end of file
Added: projects/ejb3/trunk/docs/tutorial/guide/en/modules/jboss_deployment_descriptor.xml
===================================================================
--- projects/ejb3/trunk/docs/tutorial/guide/en/modules/jboss_deployment_descriptor.xml (rev 0)
+++ projects/ejb3/trunk/docs/tutorial/guide/en/modules/jboss_deployment_descriptor.xml 2009-01-16 12:53:54 UTC (rev 82979)
@@ -0,0 +1,112 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter id="jboss.xml deployment descriptor">
+ <title>Usage of JBoss specific deployment descriptors</title>
+
+ <para>
+ The EJB 3.0 specification supports the usage of deployment descriptors to describe ejb metadata
+ or override most metadata described via annotations. The jboss.xml deployment descriptor describes
+ JBoss specific metadata, including remote and local JNDI names, cluster configuration, a security domain,
+ additional references, security principal, and container configuration. Annotations which define the ejb
+ (e.g. <literal>@Stateful</literal>, <literal>@Remote</literal>) cannot be overridden.
+
+ </para>
+
+ <sect5>
+ jboss.xml :
+
+ <para>
+ Take a look at <literal>META-INF/jboss.xml</literal>.
+ <itemizedlist>
+ <listitem>
+ The <literal>jndi-name</literal> element defines the remote JNDI binding for the <literal>ShoppingCartBean</literal> stateful session bean.
+ This JNDI binding overrides the default binding or a binding specified through the <literal>@RemoteBinding</literal> annotation.
+ Similarly, the <literal>local-jndi-name</literal> element specifies the local JNDI binding.
+ </listitem>
+
+ <listitem>
+ The <literal>clustered</literal> element indicates that the ejb is clustered, with <literal>partition-name</literal> and
+ <literal>load-balance-policy</literal> specifying the cluster name and load balance policy, respectively.
+ These elements will override the parameters specified in the <literal>@Clustered</literal> annotation.
+ In this example, you will see that the <literal>ShoppingCartBean</literal> ejb is clustered.
+ <note>
+ If you build and run this example with the "default" server configuration, the deployment will
+ fail, as the default server configuration does not support clustering. You will have to run this
+ example on the "all" server configuration which supports clustering
+ </note>
+ </listitem>
+
+ <listitem>
+ The <literal>security-domain</literal> element specifies a security domain for the ejb, overriding
+ any security domain set through the <literal>@SecurityDomain</literal> annotation. In this example,
+ you will see that a security domain is set through the jboss.xml deployment descriptor and unless a
+ Principal and Credential (i.e. user/password) is set in the client, requests to the ejb will fail
+ with a javax.ejb.EJBAccessException.
+
+ <note>
+ The jboss.xml shows using the security-domain at a bean level as well at the entire deployment level.
+ Each bean can have its own security-domain and will override the one set at the deployment level.
+ </note>
+
+ </listitem>
+ </itemizedlist>
+
+ </para>
+ </sect5>
+
+ <sect5>
+
+Building and Running
+ <para>
+ <note>
+ <para>
+ To build and run the example, make sure you have installed JBoss 5.x.
+ See the <xref linkend="JBossAS5">installation section</xref> for details.
+ </para>
+ </note>
+
+ <sect5>
+ Ant Users:
+ </sect5>
+ <para>
+ Make sure the "all" server configuration of JBossAS-5.x is running
+ </para>
+ <programlisting>
+ <![CDATA[
+$ ant
+$ ant run
+
+run:
+ [java] Attempting to buy 1 memory stick with incorrect password
+ [java] Caught javax.ejb.EJBAccessException as expected
+ [java] Setting user/password
+ [java] bill is a shopper, so is allowed to buy
+ [java] Buying 1 memory stick
+ [java] Buying another memory stick
+ [java] Buying a laptop
+ [java] Print cart:
+ [java] 2 Memory stick
+ [java] 1 Laptop
+ [java] bill is not a clerk, so is not allowed to price check
+ [java] Caught EJBAccessException as expected
+ [java] Checkout
+ [java] Should throw an object not found exception by invoking on cart after @Remove method
+ [java] Successfully caught no such object exception.
+ [java] Caught javax.ejb.EJBAccessException, for SLSB, as expected
+ [java] Now passing the correct user/password to access the SLSB
+ [java] Successfully accessed SLSB
+
+ ]]>
+ </programlisting>
+
+ <sect5>
+ Maven Users: <xref linkend="Maven_Users_TODO">TODO</xref>
+ </sect5>
+
+ <programlisting>
+$ mvn clean install
+ </programlisting>
+
+ </para>
+ </sect5>
+
+</chapter>
\ No newline at end of file
Added: projects/ejb3/trunk/docs/tutorial/guide/en/modules/joininheritance.xml
===================================================================
--- projects/ejb3/trunk/docs/tutorial/guide/en/modules/joininheritance.xml (rev 0)
+++ projects/ejb3/trunk/docs/tutorial/guide/en/modules/joininheritance.xml 2009-01-16 12:53:54 UTC (rev 82979)
@@ -0,0 +1,156 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter id="Join Inheritance in EJB3 Entities">
+ <title>Introduction Join Inheritance in EJB3 Entities</title>
+
+ <para>
+ The EJB3 specification allows you to define entities that inherit from one another.
+ The inheritance relationships can be reflected in queries as well. So, if you queried based
+ on the base class, the query is polymorphic.
+ </para>
+
+ <para>
+ The tutorial example uses the join table strategy to map an inheritance relationship of
+ <literal>org.jboss.tutorial.joininheritance.bean.Pet</literal>, which is the base class
+ for <literal>org.jboss.tutorial.joininheritance.bean.Cat</literal> and
+ <literal>org.jboss.tutorial.joininheritance.bean.Dog</literal>.
+ </para>
+
+ <para>
+ With the join table strategy there is a table per class in the hierarchy, but the subclass tables
+ only have the extra attribute they define in their subclass. A discriminator column is NOT required
+ to differentiate between which class type is persisted in a particular row unlike the single table mapping.
+ The persistence manager does not need a discrimiator column to figure out the type.
+ </para>
+
+ <para>
+ This is what the annotations look like for Pet:
+ <programlisting>
+ <![CDATA[
+ at Entity
+ at Inheritance(strategy = InheritanceType.JOINED)
+public class Pet implements java.io.Serializable
+{
+...
+ ]]>
+
+ </programlisting>
+
+ <programlisting>
+ <![CDATA[
+ at Entity
+ at Inheritance(strategy = InheritanceType.JOINED)
+public class Dog extends Pet
+{
+...
+
+ ]]>
+ </programlisting>
+ </para>
+
+ <sect5>
+ Polymorphic Queries :
+
+ <para>
+ <literal>org.jboss.tutorial.joininheritance.bean.PetDAOBean</literal> stateless EJB wraps
+ some polymorphic queries.
+
+ <programlisting>
+ <![CDATA[
+public List findByWeight(double weight)
+{
+ return manager.createQuery("from Pet p where p.weight < :weight").setParameter("weight", weight).getResultList();
+}
+
+
+ ]]>
+ </programlisting>
+ Even though the <literal>findByWeight</literal> method queries on Pet, either Dog or Cat instances
+ can be returned.
+ </para>
+
+ </sect5>
+
+ <sect5>
+ Table Mapping :
+
+ <para>
+ The table mapping for this example looks like this:
+ <programlisting>
+ <![CDATA[
+create table PET (
+ ID integer primary key,
+ ANIMAL_TYPE varchar,
+ NAME varchar,
+ WEIGHT double
+);
+
+create table CAT (
+ ID integer primary key,
+ LIVES int
+);
+
+create table DOG (
+ ID integer primary key,
+ NUMBONES int
+);
+
+ ]]>
+
+ </programlisting>
+ The join inheritance mapping is less efficient than the single table strategy as the SQL query is more complicated.
+ </para>
+
+ </sect5>
+
+ <sect5>
+
+Building and Running
+ <para>
+ <note>
+ <para>
+ To build and run the example, make sure you have installed JBoss 5.x.
+ See the <xref linkend="JBossAS5">installation section</xref> for details.
+ </para>
+ </note>
+
+ <sect5>
+ Ant Users:
+ </sect5>
+ <para>
+ Make sure your JBossAS-5.x is running
+ </para>
+ <programlisting>
+ <![CDATA[
+$ ant
+$ ant run
+
+run:
+ [java] Sox
+ [java] Junior
+
+ ]]>
+ </programlisting>
+
+ <sect5>
+ Maven Users: <xref linkend="Maven_Users_TODO">TODO</xref>
+ </sect5>
+
+ <programlisting>
+$ mvn clean install
+ </programlisting>
+
+ </para>
+ </sect5>
+
+ <sect5>
+ View the tables and rows:
+
+ <para>
+ You can view the tables created by JBoss by going to the
+ <ulink url="http://localhost:8080/jmx-console/HtmlAdaptor?action=inspectMBean&name=jboss%3Aservice%3DHypersonic%2Cdatabase%3DlocalDB">Hypersonic Service</ulink>,
+ scrolling down to the <literal>startDatabaseManager</literal> button and clicking it.
+ A Hypersonic SQL window will be minimized, but you can open it up to look at the tables and do queries.
+
+ </para>
+ </sect5>
+</chapter>
\ No newline at end of file
Added: projects/ejb3/trunk/docs/tutorial/guide/en/modules/resource_ref.xml
===================================================================
--- projects/ejb3/trunk/docs/tutorial/guide/en/modules/resource_ref.xml (rev 0)
+++ projects/ejb3/trunk/docs/tutorial/guide/en/modules/resource_ref.xml 2009-01-16 12:53:54 UTC (rev 82979)
@@ -0,0 +1,95 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter id="Using resource references in EJB3">
+ <title>Introduction to binding the resources to ENC of EJB3 beans</title>
+
+ <para>
+ Resources (e.g. data sources, JavaMail sessions, JMS queues) may be added to the local jndi namespace (ENC)
+ of individual EJBs. This is to separate the jndi names used in the bean code from the global jndi bindings
+ set by the bean deployer. The mapping of the bean local jndi binding and the global binding may be handled
+ via the ejb-jar.xml and jboss.xml deployment descriptors.
+ </para>
+
+ <sect5>
+ ejb-jar.xml :
+
+ <para>
+ Take a look at <literal>META-INF/ejb-jar.xml</literal>. For <literal>ENCBean</literal>, there are 3
+ <literal><resource-ref></literal> elements indicating resource reference names and types.
+
+ </para>
+
+ </sect5>
+
+ <sect5>
+ jboss.xml :
+ <para>
+ Take a look at <literal>META-INF/jboss.xml</literal>. For <literal>ENCBean</literal>, there are again
+ 3 <literal><resource-ref></literal> elements indicating resource reference names and either the global jndi
+ binding via the <literal><jndi-name></literal> element or the resource name. Resource managers
+ are used to map resource names to global jndi bindings via the <literal><resource-managers></literal> element.
+
+ </para>
+
+ </sect5>
+
+ <sect5>
+ TestENCBean.java :
+ <para>
+ Take a look at <literal>org.jboss.tutorial.resource_ref.bean.TestENCBean</literal>. Each one of the resources are accessed from the
+ bean local jndi namespace (i.e. java:comp/env) by the value set in the <literal><res-ref-name></literal> values
+ in the deployment descriptors.
+ </para>
+ </sect5>
+
+ <sect5>
+
+Building and Running
+ <para>
+ <note>
+ <para>
+ To build and run the example, make sure you have installed JBoss 5.x.
+ See the <xref linkend="JBossAS5">installation section</xref> for details.
+ </para>
+ </note>
+
+ <sect5>
+ Ant Users:
+ </sect5>
+ <para>
+ Make sure your JBossAS-5.x is running
+ </para>
+ <programlisting>
+ <![CDATA[
+$ ant
+$ ant run
+
+run:
+ [java] Successfully accessed bean resource references
+
+ ]]>
+ </programlisting>
+
+ <sect5>
+ Maven Users: <xref linkend="Maven_Users_TODO">TODO</xref>
+ </sect5>
+
+ <programlisting>
+$ mvn clean install
+ </programlisting>
+
+ </para>
+ </sect5>
+ <para>
+ On the server you will notice these logs:
+ <programlisting>
+ <![CDATA[
+13:44:09,500 INFO [TestENCBean] Found data source resource ref
+13:44:09,500 INFO [TestENCBean] Found mail resource ref
+13:44:09,500 INFO [TestENCBean] Found jms queue resource ref
+13:44:09,500 INFO [TestENCBean] Found jms queue resource env ref
+
+ ]]>
+ </programlisting>
+ </para>
+
+</chapter>
\ No newline at end of file
Added: projects/ejb3/trunk/docs/tutorial/guide/en/modules/timer.xml
===================================================================
--- projects/ejb3/trunk/docs/tutorial/guide/en/modules/timer.xml (rev 0)
+++ projects/ejb3/trunk/docs/tutorial/guide/en/modules/timer.xml 2009-01-16 12:53:54 UTC (rev 82979)
@@ -0,0 +1,92 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter id="Timer service in EJB3">
+ <title>Introduction to timer service in EJB3</title>
+
+ <para>
+ This example shows you how to access <literal>javax.ejb.SessionContext</literal> as well as using
+ the EJB Timer Service. It also explains how callbacks work in EJB 3.0.
+
+ </para>
+
+ <sect5>
+ SessionContext injection :
+
+ <para>
+ The <literal>javax.ejb.SessionContext</literal> is injected using the <literal>@javax.annotation.Resource</literal> annotation.
+ When the stateless bean instance is created the field will be initialized with the correct SessionContext.
+ Take a look at <literal>org.jboss.tutorial.timer.bean.ExampleTimerBean</literal>
+ <programlisting>
+ <![CDATA[
+private @Resource SessionContext ctx;
+
+ ]]>
+
+ </programlisting>
+ </para>
+
+ </sect5>
+
+ <sect5>
+ Timeout Callbacks :
+ <para>
+ The rest of the bean example registers a timer with the EJB Timer service. In the EJB 2.1 specification
+ it was required to implement an interface to get ejbTimeout callbacks. In JBoss EJB3, it is implemented
+ as an annotation. All you have to define is a method annotated with <literal>javax.ejb.Timeout</literal>.
+
+ </para>
+ </sect5>
+
+ <sect5>
+
+Building and Running
+ <para>
+ <note>
+ <para>
+ To build and run the example, make sure you have installed JBoss 5.x.
+ See the <xref linkend="JBossAS5">installation section</xref> for details.
+ </para>
+ </note>
+
+ <sect5>
+ Ant Users:
+ </sect5>
+ <para>
+ Make sure your JBossAS-5.x is running
+ </para>
+ <programlisting>
+ <![CDATA[
+$ ant
+$ ant run
+
+run:
+ [java] Timer scheduled to trigger after 5 seconds
+
+ ]]>
+ </programlisting>
+
+ <sect5>
+ Maven Users: <xref linkend="Maven_Users_TODO">TODO</xref>
+ </sect5>
+
+ <programlisting>
+$ mvn clean install
+ </programlisting>
+
+ </para>
+ </sect5>
+ <para>
+ On the server you will notice these logs:
+ <programlisting>
+ <![CDATA[
+INFO [STDOUT] ---------------------
+INFO [STDOUT] Created a timer event to be triggered after 5000 milli seconds
+INFO [STDOUT] ---------------------
+INFO [STDOUT] ---------------------
+INFO [STDOUT] * Received Timer event: Hello World
+INFO [STDOUT] ---------------------
+
+ ]]>
+ </programlisting>
+ </para>
+
+</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list