Seam SVN: r11674 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 03:51:59 -0500 (Tue, 24 Nov 2009)
New Revision: 11674
Modified:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml
Log:
Edited the Tutorial chapter.
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml 2009-11-24 08:09:15 UTC (rev 11673)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml 2009-11-24 08:51:59 UTC (rev 11674)
@@ -97,7 +97,7 @@
<emphasis>validation</emphasis> declaratively, via annotations. It also needs some extra
annotations that define the class as a Seam component. </para>
<!-- Can't use code hightlighting with callouts -->
- <example>
+
<formalpara><title>User.java Example</title>
<para>
<programlisting role="JAVA"><![CDATA[@Entity
@@ -198,7 +198,7 @@
</orderedlist>
</para>
</formalpara>
-</example>
+
<para> The most important things to notice in this example are the <literal>@Name</literal> and
<literal>@Scope</literal> annotations. These annotations establish that this class is a Seam component. </para>
<para> We'll see below that the properties of our <literal>User</literal> class are bound
@@ -214,7 +214,7 @@
<section>
<title>The stateless session bean class: <literal>RegisterAction.java</literal></title>
- <para> Most Seam application use session beans as JSF action listeners (you can use JavaBeans instead if
+ <para> Most Seam applications use session beans as JSF action listeners (you can use JavaBeans instead if
you like). </para>
<para> We have exactly one JSF action in our application, and one session bean method attached to it. In
this case, we'll use a stateless session bean, since all the state associated with our action is
@@ -392,18 +392,9 @@
<section>
<title>The Seam component deployment descriptor: <literal>components.xml</literal></title>
- <para> If you've used many Java frameworks before, you'll be used to having to declare all your
- component classes in some kind of XML file that gradually grows more and more unmanageable as your
- project matures. You'll be relieved to know that Seam does not require that application components
- be accompanied by XML. Most Seam applications require a very small amount of XML that does not grow
- very much as the project gets bigger. </para>
+ <para> If you have used Java frameworks previously, you will be used to declaring your component classes in an XML file. You have probably also noticed that as a project matures, these XML files tend to become unmanageable. Fortunately, Seam does not require application components to be accompanied by XML. Most Seam applications require only a small amount of XML, which does not tend to increase in size as projects expand. </para>
- <para> Nevertheless, it is often useful to be able to provide for <emphasis>some</emphasis> external
- configuration of <emphasis>some</emphasis> components (particularly the components built in to
- Seam). You have a couple of options here, but the most flexible option is to provide this
- configuration in a file called <literal>components.xml</literal>, located in the
- <literal>WEB-INF</literal> directory. We'll use the <literal>components.xml</literal> file to tell
- Seam how to find our EJB components in JNDI: </para>
+ <para> However, it is often useful to be able to provide for some external configuration of some components, particularly the components that are built into Seam. The most flexible option, here, is to provide this configuration in a file called <filename>components.xml</filename>, located in the <filename>WEB-INF</filename> directory. The <filename>components.xml</filename> file can be used to tell Seam how to find our EJB components in JNDI: </para>
<example>
<title></title>
<programlisting role="XML">
@@ -504,17 +495,12 @@
</example>
- <para> Note that we don't need
- any JSF managed bean declarations! Our managed beans are annotated Seam components. In Seam applications,
- the <literal>faces-config.xml</literal> is used much less often than in plain JSF. </para>
+ <para> Note that JSF managed bean declarations are unnecessary because the managed beans are annotated Seam components. In Seam applications, <filename>faces-config.xml</filename> is used much less often than in plain JSF. Here, we use it simply to enable Facelets (and not JSP) as the view handler.
+ </para>
- <para> In fact, once you have all the basic descriptors set up, the <emphasis>only</emphasis> XML you
- need to write as you add new functionality to a Seam application is orchestration: navigation rules
- or jBPM process definitions. Seam takes the view that <emphasis>process flow</emphasis> and
- <emphasis>configuration data</emphasis> are the only things that truly belong in XML. </para>
+ <para> Once you have set up all the basic descriptors, the only XML you need write to add functionality to a Seam application will be for orchestration: navigation rules or jBPM process definitions. Seam operates on the principle that process flow and configuration data are all that truly belongs in XML. </para>
- <para> In this simple example, we don't even need a navigation rule, since we decided to embed the view
- id in our action code. </para>
+ <para> The previous example does not require a navigation rule, since the view ID was embedded in our action code. </para>
</section>
@@ -579,7 +565,7 @@
<title>The view: <literal>register.xhtml</literal> and <literal>registered.xhtml</literal></title>
<para> The view pages for a Seam application could be implemented using any technology that supports
- JSF. In this example we use Facelets, because we think it's better than JSP.</para>
+ JSF. This example uses Facelets.</para>
<example>
<title></title>
@@ -638,9 +624,6 @@
</example>
- <para> This is a boring old Facelets page using some embedded EL. There is nothing specific to Seam
- here. </para>
-
</section>
<section>
@@ -681,8 +664,6 @@
<para> This deployment descriptor links modules in the enterprise archive and binds the web application
to the context root <literal>/seam-registration</literal>. </para>
- <para> We've now seen <emphasis>all</emphasis> the files in the entire application! </para>
-
</section>
</section>
@@ -813,7 +794,7 @@
<para> But <literal>MessageManagerBean</literal> is also responsible for fetching the list of messages
the first time we navigate to the message list page. There are various ways the user could navigate
- to the page, and not all of them are preceded by a JSF action—the user might have
+ to the page, and not all of them are preceded by a JSF action — the user might have
bookmarked the page, for example. So the job of fetching the message list takes place in a Seam
<emphasis>factory method</emphasis>, instead of in an action listener method. </para>
@@ -934,12 +915,11 @@
public void destroy();
}</programlisting>
- <para> From now on, we won't show local interfaces in our code examples. </para>
- <para> Let's skip over <literal>components.xml</literal>, <literal>persistence.xml</literal>,
+ <para> From this point, local interfaces are no longer shown in these code examples.
+ <literal>components.xml</literal>, <literal>persistence.xml</literal>,
<literal>web.xml</literal>, <literal>ejb-jar.xml</literal>, <literal>faces-config.xml</literal>
- and <literal>application.xml</literal> since they are much the same as the previous example, and go
- straight to the JSP. </para>
+ and <literal>application.xml</literal> operate in a similar fashion to the previous example and to directly to the JSP. </para>
</section>
@@ -1055,8 +1035,8 @@
<section>
<title>Understanding the code</title>
<para> The center of this example is the jBPM process definition. There are also two JSPs and two trivial
- JavaBeans (There was no reason to use session beans, since they do not access the database, or have any
- other transactional behavior). Let's start with the process definition: </para>
+ JavaBeans. (There was no reason to use session beans, since they do not access the database, or have any
+ other transactional behavior.) Let's start with the process definition: </para>
<!-- Can't use code hightlighting with callouts -->
<formalpara><title>todo.jpdl.xml Example</title>
<para>
@@ -1531,7 +1511,7 @@
</imageobject>
</mediaobject>
- <para> Now that we have seen the pageflow, it is very, very easy to understand the rest of the application! </para>
+ <para> Now that we have seen the pageflow, it is easy to understand the rest of the application. </para>
<para> Here is the main page of the application, <literal>numberGuess.jspx</literal>: </para>
@@ -1647,7 +1627,7 @@
</example>
- <para> As is <literal>lose.jspx</literal> (which I can't be bothered copy/pasting). Finally, the JavaBean
+ <para><filename>lose.jspx</filename> is also as expected. Finally, the JavaBean
Seam component: </para>
<!-- Can't use code hightlighting with callouts -->
<formalpara><title>NumberGuess.java Example</title>
@@ -1786,7 +1766,7 @@
</programlisting>
- <para> As you can see, this Seam component is pure business logic! It doesn't need to know anything at all
+ <para> As you can see, this Seam component is pure business logic. It doesn't need to know anything at all
about the user interaction flow. This makes the component potentially more reuseable. </para>
</section>
@@ -1849,50 +1829,60 @@
</mediaobject>
</screenshot>
- <para> The booking application uses JSF, EJB 3.0 and Seam, together with Facelets for the view. There is
- also a port of this application to JSF, Facelets, Seam, JavaBeans and Hibernate3. </para>
+ <para> The booking application uses JSF, EJB 3.0 and Seam, together with Facelets for the view. There is also a port of this application to JSF, Facelets, Seam, JavaBeans and Hibernate3. </para>
- <para> One of the things you'll notice if you play with this application for long enough is that it is
- extremely <emphasis>robust</emphasis>. You can play with back buttons and browser refresh and opening
- multiple windows and entering nonsensical data as much as you like and you will find it very difficult
- to make the application crash. You might think that we spent weeks testing and fixing bugs to achive
- this. Actually, this is not the case. Seam was designed to make it very straightforward to build robust
- web applications and a lot of robustness that you are probably used to having to code yourself comes
- naturally and automatically with Seam. </para>
- <para> As you browse the sourcecode of the example application, and learn how the application works, observe
- how the declarative state management and integrated validation has been used to achieve this robustness. </para>
+ <para> One of the things you will notice about this application is that it is extremely robust. You can open multiple windows, use the back and browser refresh buttons, and enter nonsensical data, but the application is difficult to crash. Seam was designed to make building robust web applications straightforward, so robustness that would previously be hand-coded comes naturally and automatically with Seam. </para>
+
+ <para> As you browse the source code of the example application and learn how the application works, pay particular attention to the way the declarative state management and integrated validation has been used to achieve this robustness. </para>
</section>
<section>
<title>Overview of the booking example</title>
- <para> The project structure is identical to the previous one, to install and deploy this application,
+ <para> The project structure is identical to the previous one. To install and deploy this application,
please refer to <xref linkend="try-examples"/>. Once you've successfully started the application, you
can access it by pointing your browser to <ulink url="http://localhost:8080/seam-booking/">
<literal>http://localhost:8080/seam-booking/</literal>
</ulink>
</para>
- <para> Just nine classes (plus six session beans local interfaces) where used to implement this application.
- Six session bean action listeners contain all the business logic for the listed features. </para>
+ <para> The application uses six session beans to implement the business logic for the following features: </para>
- <itemizedlist>
+ <itemizedlist>
<listitem>
- <para><literal>BookingListAction</literal> retrieves existing bookings for the currently logged in user. </para>
+ <para>
+ <literal>AuthenticatorAction</literal> provides the login authentication logic.
+ </para>
</listitem>
- <listitem>
- <para><literal>ChangePasswordAction</literal> updates the password of the currently logged in user.</para>
+ <listitem>
+ <para>
+ <literal>BookingListAction</literal> retrieves existing bookings for the currently logged in user.
+ </para>
</listitem>
- <listitem>
- <para><literal>HotelBookingAction</literal> implements the core functionality of the application: hotel
- room searching, selection, booking and booking confirmation. This functionality is implemented as a
- <emphasis>conversation</emphasis>, so this is the most interesting class in the application. </para></listitem>
- <listitem>
- <para><literal>RegisterAction</literal> registers a new system user.</para>
+ <listitem>
+ <para>
+ <literal>ChangePasswordAction</literal> updates the password of the currently logged in user.
+ </para>
</listitem>
+ <listitem>
+ <para>
+ <literal>HotelBookingAction</literal> implements booking and confirmation functionality. This is implemented as a <emphasis>conversation</emphasis>, so this is one of the more important classes in the application.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>HotelSearchingAction</literal> implements the hotel search functionality.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>RegisterAction</literal> registers a new system user.
+ </para>
+ </listitem>
</itemizedlist>
+
<para> Three entity beans implement the application's persistent domain model. </para>
<itemizedlist>
@@ -1909,66 +1899,36 @@
<section>
<title>Understanding Seam conversations</title>
- <para> We encourage you browse the sourcecode at your pleasure. In this tutorial we'll concentrate upon one
- particular piece of functionality: hotel search, selection, booking and confirmation. From the point of
- view of the user, everything from selecting a hotel to confirming a booking is one continuous unit of
- work, a <emphasis>conversation</emphasis>. Searching, however, is <emphasis>not</emphasis> part of the
- conversation. The user can select multiple hotels from the same search results page, in different
- browser tabs. </para>
- <para> Most web application architectures have no first class construct to represent a conversation. This
- causes enormous problems managing state associated with the conversation. Usually, Java web applications
- use a combination of two techniques: first, some state is thrown into the
- <literal>HttpSession</literal>; second, persistable state is flushed to the database after every
- request, and reconstructed from the database at the beginning of each new request. </para>
- <para> Since the database is the least scalable tier, this often results in an utterly unacceptable lack of
- scalability. Added latency is also a problem, due to the extra traffic to and from the database on every
- request. To reduce this redundant traffic, Java applications often introduce a data (second-level) cache
- that keeps commonly accessed data between requests. This cache is necessarily inefficient, because
- invalidation is based upon an LRU policy instead of being based upon when the user has finished working
- with the data. Furthermore, because the cache is shared between many concurrent transactions, we've
- introduced a whole raft of problem's associated with keeping the cached state consistent with the
- database. </para>
- <para> Now consider the state held in the <literal>HttpSession</literal>. By very careful programming, we
- might be able to control the size of the session data. This is a lot more difficult than it sounds,
- since web browsers permit ad hoc non-linear navigation. But suppose we suddenly discover a system
- requirement that says that a user is allowed to have <emphasis>mutiple concurrent
- conversations</emphasis>, halfway through the development of the system (this has happened to me).
- Developing mechanisms to isolate session state associated with different concurrent conversations, and
- incorporating failsafes to ensure that conversation state is destroyed when the user aborts one of the
- conversations by closing a browser window or tab is not for the faint hearted (I've implemented this
- stuff twice so far, once for a client application, once for Seam, but I'm famously psychotic). </para>
- <para> Now there is a better way. </para>
- <para> Seam introduces the <emphasis>conversation context</emphasis> as a first class construct. You can
- safely keep conversational state in this context, and be assured that it will have a well-defined
- lifecycle. Even better, you won't need to be continually pushing data back and forth between the
- application server and the database, since the conversation context is a natural cache of data that the
- user is currently working with. </para>
- <para> Usually, the components we keep in the conversation context are stateful session beans. (We can also
- keep entity beans and JavaBeans in the conversation context.) There is an ancient canard in the Java
- community that stateful session beans are a scalability killer. This may have been true in 1998 when
- WebFoobar 1.0 was released. It is no longer true today. Application servers like JBoss AS have extremely
- sophisticated mechanisms for stateful session bean state replication. (For example, the JBoss EJB3
- container performs fine-grained replication, replicating only those bean attribute values which actually
- changed.) Note that all the traditional technical arguments for why stateful beans are inefficient apply
- equally to the <literal>HttpSession</literal>, so the practice of shifting state from business tier
- stateful session bean components to the web session to try and improve performance is unbelievably
- misguided. It is certainly possible to write unscalable applications using stateful session beans, by
- using stateful beans incorrectly, or by using them for the wrong thing. But that doesn't mean you should
- <emphasis>never</emphasis> use them. Anyway, Seam guides you toward a safe usage model. Welcome to
- 2005. </para>
- <para> OK, I'll stop ranting now, and get back to the tutorial. </para>
+ <para>
+ This tutorial concentrates upon one particular piece of functionality: placing a hotel reservation. From the user's perspective, hotel search, selection, booking, and confirmation are one continuous unit of work — a <emphasis>conversation</emphasis>. However, from our perspective, it is important that searching remains separate so that users can select multiple hotels from the same search results page, and open distinct conversations in separate browswer tabs.
+ </para>
+ <para>
+ Most web application architectures do not have first class constructs to represent conversations, which makes managing conversational state problematic. Java web applications generally use a combination of several techniques. Some state is transferred in the URL, but what cannot be transferred here is either added to the <literal>HttpSession</literal> or recorded to the database at the beginning and end of each request.
+ </para>
+ <para>
+ Since the database is the least-scalable tier, this drastically reduces scalability. The extra traffic to and from the database also increases latency. In order to reduce redundant traffic, Java applications often introduce a data cache to store commonly-accessed data between requests. However, since invalidation is based upon an LRU policy, rather than whether the user has finished using the data, this cache is inefficient. It is also shared between concurrent transactions, which introduces further issues associated with keeping the cached state consistent with that of the database.
+ </para>
+ <para>
+ State held in the <literal>HttpSession</literal> suffers similar issues. The <literal>HttpSession</literal> is fine for storing true session data — data common to all requests between user and application — but for data related to individual request series, it does not work so well. Conversations stored here quickly break down when dealing with multiple windows or the back button. Without careful programming, data in the <literal>HttpSession</literal> can also grow quite large, which makes the session difficult to cluster. Developing mechanisms to deal with the problems these methods present (by isolating session state associated with distinct concurrent conversations, and incorporating failsafes to ensure conversation state is destroyed when a conversation is aborted) can be complicated.
+ </para>
+ <para>
+ Seam greatly improves conditions by introducing <emphasis>conversation context</emphasis> as a first class construct. Conversation state is stored safely in this context, with a well-defined lifecycle. Even better, there is no need to push data continually between the application server and the database; the conversation context is a natural cache for currently-used data.
+ </para>
- <para> The booking example application shows how stateful components with different scopes can collaborate
- together to achieve complex behaviors. The main page of the booking application allows the user to
- search for hotels. The search results are kept in the Seam session scope. When the user navigates to one
- of these hotels, a conversation begins, and a conversation scoped component calls back to the session
- scoped component to retrieve the selected hotel. </para>
- <para> The booking example also demonstrates the use of RichFaces Ajax to implement rich client behavior without
- the use of handwritten JavaScript. </para>
+ <para>
+ In the following application, the conversation context is used to store stateful session beans. These are sometimes regarded as detrimental to scalability, and in the past, they may have been. However, modern application servers have sophisticated mechanisms for stateful session bean replication. JBoss AS performs fine-grained replication, replicating only altered bean attribute values. Used correctly, stateful session beans pose no scalability problems, but for those uncomfortable or unfamiliar with the use of stateful session beans, Seam also allows the use of POJOs.
+ </para>
+ <para>
+ The booking example shows one way that stateful components with different scopes can collaborate to achieve complex behaviors. The main page of the booking application allows the user to search for hotels. Search results are stored in the Seam session scope. When the user navigate to a hotel, a conversation begins, and a conversation scoped component retrieves the selected hotel from the session scoped component.
+ </para>
+ <para>
+ The booking example also demonstrates the use of RichFaces Ajax to implement rich client behavior without handwritten JavaScript.
+ </para>
+ <para>
+ The search function is implemented with a session-scoped stateful session bean, similar to the one used in the message list example.
+ </para>
- <para> The search functionality is implemented using a session-scope stateful session bean, similar to the
- one we saw in the message list example above. </para>
<formalpara><title>HotelSearchingAction.java Example</title>
<para>
@@ -2724,7 +2684,7 @@
</programlisting>
- <para> Notice that the example is using page actions for some other functionality—the login
+ <para> Notice that the example is using page actions for some other functionality — the login
challenge, and the pageview counter. Also notice the use of a parameter in the page action method
binding. This is not a standard feature of JSF EL, but Seam lets you use it, not just for page actions,
but also in JSF method bindings. </para>
15 years
- 1
- 0
Seam SVN: r11673 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 03:09:15 -0500 (Tue, 24 Nov 2009)
New Revision: 11673
Modified:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml
Log:
Edited part of Tutorial chapter.
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml 2009-11-24 08:00:17 UTC (rev 11672)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml 2009-11-24 08:09:15 UTC (rev 11673)
@@ -6,29 +6,27 @@
<section id="try-examples">
<title>Try the examples</title>
- <para> In this tutorial, we'll assume that you are using JBoss EAP 4.3.</para>
+ <para> Seam provides a number of example applications which demonstrate how to use a variety of Seam's features. This tutorial will guide you through a few of those examples to help you get started learning Seam. The Seam examples are located in the <filename>examples</filename> subdirectory of the Seam distribution. The first example, on registration, is in the <filename>examples/registration</filename> directory, and so on.</para>
+
+ <para>
+ Each example has the same directory structure:
+ </para>
- <para> The directory structure of each example in Seam follows this pattern: </para>
-
<itemizedlist>
<listitem>
- <para> Web pages, images and stylesheets may be found in
- <filename>examples/<replaceable>registration</replaceable>/view</filename>
+ <para> The <filename>view</filename> directory contains view-related files such as web page templates, images and stylesheets.
</para>
</listitem>
<listitem>
- <para> Resources such as deployment descriptors and data import scripts may be found in
- <filename>examples/<replaceable>registration</replaceable>/resources</filename>
+ <para> The <filename>resources</filename> directory contains deployment descriptors and other configuration files.
</para>
</listitem>
<listitem>
- <para> Java source code may be found in
- <filename>examples/<replaceable>registration</replaceable>/src</filename>
+ <para> The <filename>src</filename> directory contains the application source code.
</para>
</listitem>
<listitem>
- <para> The Ant build script is
- <filename>examples/<replaceable>registration</replaceable>/build.xml</filename>
+ <para> <filename>build.xml</filename> is the Ant script that builds and runs the example.
</para>
</listitem>
</itemizedlist>
@@ -37,10 +35,10 @@
<title>Running the examples on JBoss AS</title>
<para> First, make sure you have Ant correctly installed, with <literal>$ANT_HOME</literal> and
- <literal>$JAVA_HOME</literal> set correctly. Next, make sure you set the location of your EAP embedded JBoss AS
+ <literal>$JAVA_HOME</literal> set correctly. Next, make sure you set the location of your Enterprise Application Platform embedded JBoss AS
installation in the <literal>build.properties</literal> file in the root folder of your Seam
installation, predefined location is /var/lib/jbossas. If you haven't already done so,
- start JBoss EAP AS now by typing <literal>bin/run.sh</literal>
+ start JBoss Enterprise Application Platform AS now by typing <literal>bin/run.sh</literal>
or <literal>bin/run.bat</literal> in the root directory of your JBoss installation. </para>
<para> Now, build and deploy the example by typing <literal>ant deploy</literal> in the
@@ -99,6 +97,7 @@
<emphasis>validation</emphasis> declaratively, via annotations. It also needs some extra
annotations that define the class as a Seam component. </para>
<!-- Can't use code hightlighting with callouts -->
+ <example>
<formalpara><title>User.java Example</title>
<para>
<programlisting role="JAVA"><![CDATA[@Entity
@@ -199,7 +198,7 @@
</orderedlist>
</para>
</formalpara>
-
+</example>
<para> The most important things to notice in this example are the <literal>@Name</literal> and
<literal>@Scope</literal> annotations. These annotations establish that this class is a Seam component. </para>
<para> We'll see below that the properties of our <literal>User</literal> class are bound
15 years
- 1
- 0
Seam SVN: r11672 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 03:00:17 -0500 (Tue, 24 Nov 2009)
New Revision: 11672
Removed:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide_CP02_FP01.ent
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide_CP02_FP01.xml
Log:
Removed old book version files.
Deleted: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide_CP02_FP01.ent
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide_CP02_FP01.ent 2009-11-24 07:59:12 UTC (rev 11671)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide_CP02_FP01.ent 2009-11-24 08:00:17 UTC (rev 11672)
@@ -1,3 +0,0 @@
-<!ENTITY HOLDER "Red Hat, Inc">
-<!ENTITY YEAR "2008">
-<!ENTITY VERSION "4.3.0_CP02_FP01">
Deleted: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide_CP02_FP01.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide_CP02_FP01.xml 2009-11-24 07:59:12 UTC (rev 11671)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide_CP02_FP01.xml 2009-11-24 08:00:17 UTC (rev 11672)
@@ -1,41 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
-
-<book>
- <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Gettingstarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Getting_Started_With_JBoss_Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Migration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Xml.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Conversations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Jbpm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Persistence.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Validation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Groovy.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Drools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "I18n.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Text.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Itext.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Mail.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Jms.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Cache.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Webservices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Remoting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Spring.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Hsearch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Annotations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Components.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Controls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Elenhancements.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href= "Dependencies.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-</book>
15 years
- 1
- 0
Seam SVN: r11671 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 02:59:12 -0500 (Tue, 24 Nov 2009)
New Revision: 11671
Modified:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Spring.xml
Log:
Edited Spring chapter.
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Spring.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Spring.xml 2009-11-24 07:37:05 UTC (rev 11670)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Spring.xml 2009-11-24 07:59:12 UTC (rev 11671)
@@ -11,9 +11,11 @@
<para>Spring integration in Seam is marked as technology preview, so standard support is not guaranteed.</para>
</note>
- <para>Note! The Spring integration code is included in the jboss-seam-ioc library. This dependency is required for
+ <note>
+ <para>The Spring integration code is included in the jboss-seam-ioc library. This dependency is required for
all seam-spring integration techniques covered in this chapter.</para>
-
+ </note>
+
<para>Seam's support for Spring provides the ability to: </para>
<itemizedlist>
@@ -83,18 +85,18 @@
</bean>
]]></programlisting>
- <para>Now for the caveat!</para>
+ <para>
+ However, Spring, unlike Seam, was not designed to support a stateful component model with multiple contexts. Spring injection does not occur at method invocation time, but when the Spring bean is instantiated.
+ </para>
+
+ <para>
+ The instance available when the bean is instantiated will be used for the entire life of the bean. Say you inject a Seam conversation-scoped component instance directly into a singleton Spring bean — that singleton will hold a reference to the same instance long after the conversation is over. This is called scope <emphasis>impedance</emphasis>.
+ </para>
+
+ <para>
+ Seam bijection maintains scope impedance naturally as an invocation flows through the system. In Spring, we must inject a proxy of the Seam component, and resolve the reference when the proxy is invoked.
+ </para>
- <para> Seam was designed from the ground up to support a stateful component model with multiple contexts. Spring
- was not. Unlike Seam bijection, Spring injection does not occur at method invocation time. Instead,
- injection happens only when the Spring bean is instantiated. So the instance available when the bean is
- instantiated will be the same instance that the bean uses for the entire life of the bean. For example, if a
- Seam <literal>CONVERSATION</literal>-scoped component instance is directly injected into a singleton Spring
- bean, that singleton will hold a reference to the same instance long after the conversation is over! We call
- this problem <emphasis>scope impedance</emphasis>. Seam bijection ensures that scope impedance is maintained
- naturally as an invocation flows through the system. In Spring, we need to inject a proxy of the Seam
- component, and resolve the reference when the proxy is invoked.</para>
-
<para>The <literal><seam:instance/></literal> tag lets us automatically proxy the Seam component.</para>
<programlisting role="XML"><![CDATA[<seam:instance id="seamManagedEM" name="someManagedEMComponent" proxy="true"/>
@@ -106,7 +108,7 @@
<para> This example shows one way to use a Seam-managed persistence context from a Spring bean. (For a more robust
way to use Seam-managed persistence contexts as a replacement for the Spring
<literal>OpenEntityManagerInView</literal> filter see section on
- <xref linkend="spring-persistence"/>Using a Seam Managed Persistence Context in Spring)</para>
+ <xref linkend="spring-persistence"/>.</para>
</section>
<section>
@@ -197,7 +199,7 @@
<para> The prefix of the scope name may be changed by specifying the <literal>prefix</literal> attribute in the
<literal>configure-scopes</literal> definition. (The default prefix is <literal>seam.</literal>) </para>
- <para> By default an instance of a Spring Component registered in this way is not automatically created when
+ <para> By default an instance of a Spring component registered in this way is not automatically created when
referenced using <literal>@In</literal>. To have an instance auto-created you must either specify <literal>@In(create=true)</literal>
at the injection point to identify a specific bean to be auto created or you can use the <literal>default-auto-create</literal>
attribute of <literal>configure-scopes</literal> to make all spring beans who use a seam scope auto created.</para>
@@ -228,9 +230,9 @@
transaction APIs (JPA, Hibernate, JDO, and JTA) Spring also provides tight integrations with many application
server TransactionManagers such as Websphere and Weblogic. Spring
transaction management exposes support for many advanced features such as nested
- transactions and supports full Java EE transaction propagation rules like REQUIRES_NEW and NOT_SUPPORTED. For more
+ transactions and supports full Java EE transaction propagation rules like REQUIRES_NEW and NOT_SUPPORTED. <!--For more
information see the spring documentation
- <ulink url="http://static.springframework.org/spring/docs/2.0.x/reference/transaction...">here.</ulink></para>
+ <ulink url="http://static.springframework.org/spring/docs/2.0.x/reference/transaction...">here.</ulink>--></para>
<para>To configure Seam to use Spring transactions enable the SpringTransaction component like so:</para>
@@ -251,7 +253,7 @@
an persistence context beyond the scope of a single web request
(<literal>OpenEntityManagerInViewFilter</literal>). So, it would be nice if Spring developers
could have access to a Seam managed persistence context using all of the same tools Spring provides
- for integration with JPA(e.g. <literal>PersistenceAnnotationBeanPostProcessor</literal>,
+ for integration with JPA (for example, <literal>PersistenceAnnotationBeanPostProcessor</literal>,
<literal>JpaTemplate</literal>, etc.)</para>
<para>Seam provides a way for Spring to access a Seam managed persistence context with
@@ -282,8 +284,8 @@
<property name="persistenceContextName" value="entityManager"/>
</bean>]]></programlisting>
- <para>Where 'persistenceContextName' is the name of the Seam managed persistence context component. By default
- this EntityManagerFactory has a unitName equal to the Seam component name or in this case 'entityManager'.
+ <para>Where <literal>persistenceContextName</literal> is the name of the Seam managed persistence context component. By default
+ this EntityManagerFactory has a unitName equal to the Seam component name or in this case <literal>entityManager</literal>.
If you wish to provide a different unitName you can do so by providing a persistenceUnitName like so:
</para>
@@ -330,18 +332,15 @@
<title>Using a Seam Managed Hibernate Session in Spring</title>
<para>The Seam Spring integration also provides support for complete access to a Seam managed Hibernate session
- using spring's tools. This integration is very similar to the <xref linkend="spring-persistence"/>JPA integration.</para>
+ using spring's tools. This integration is very similar to the <xref linkend="spring-persistence"/>.</para>
- <para>Like Spring's JPA integration spring's propagation model allows only one open EntityManager per
- EntityManagerFactory per transaction??? to be available to spring tools. So, the Seam Session integration works
- by wrapping a proxy SessionFactory around a Seam managed Hibernate session
- context.</para>
+ <para>Spring's propagation model allows only one open <literal>EntityManager</literal> per <literal>EntityManagerFactory</literal> to be available to Spring tools, so Seam integrates by wrapping a proxy <literal>SessionFactory</literal> around a Seam-managed Hibernate session context. </para>
<programlisting role="XML"><![CDATA[<bean id="seamSessionFactory" class="org.jboss.seam.ioc.spring.SeamManagedSessionFactoryBean">
<property name="sessionName" value="hibernateSession"/>
</bean>]]></programlisting>
- <para>Where 'sessionName' is the name of the <literal>persistence:managed-hibernate-session</literal> component.
+ <para>Where <literal>sessionName</literal> is the name of the <literal>persistence:managed-hibernate-session</literal> component.
This SessionFactory can then be used in any Spring provided tools. The integration
also provides support for calls to <literal>SessionFactory.getCurrentInstance()</literal> as long as you call
getCurrentInstance() on the <literal>SeamManagedSessionFactory</literal>.</para>
@@ -389,7 +388,7 @@
<para>Spring provides an abstraction for executing code asynchronously called a <literal>TaskExecutor</literal>.
The Spring Seam integration allows for the use of a Spring <literal>TaskExecutor</literal> for executing
immediate <literal>@Asynchronous</literal> method calls. To enable this functionality install the
- <literal>SpringTaskExecutorDispatchor</literal> and provide a spring bean defined taskExecutor like so:</para>
+ <literal>SpringTaskExecutorDispatcher</literal> and provide a spring bean defined taskExecutor like so:</para>
<programlisting role="XML"><![CDATA[<spring:task-executor-dispatcher task-executor="#{springThreadPoolTaskExecutor}"/>]]></programlisting>
15 years
- 1
- 0
Seam SVN: r11670 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 02:37:05 -0500 (Tue, 24 Nov 2009)
New Revision: 11670
Modified:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Testing.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Text.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Validation.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Webservices.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Xml.xml
Log:
Edited testing, text, tools, validation, webservices and xml chapters.
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Testing.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Testing.xml 2009-11-24 07:35:44 UTC (rev 11669)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Testing.xml 2009-11-24 07:37:05 UTC (rev 11670)
@@ -3,7 +3,7 @@
<para>
Most Seam applications will need at least two kinds of automated tests:
<emphasis>unit tests</emphasis>, which test a particular Seam component
- in isolation, and scripted <emphasis>integration tests</emphasis> which
+ in isolation, and <emphasis>scripted integration tests</emphasis> which
exercise all Java layers of the application (that is, everything except the
view pages).
</para>
@@ -15,7 +15,7 @@
<title>Unit testing Seam components</title>
<para>
All Seam components are POJOs. This is a great place to start if you
- want easy unit testing. And since Seam emphasises the use of bijection
+ want easy unit testing. And since Seam emphasises the use of bijection
for inter-component interactions and access to contextual objects, it's
very easy to test a Seam component outside of its normal runtime
environment.
@@ -76,11 +76,11 @@
]]></programlisting>
<para>
- You'll notice we aren't testing retrieving data from or persisting
- data to the database; nor are we testing any functionality
- provided by Seam. We are just testing the logic of our POJOs. Seam
- components don't usually depend directly upon container infrastructure,
- so most unit testing as as easy as that!
+ In this case, we aren't testing retrieving data from the database, or
+ pushing data to it; nor are we testing any functionality provided
+ by Seam. We are just testing the logic of our POJOs. Seam components
+ don't usually depend directly upon container infrastructure,
+ so most unit testing is a simple process.
</para>
<para>
However, if you want to test the entire application, read on.
@@ -93,18 +93,16 @@
<para>
Integration testing is slightly more difficult. In this case, we can't eliminate
- the container infrastructure; indeed, that is part of what is being tested! At
- the same time, we don't want to be forced to deploy our application to an
- application server to run the automated tests. We need to be able to reproduce
- just enough of the container infrastructure inside our testing environment to be
- able to exercise the whole application, without hurting performance too much.
+ the container infrastructure, as it is also being tested. At the same time, we don't
+ want to be forced to deploy our application to an application server to run the
+ automated tests. We need to be able to reproduce just enough of the container
+ infrastructure inside our testing environment to be able to exercise the whole
+ application, without hurting performance too much.
</para>
<para>
- The approach taken by Seam is to let you write tests that exercise your
- components while running inside a pruned down container environment (Seam,
- together with the JBoss Embedded container; n.b. JBoss Embedded requires
- JDK 1.5 and does not work with JDK 1.6).
+ Seam allows you to test your components while running inside a pruned down container environment. This environment, incorporating Seam and the JBoss Embedded Container, requires JDK 1.5, and does not work with
+ JDK 1.6.
</para>
<programlisting role="JAVA"><![CDATA[public class RegisterTest extends SeamTest
@@ -143,7 +141,7 @@
Occasionally, we need to be able to replace the implementation of some
Seam component that depends upon resources which are not available in
the integration test environment. For example, suppose we have some
- Seam component which is a facade to some payment processing system:
+ Seam component which is a facade to a payment processing system:
</para>
<programlisting role="JAVA"><![CDATA[@Name("paymentProcessor")
@@ -176,20 +174,19 @@
</section>
<section>
- <title>Integration testing Seam application user interactions</title>
+ <title>Integration testing Seam application User Interactions</title>
<para>
- An even harder problem is emulating user interactions. A third problem is where
- to put our assertions. Some test frameworks let us test the whole application
- by reproducing user interactions with the web browser. These frameworks have
- their place, but they are not appropriate for use at development time.
+ Emulating user interactions is a difficult, as is correctly placing our assertions.
+ Some test frameworks let us test the whole application by reproducing user
+ interactions with the web browser. These frameworks have their place, but are not
+ appropriate for use at development time.
</para>
<para>
<literal>SeamTest</literal> lets you write <emphasis>scripted</emphasis> tests,
in a simulated JSF environment. The role of a scripted test is to reproduce
- the interaction between the view and the Seam components. In other words, you
- get to pretend you are the JSF implementation!
+ the interaction between the view and the Seam components.
</para>
<para>
@@ -283,7 +280,7 @@
}]]></programlisting>
<para>
- Notice that we've extended <literal>SeamTest</literal>, which provides a
+ We have extended <literal>SeamTest</literal>, which provides a
Seam environment for our components, and written our test script as an
anonymous class that extends <literal>SeamTest.FacesRequest</literal>,
which provides an emulated JSF request lifecycle. (There is also a
@@ -296,7 +293,7 @@
<para>
You'll find plenty of integration tests for the Seam example applications
which demonstrate more complex cases. There are instructions for running
- these tests using Ant, or using the TestNG plugin for eclipse:
+ these tests using Ant, or using the TestNG plugin for Eclipse:
</para>
<mediaobject>
@@ -436,17 +433,17 @@
dependencies from <literal>lib/</literal> (e.g.
<literal>jboss-system.jar</literal>) on the classpath, these
will cause Embedded JBoss to not boot. So, just add the
- dependencies (e.g. Drools, jBPM)you need as you go.
+ dependencies (e.g. Drools, jBPM) you need as you go.
</para>
<para>
You also need to include the <literal>bootstrap/</literal>
- directory on the classpath; <literal>bootstrap/</literal> contains
+ directory on the classpath. <literal>Bootstrap/</literal> contains
the configuration for Embedded JBoss.
</para>
<para>
- And, of course you need to put your built project and tests onto
+ You also need to put your built project and tests onto
the classpath. Don't forget to put all the correct configuration
files for JPA and Seam onto the classpath as well.Seam asks
Embedded JBoss to deploy any resource (jar or directory)
@@ -458,7 +455,7 @@
<para>
By default, a generated project will use the
- <literal>java:/DefaultDS</literal> (a built in HSQL datasource in
+ <literal>java:/DefaultDS</literal> (a built-in HSQL datasource in
Embedded JBoss) for testing. If you want to use another datasource
place the <literal>foo-ds.xml</literal> into
<literal>bootstrap/deploy</literal> directory.
@@ -471,7 +468,7 @@
<para>
Seam provides TestNG support out of the box, but you can also use
- another test framework, such as JUnit, if you want.
+ another test framework, such as JUnit, if you prefer.
</para>
<para>
@@ -532,7 +529,7 @@
<para>
You need to provide a dataset for DBUnit. IMPORTANT NOTE: DBUnit supports two
formats for dataset files, flat and XML. Seam's DBUnitSeamTest assumes the flat
- format is used, so please ensure that your dataset is in this format also.
+ format is used, so please ensure that your dataset is in this format:
</para>
<programlisting role="XML"><![CDATA[<dataset>
@@ -550,7 +547,7 @@
</dataset>]]></programlisting>
<para>
- and tell Seam about it by overriding <literal>prepareDBUnitOperations()</literal>:
+ Then override the <literal>prepareDBUnitOperations()</literal> to announce the changes to Seam:
</para>
<programlisting role="JAVA"><![CDATA[protected void prepareDBUnitOperations() {
@@ -644,4 +641,4 @@
</section>
-</chapter>
\ No newline at end of file
+</chapter>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Text.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Text.xml 2009-11-24 07:35:44 UTC (rev 11669)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Text.xml 2009-11-24 07:37:05 UTC (rev 11670)
@@ -43,7 +43,7 @@
This is the second paragraph.]]></programlisting>
<para>
- (Note that a simple newline is ignored, you need an additional blank line to wrap text into a new paragraph.)
+ A simple newline will be ignored, and you need an additional blank line to wrap text into a new paragraph.
This is the HTML that results:
</para>
@@ -220,10 +220,6 @@
<tr><td>Last name:</td><td>King</td></tr>
</table>]]></programlisting>
- <para>
- But you can do much more if you want!
- </para>
-
</section>
-</chapter>
\ No newline at end of file
+</chapter>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Validation.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Validation.xml 2009-11-24 07:35:44 UTC (rev 11669)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Validation.xml 2009-11-24 07:37:05 UTC (rev 11670)
@@ -105,7 +105,7 @@
<para>
<emphasis>Note:</emphasis> specifying <literal>@NotNull</literal>
on the model does <emphasis>not</emphasis> eliminate the requirement
- for <literal>required="true"</literal> to appear on the control!
+ for <literal>required="true"</literal> to appear on the control.
This is due to a limitation of the JSF validation architecture.
</para>
@@ -144,8 +144,7 @@
<para>
This tag simply adds an <literal><s:validate></literal>
- to every input in the form. For a large form, it can save a lot
- of typing!
+ to every input in the form.
</para>
<para>
@@ -248,7 +247,7 @@
<para>
It's better style to define explicit ids for
important controls on the page, especially if you want to do
- automated testing for the UI, using some toolkit like
+ automated testing for the UI, using a toolkit like
Selenium. If you don't provide explicit ids, JSF will generate
them, but the generated values will change if you change
anything on the page.
@@ -277,10 +276,9 @@
</h:form>]]></programlisting>
<para>
- And what if you want to specify a different message to be
- displayed when validation fails? You can use the Seam message
- bundle (and all it's goodies like el expressions inside the message,
- and per-view message bundles) with the Hibernate Validator:
+ You can use the Seam message bundle (and all it's goodies like el expressions inside the message,
+ and per-view message bundles) with the Hibernate Validator to specify a different
+ message to be displayed when validation fails:
</para>
<programlisting role="JAVA"><![CDATA[public class Location {
@@ -300,4 +298,4 @@
location.zipCode.invalid = The zip code is not valid for #{location.name}
</programlisting>
-</chapter>
\ No newline at end of file
+</chapter>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Webservices.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Webservices.xml 2009-11-24 07:35:44 UTC (rev 11669)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Webservices.xml 2009-11-24 07:37:05 UTC (rev 11670)
@@ -45,9 +45,7 @@
<section>
<title>Conversational Web Services</title>
<para>
- So how are conversations propagated between web service requests? Seam uses a SOAP header element present
- in both the SOAP request and response messages to carry the conversation ID from the consumer to the service,
- and back again. Here's an example of a web service request that contains a conversation ID:
+ Seam uses a SOAP header element present in both the SOAP request and response messages to carry the conversation ID from the consumer to the service, and back again. Below is an example of a web service request that contains a conversation ID:
</para>
<programlisting role="XML"><![CDATA[<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
@@ -72,7 +70,7 @@
<para>
An important thing to note is that the <literal>conversationId</literal> header element must be qualified
with a namespace of <literal>http://www.jboss.org/seam/webservice</literal>, otherwise Seam will not be
- able to read the conversation ID from the request. Here's an example of a response to the above request message:
+ able to read the conversation ID from the request. Below is an example of a response to the above request message:
</para>
<programlisting role="XML"><![CDATA[<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Xml.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Xml.xml 2009-11-24 07:35:44 UTC (rev 11669)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Xml.xml 2009-11-24 07:37:05 UTC (rev 11670)
@@ -1,12 +1,13 @@
<chapter id="xml">
- <title>Configuring Seam components</title>
+ <title>Configuring Seam Components</title>
<para>
The philosophy of minimizing XML-based configuration is extremely strong in Seam. Nevertheless,
there are various reasons why we might want to configure a Seam component using XML: to isolate
deployment-specific information from the Java code, to enable the creation of re-usable frameworks,
to configure Seam's built-in functionality, etc.
+ </para><para>
Seam provides two basic approaches to configuring components: configuration via property settings in a
properties file or in <literal>web.xml</literal>, and configuration via <literal>components.xml</literal>.
</para>
@@ -38,8 +39,8 @@
<title>Configuring components via <literal>components.xml</literal></title>
<para>
- The <literal>components.xml</literal> file is a bit more powerful than property settings. It lets
- you:
+ The <literal>components.xml</literal> file is a bit more powerful than property settings. It allows
+ you to:
</para>
<itemizedlist>
@@ -92,8 +93,11 @@
</para>
<para>
- For example, the following <literal>components.xml</literal> file installs jBPM:
+ For example, the following three examples install jBPM:
</para>
+ <para>
+ Example One:
+ </para>
<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -102,7 +106,7 @@
</components>]]></programlisting>
<para>
- This example does the same thing:
+ Example Two:
</para>
<programlisting role="XML"><![CDATA[<components>
@@ -125,7 +129,7 @@
</components>]]></programlisting>
<para>
- As does this one:
+ Example Three:
</para>
<programlisting role="XML"><![CDATA[<components>
@@ -203,7 +207,7 @@
</components>]]></programlisting>
<para>
- You can create an "alias" (a second name) for a Seam component like so:
+ You can create an alias for a Seam component like so:
</para>
<programlisting role="XML"><![CDATA[<components>
@@ -213,7 +217,7 @@
</components>]]></programlisting>
<para>
- You can even create an "alias" for a commonly used expression:
+ You can even create an alias for a commonly used expression:
</para>
<programlisting role="XML"><![CDATA[<components>
@@ -334,7 +338,7 @@
<para>
Finally, you may wire together components using a value-binding expression. Note that this is quite
- different to injection using <literal>@In</literal>, since it happens at component instantiation time
+ different to injection using <literal>@In</literal>, since it happens at component creation time
instead of invocation time. It is therefore much more similar to the dependency injection facilities
offered by traditional IoC containers like JSF or Spring.
</para>
@@ -396,9 +400,8 @@
<para>
Now, this works great for the built-in Seam components, but what about user components? There are two options.
- First, Seam supports mixing the two models, allowing the use of the generic <literal><component></literal>
- declarations for user components, along with namespaced declarations for built-in components. But even better,
- Seam allows you to quickly declare namespaces for your own components.
+ Firstly, Seam supports mixing the two models, allowing the use of the generic <literal><component></literal>
+ declarations for user components, along with namespaced declarations for built-in components. Secondly, Seam allows you to quickly declare namespaces for your own components.
</para>
<para>
15 years
- 1
- 0
Seam SVN: r11669 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 02:35:44 -0500 (Tue, 24 Nov 2009)
New Revision: 11669
Modified:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Security.xml
Log:
Edited Security chapter.
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Security.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Security.xml 2009-11-24 07:14:11 UTC (rev 11668)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Security.xml 2009-11-24 07:35:44 UTC (rev 11669)
@@ -41,7 +41,7 @@
</para>
<para>
- If on the other hand, your application requires security checks based on contextual state or complex business rules,
+ If, on the other hand, your application requires security checks based on contextual state or complex business rules,
then you will require the features provided by the advanced mode.
</para>
</section>
@@ -112,7 +112,7 @@
<para>
The authentication features provided by Seam Security are built upon JAAS (Java Authentication and Authorization Service),
and as such provide a robust and highly configurable API for handling user authentication. However, for less complex
- authentication requirements Seam offers a much more simplified method of authentication that hides the complexity of JAAS.
+ authentication requirements Seam offers a simpler authentication method that hides the complexity of JAAS.
</para>
<section>
@@ -324,7 +324,7 @@
<para>
To prevent users from receiving the default error page in response to a security error, it's recommended that
- <literal>pages.xml</literal> is configured to redirect security errors to a more "pretty" page. The two
+ <literal>pages.xml</literal> is configured to redirect security errors to a more attractive page. The two
main types of exceptions thrown by the security API are:
</para>
@@ -394,8 +394,8 @@
</pages>]]></programlisting>
<para>
- (This is less of a blunt instrument than the exception handler shown above, but should
- probably be used in conjunction with it.)
+ This is more refined than the previous exception handler, but should
+ probably be used in conjunction with it.
</para>
<para>
@@ -1045,8 +1045,7 @@
<para>
So how does the security API know whether a user has the <literal>customer:modify</literal> permission
- for a specific customer? Seam Security provides quite a novel method for determining user permissions,
- based on JBoss Rules. A couple of the advantages of using a rule engine are 1) a centralized location
+ for a specific customer? Seam Security determines permissions based on JBoss Rules. Some advantages of using a rule engine are 1) a centralized location
for the business logic that is behind each user permission, and 2) speed - JBoss Rules uses very efficient
algorithms for evaluating large numbers of complex rules involving multiple conditions.
</para>
@@ -1146,9 +1145,9 @@
<programlisting><![CDATA[c: PermissionCheck(name == "customer", action == "delete")]]></programlisting>
<para>
- In plain english, this condition is stating that there must exist a <literal>PermissionCheck</literal> object
+ This condition specifies that a <literal>PermissionCheck</literal> object
with a <literal>name</literal> property equal to "customer", and an <literal>action</literal> property equal
- to "delete" within the working memory.
+ to "delete" must exist within the working memory.
</para>
<para>
15 years
- 1
- 0
Seam SVN: r11668 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 02:14:11 -0500 (Tue, 24 Nov 2009)
New Revision: 11668
Modified:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Remoting.xml
Log:
Edited Remoting chapter.
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Remoting.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Remoting.xml 2009-11-24 07:06:18 UTC (rev 11667)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Remoting.xml 2009-11-24 07:14:11 UTC (rev 11668)
@@ -726,7 +726,7 @@
Javascript if desired. The following example demonstrates how to configure the polling to occur much more
aggressively. You should set these parameters to suitable values for your application: </para>
- <para> Via components.xml: </para>
+ <para> Via <filename>components.xml</filename>: </para>
<programlisting role="XML"><![CDATA[<remoting:remoting poll-timeout="5" poll-interval="1"/>]]></programlisting>
15 years
- 1
- 0
Seam SVN: r11667 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 02:06:18 -0500 (Tue, 24 Nov 2009)
New Revision: 11667
Modified:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Conversations.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Dependencies.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Elenhancements.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Framework.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Gettingstarted.xml
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Remoting.xml
Log:
Edited chapters for CP07.
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Conversations.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Conversations.xml 2009-11-24 06:41:27 UTC (rev 11666)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Conversations.xml 2009-11-24 07:06:18 UTC (rev 11667)
@@ -15,29 +15,18 @@
</para>
<itemizedlist>
- <listitem>
- <para>
- The idea of a <emphasis>workspace</emphasis>, which I
- encountered in a project for the Victorian government in
- 2002. In this project I was forced to implement workspace
- management on top of Struts, an experience I pray never
- to repeat.
+ <listitem>
+ <para>
+ The idea of a <emphasis>workspace</emphasis>.
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
The idea of an <emphasis>application transaction</emphasis>
with optimistic semantics, and the realization that existing
frameworks based around a stateless architecture could not
provide effective management of extended persistence contexts.
- (The Hibernate team is truly fed up with copping the blame for
- <literal>LazyInitializationException</literal>s, which are
- not really Hibernate's fault, but rather the fault of the
- extremely limiting persistence context model supported by
- stateless architectures such as the Spring framework or the
- traditional <emphasis>stateless session facade</emphasis>
- (anti)pattern in J2EE.)
- </para>
+ </para>
</listitem>
<listitem>
<para>
@@ -49,7 +38,7 @@
<para>
By unifying these ideas and providing deep support in the framework,
we have a powerful construct that lets us build richer and more efficient
- applications with less code than before.
+ applications with less code.
</para>
<section>
@@ -170,7 +159,7 @@
</h:commandLink>]]></programlisting>
<para>
- Note that disabling conversation context propagation is absolutely not the
+ Note that disabling conversation context propagation is not the
same thing as ending the conversation.
</para>
@@ -587,8 +576,8 @@
</quote>
</para>
<para>
- With a natural conversation its really easy to have the user
- rejoin the existing conversation, and pick up where they left
+ With a natural conversation it is easy to have the user
+ rejoin the existing conversation and pick up where they left
off - just have them to rejoin the payForItem conversation
with the itemId as the conversation id.
</para>
@@ -598,28 +587,20 @@
</para>
<para>
- For me this consists of a navigable
- hierarchy (I can navigate by editing the url) and a meaningful
- URL (like this Wiki uses - so don't identify things by random
- ids). For some applications user friendly URLs are less
+ This consists of a navigable
+ hierarchy (which can be navigated by editing the url) and a meaningful
+ URL. For some applications user-friendly URLs are less
important, of course.
</para>
<para>
- With a natural conversations, when you are building your hotel
- booking system (or, of course, whatever your app is) you can
- generate a URL like
+ With a natural conversations you can generate a URL like
<literal>http://seam-hotels/book.seam?hotel=BestWesternAntwerpen</literal>
(of course, whatever parameter <literal>hotel</literal> maps
to on your domain model must be unique) and with URLRewrite
easily transform this to
http://seam-hotels/book/BestWesternAntwerpen.
</para>
-
- <para>
- Much better!
- </para>
-
</section>
<section>
<title>Creating a natural conversation</title>
@@ -692,7 +673,7 @@
<para>
From here, we can see that invoking the action <literal>#{bidAction.placeBid}</literal>
- from our auction view (by the way, all these examples are taken from the seamBay example in Seam),
+ from our auction view (all examples are taken from the seamBay example in Seam),
that we will be redirected to <literal>/bid.xhtml</literal>, which, as we saw previously,
is configured with the natural conversation <literal>PlaceBid</literal>. The declaration for
our action method looks like this:
@@ -749,7 +730,7 @@
Include one or more of the standard workspace switcher JSP
or facelets fragments in your pages. The standard fragments
support workspace management via a drop down menu, a list
- of conversations, or breadcrumbs.
+ of conversations or breadcrumbs.
</para>
</listitem>
</itemizedlist>
@@ -782,7 +763,7 @@
<para>
Note that if this file is missing, the Seam application will
- continue to work perfectly! The only missing functionality
+ continue to work. The only missing functionality
will be the ability to switch workspaces.
</para>
@@ -833,7 +814,7 @@
<para>
Include the following fragment in your JSP or facelets page
to get a drop-down menu that lets you switch to any
- current conversation, or to any other page of the application:
+ current conversation or to any other page of the application:
</para>
<programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{switcher.conversationIdOrOutcome}">
@@ -953,8 +934,8 @@
<para>
Conversational components have one minor limitation: they cannot be used to hold bindings
- to JSF components. (We generally prefer not to use this feature of JSF unless absolutely
- necessary, since it creates a hard dependency from application logic to the view.) On a
+ to JSF components. It is best to not to use this feature unless absolutely necessary
+ as it creates a hard dependency from application logic to the view. On a
postback request, component bindings are updated during the Restore View phase,
before the Seam conversation context has been restored.
</para>
@@ -1029,21 +1010,19 @@
Conversational components don't allow real concurrent access therefore
Seam queues each request to process them serially. This allows each
request to be executed in a deterministic fashion. However, a simple
- queue isn't that great — firstly, if a method is, for some
- reason, taking a very long time to complete, running it over and over
- again whenever the client generates a request is bad idea (potential
- for Denial of Service attacks), and, secondly, AJAX is often to used
- to provide a quick status update to the user, so continuing to run the
- action after a long time isn't useful.
+ queue is not optimal — firstly, if a method is taking a very long
+ time to complete, running it repeatedly whenever the client generates a
+ request creates the potential for Denial of Service attacks), and,
+ secondly, AJAX is often to used to provide a quick status update to the
+ user, so continuing to run the action after a long time is not effective.
</para>
<para>
Therefore, when you are working inside a long running conversation,
Seam queues the action event for a period of time (the concurrent
request timeout); if it can't process the event in time, it creates a
- temporary conversation and prints out a message to the user to let them
- know what's going on. It's therefore very important not to flood the
- server with AJAX events!
+ temporary conversation and prints out a message to the user to inform them.
+ It is therefore important not to flood the server with AJAX events.
</para>
<para>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Dependencies.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Dependencies.xml 2009-11-24 06:41:27 UTC (rev 11666)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Dependencies.xml 2009-11-24 07:06:18 UTC (rev 11667)
@@ -907,7 +907,7 @@
<para>
- Maven offers support for transitive dependency management and can be used
+ <application>Maven</application> offers support for transitive dependency management and can be used
to manage the dependencies of your Seam project. You can use Maven Ant
Tasks to integrate Maven into your Ant build, or can use Maven to build and
deploy your project.
@@ -919,8 +919,8 @@
</para>
<para>
- Released versions of Seam are available in http://repository.jboss.org/maven2
- and nightly snapshots are available in http://snapshots.jboss.org/maven2.
+ Released versions of Seam are available in <ulink type="http" url="http://repository.jboss.org/maven2"></ulink>
+ and nightly snapshots are available in <ulink type="http" url="http://snapshots.jboss.org/maven2"></ulink>.
</para>
<para>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Elenhancements.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Elenhancements.xml 2009-11-24 06:41:27 UTC (rev 11666)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Elenhancements.xml 2009-11-24 07:06:18 UTC (rev 11667)
@@ -62,14 +62,14 @@
are stored (for example, <literal>hotel.id</literal> and
<literal>user.username</literal>), and evaluated (as value
expressions) when the page is submitted. You can't pass objects as
- parameters!
+ parameters.
</para>
<para>
You must ensure that the parameters are available not only when the
- page is rendered, but also when it is submittedIf the arguments can
+ page is rendered, but also when it is submitted. If the arguments can
not be resolved when the page is submitted the action method will be
- called with <literal>null</literal> arguments!
+ called with <literal>null</literal> arguments.
</para>
<para>
@@ -173,8 +173,7 @@
types are passed in by JSF. In the case of a method binding,
JSF assumes that there are no parameters to pass. With this
extension, we can't know the parameter types until after the
- expression has been evaluated. This has two minor
- consequences:
+ expression has been evaluated. This has two consequences:
</para>
<itemizedlist>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Framework.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Framework.xml 2009-11-24 06:41:27 UTC (rev 11666)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Framework.xml 2009-11-24 07:06:18 UTC (rev 11667)
@@ -51,8 +51,7 @@
</framework:entity-home>]]></programlisting>
<para>
- If that looks a bit too much like "programming in XML" for
- your taste, you can use extension instead:
+ If you prefer, you can use extension instead:
</para>
<programlisting role="JAVA"><![CDATA[
@@ -68,8 +67,8 @@
}]]></programlisting>
<para>
- The second approach has one huge advantage: you can easily add
- extra functionality, and override the built-in functionality
+ The second approach has the advantage of allowing you to easily add
+ extra functionality and override the built-in functionality
(the framework classes were carefully designed for extension
and customization).
</para>
@@ -183,9 +182,9 @@
</h:form>]]></programlisting>
<para>
- Usually, it is much nicer to be able to refer to the <literal>Person</literal>
- merely as <literal>person</literal>, so let's make that possible by adding a
- line to <literal>components.xml</literal>:
+ Usually, it is preferable to be able to refer to the <literal>Person</literal>
+ merely as <literal>person</literal>. Adding a line to
+ <literal>components.xml</literal> makes this possible:
</para>
<programlisting role="XML"><![CDATA[<factory name="person"
@@ -262,8 +261,8 @@
</para>
<para>
- Suppose we need to create <literal>Person</literal> entries with their
- nationality initialized. We can do that easily, via configuration:
+ Should we need to create <literal>Person</literal> entries with their
+ nationality initialized, we can do so easily, via configuration:
</para>
<programlisting role="XML"><![CDATA[<factory name="person"
@@ -391,14 +390,13 @@
Person_updated=Person #{person.firstName} #{person.lastName} updated]]></programlisting>
<para>
- This enables internationalization, and keeps your code and configuration clean of
+ This enables internationalization and keeps your code and configuration clean of
presentation concerns.
</para>
<para>
- The final step is to add validation functionality to the page, using
- <literal><s:validateAll></literal> and <literal><s:decorate></literal>,
- but I'll leave that for you to figure out.
+ The final step is to add validation functionality to the page using
+ <literal><s:validateAll></literal> and <literal><s:decorate></literal>.
</para>
</section>
@@ -593,10 +591,6 @@
}]]></programlisting>
- <para>
- As you can see, its not an earthshattering improvement...
- </para>
-
</section>
-</chapter>
\ No newline at end of file
+</chapter>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml 2009-11-24 06:41:27 UTC (rev 11666)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml 2009-11-24 07:06:18 UTC (rev 11667)
@@ -13,10 +13,6 @@
</para>
<para>
- In short, if you are an Eclipse user, then you'll want JBoss Tools!
- </para>
-
- <para>
JBoss Tools, as with seam-gen, works best with JBoss AS, but it's possible
with a few tweaks to get your app running on other application servers.
The changes are much like those described for seam-gen later in this
@@ -57,9 +53,7 @@
<para>
First, enter a name for your new project. For this tutorial, we're
- going to use
- <literal>helloworld</literal>
- .
+ going to use <literal>helloworld</literal>.
</para>
@@ -299,7 +293,7 @@
<para>
Finally, review the package names for your generated beans, and if you
- are happy, click <emphasis>Finish</emphasis>:
+ are satisfied, click <emphasis>Finish</emphasis>:
</para>
<mediaobject>
@@ -367,11 +361,11 @@
</imageobject>
</mediaobject>
- <para>
+<!-- <para>
If you don't want to bother with this stuff now, you don't have to—come
back to it later, when you get your first
<literal>OutOfMemoryException</literal>.
- </para>
+ </para> -->
<para>
To start JBoss, and deploy the project, just right click on the server
@@ -391,10 +385,9 @@
</mediaobject>
<para>
- Don't get scared by the XML configuration documents that were generated
- into the project directory. They are mostly standard Java EE stuff, the
- stuff you need to create once and then never look at again, and they
- are 90% the same between all Seam projects.
+ The XML configuration documents generated in the project directory are
+ predominately standard Java EE. They are 90% the same between all Seam
+ projects.
</para>
</section>
@@ -560,10 +553,9 @@
<para>
Then go to <literal>http://localhost:8080/helloworld</literal>. You can
- browse the database, edit existing objects, and create new objects. If
- you look at the generated code, you'll probably be amazed how simple it
- is! Seam was designed so that data access code is easy to write by
- hand, even for people who don't want to cheat by using reverse
+ browse the database, edit existing objects, and create new objects.
+ Seam was designed so that data access code is easy to write by
+ hand, even for people who don't want to use reverse
engineering.
</para>
</section>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Gettingstarted.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Gettingstarted.xml 2009-11-24 06:41:27 UTC (rev 11666)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Gettingstarted.xml 2009-11-24 07:06:18 UTC (rev 11667)
@@ -4,21 +4,17 @@
<chapter id="gettingstarted">
<title>Getting started with Seam, using seam-gen</title>
- <para>The Seam distribution includes a command line utility that makes it really easy to set up an Eclipse project,
- generate some simple Seam skeleton code, and reverse engineer an application from a preexisting database.</para>
+ <para>The Seam distribution includes a command line utility that makes it easy to set up an Eclipse project,
+ generate some simple Seam skeleton code and reverse engineer an application from a preexisting database.</para>
- <para>This is the easy way to get your feet wet with Seam, and gives you some ammunition for next time you find
- yourself trapped in an elevator with one of those tedious Ruby guys ranting about how great and wonderful his
- new toy is for building totally trivial applications that put things in databases.</para>
-
- <para>In this release, seam-gen works best for people with JBoss AS. You can use the generated project with other
+ <para>In this release, seam-gen works best for people with JBoss AS. You can use the generated project with other
J2EE or Java EE 5 application servers by making a few manual changes to the project configuration.</para>
<para>You <emphasis>can</emphasis> use seam-gen without Eclipse, but in this tutorial, we want to show you how to
use it in conjunction with Eclipse for debugging and integration testing. If you don't want to install Eclipse,
you can still follow along with this tutorial—all steps can be performed from the command line.</para>
- <para>Seam-gen is basically just a big ugly Ant script wrapped around Hibernate Tools, together with some templates.
+ <para>Seam-gen is basically just an Ant script wrapped around Hibernate Tools together with some templates.
That makes it easy to customize if you need to.</para>
<section>
@@ -44,8 +40,6 @@
<para>If you're running JBoss from the command line, you can configure the JVM options in
<literal>bin/run.conf</literal>.</para>
- <para>If you don't want to bother with this stuff now, you don't have to—come back to it later, when you get
- your first <literal>OutOfMemoryException</literal>.</para>
</section>
<section>
@@ -166,9 +160,11 @@
You can edit this page, or the template, in eclipse, and see the results <emphasis>immediately</emphasis>,
by clicking refresh in your browser.</para>
- <para>Don't get scared by the XML configuration documents that were generated into the project directory. They
- are mostly standard Java EE stuff, the stuff you need to create once and then never look at again, and they
- are 90% the same between all Seam projects. (They are so easy to write that even seam-gen can do it.)</para>
+ <para>
+ The XML configuration documents generated in the project directory are
+ predominately standard Java EE. They are 90% the same between all Seam
+ projects.
+ </para>
<para>The generated project includes three database and persistence configurations. The
<literal>persistence-test.xml</literal> and
@@ -360,7 +356,7 @@
this may be accomplished by touching the top level deployment descriptor: <literal>application.xml</literal>
for an EAR deployment, or <literal>web.xml</literal> for a WAR deployment.)</para>
- <para>But if you really want a fast edit/compile/test cycle, Seam supports incremental redeployment of JavaBean
+ <para>If you want a fast edit/compile/test cycle, Seam supports incremental redeployment of JavaBean
components. To make use of this functionality, you must deploy the JavaBean components into the
<literal>WEB-INF/dev</literal> directory, so that they will be loaded by a special Seam classloader,
instead of by the WAR or EAR classloader.</para>
@@ -369,8 +365,8 @@
<itemizedlist>
<listitem>
- <para>the components must be JavaBean components, they cannot be EJB3 beans (we are working on fixing
- this limitation)</para>
+ <para>the components must be JavaBean components, they cannot be EJB3 beans.
+ (This limitation is being worked on.)</para>
</listitem>
<listitem>
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Remoting.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Remoting.xml 2009-11-24 06:41:27 UTC (rev 11666)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Remoting.xml 2009-11-24 07:06:18 UTC (rev 11667)
@@ -3,11 +3,9 @@
<chapter id="remoting">
<title>Remoting</title>
- <para> Seam provides a convenient method of remotely accessing components from a web page, using AJAX (Asynchronous
- Javascript and XML). The framework for this functionality is provided with almost no up-front development effort -
- your components only require simple annotating to become accessible via AJAX. This chapter describes the steps
- required to build an AJAX-enabled web page, then goes on to explain the features of the Seam Remoting framework in
- more detail. </para>
+ <para>
+ Seam uses Asynchronous JavaScript and XML (AJAX) to remotely access components from a web page. The framework for this functionality requires very little development effort — you can make your components AJAX-accessible with simple annotations. This chapter describes the steps required to build an AJAX-enabled web page, and explains the Seam Remoting framework in further detail.
+ </para>
<section>
<title>Configuration</title>
@@ -114,15 +112,13 @@
// ]]>]]><![CDATA[
</script>]]></programlisting>
- <para> We're done! Deploy your application and browse to your page. Click the button, and enter a name when
- prompted. A message box will display the hello message confirming that the call was successful. If you want to
- save some time, you'll find the full source code for this Hello World example in Seam's
- <literal>/examples/remoting/helloworld</literal> directory. </para>
+ <para>
+ Now deploy your application and browse to your page. Click the button, and enter a name when prompted. A message box will display the "Hello" message, confirming the call's success. (You can find the full source code for this Hello World example in Seam's <filename>/examples/remoting/helloworld</filename> directory.)
+ </para>
- <para> So what does the code of our script actually do? Let's break it down into smaller pieces. To start with,
- you can see from the Javascript code listing that we have implemented two methods - the first method is
- responsible for prompting the user for their name and then making a remote request. Take a look at the following
- line: </para>
+ <para>
+ You can see from the JavaScript code listing that we have implemented two methods. The first method prompts the user for their name, and makes a remote request. Look at the following line:
+ </para>
<programlisting role="XHTML">Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);</programlisting>
@@ -131,16 +127,13 @@
against this stub, which is exactly what happens with the remainder of the line: <literal>sayHello(name,
sayHelloCallback);</literal>. </para>
- <para> What this line of code in its completeness does, is invoke the <literal>sayHello</literal> method of our
- component, passing in <literal>name</literal> as a parameter. The second parameter,
- <literal>sayHelloCallback</literal> isn't a parameter of our component's <literal>sayHello</literal> method,
- instead it tells the Seam Remoting framework that once it receives the response to our request, it should pass
- it to the <literal>sayHelloCallback</literal> Javascript method. This callback parameter is entirely optional,
- so feel free to leave it out if you're calling a method with a <literal>void</literal> return type or if you
- don't care about the result. </para>
+ <para>
+ The whole line invokes the <literal>sayHello</literal> method of our component, passing in name as a parameter. The second parameter, <literal>sayHelloCallback</literal>, is not a parameter of our component's <literal>sayHello</literal> method — it tells the Seam Remoting framework that, once a response to the request is received, the response should be passed to the <literal>sayHelloCallback</literal> JavaScript method. (This callback parameter is optional; you can leave it out if you are calling a method with a void return type, or if the result of the request is not important.)
+ </para>
- <para> The <literal>sayHelloCallback</literal> method, once receiving the response to our remote request then pops
- up an alert message displaying the result of our method call. </para>
+ <para>
+ When the sayHelloCallback method receives the response to our remote request, it displays an alert message with the result of our method call.
+ </para>
</section>
@@ -243,10 +236,9 @@
<section>
<title>Seam.Remoting.createType()</title>
- <para> If your application contains or uses Javabean classes that aren't Seam components, you may need to create
- these types on the client side to pass as parameters into your component method. Use the
- <literal>createType()</literal> method to create an instance of your type. Pass in the fully qualified Java
- class name as a parameter: </para>
+ <para>
+ If your application contains or uses JavaBean classes that are not Seam components, you may need to create these types on the client side to pass as parameters into your component method. Use the <methodname>createType()</methodname> method to create an instance of your type. Pass in the fully-qualified Java class name as a parameter:
+ </para>
<programlisting role="XHTML">var widget = Seam.Remoting.createType("com.acme.widgets.MyWidget");</programlisting>
</section>
@@ -313,12 +305,9 @@
stubs are behavioural, and are used to execute methods against your session bean components, while type stubs
contain state and represent the types that can be passed in as parameters or returned as a result. </para>
- <para> The type of client stub that is generated depends on the type of your Seam component. If the component is a
- session bean, then an executable stub will be generated, otherwise if it's an entity or JavaBean, then a type stub
- will be generated. There is one exception to this rule; if your component is a JavaBean (ie it is not a session
- bean nor an entity bean) and any of its methods are annotated with @WebRemote, then an executable stub will be
- generated for it instead of a type stub. This allows you to use remoting to call methods of your JavaBean
- components in a non-EJB environment where you don't have access to session beans. </para>
+ <para>
+ The type of stub that is generated depends upon the type of your Seam component. If the component is a session bean, an executable stub will be generated. If it is an entity or JavaBean, a type stub will be generated. However, if your component is a JavaBean and any of its methods are annotated with <literal>@WebRemote</literal>, an executable stub will be generated. This lets you call your JavaBean component's methods in a non-EJB environment, where you do not have access to session beans.
+ </para>
</section>
@@ -337,19 +326,16 @@
call <literal>Seam.Remoting.getContext().getConversationId()</literal>. To set the conversation ID before making a
request, call <literal>Seam.Remoting.getContext().setConversationId()</literal>. </para>
- <para> If the conversation ID hasn't been explicitly set with
- <literal>Seam.Remoting.getContext().setConversationId()</literal>, then it will be automatically assigned the
- first valid conversation ID that is returned by any remoting call. If you are working with multiple conversations
- within your page, then you may need to explicitly set the conversation ID before each call. If you are working
- with just a single conversation, then you don't need to do anything special. </para>
+ <para>
+ If the conversation ID has not been explicitly set with Seam.Remoting.getContext().setConversationId(), then the first valid conversation ID returned by any remoting call is assigned automatically. If you are working with multiple conversations within your page, you may need to set your conversation ID explicitly before each call. Single conversations do not require explicit ID setting.
+ </para>
</section>
<section>
<title>Remote calls within the current conversation scope</title>
- <para> In some circumstances it may be required to make a remote call within the scope of the
- current view's conversation. To do this, you must explicitly set the conversation ID to that
- of the view before making the remote call. This small snippet of JavaScript will set the
- conversation ID that is used for remoting calls to the current view's conversation ID: </para>
+ <para>
+ Under some circumstances, you may need to make a remote call within the scope of the current view's conversation. To do so, you must explicitly set the conversation ID to that of the view before making the remote call. The following JavaScript will set the conversation ID being used for remote calls to the current view's conversation ID:
+ </para>
<programlisting role="XHTML"><![CDATA[Seam.Remoting.getContext().setConversationId( #{conversation.id} );]]></programlisting>
</section>
15 years
- 1
- 0
Seam SVN: r11666 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 01:41:27 -0500 (Tue, 24 Nov 2009)
New Revision: 11666
Modified:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Persistence.xml
Log:
Edited Persistence chapter.
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Persistence.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Persistence.xml 2009-11-24 05:55:24 UTC (rev 11665)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Persistence.xml 2009-11-24 06:41:27 UTC (rev 11666)
@@ -13,28 +13,26 @@
<title>Introduction</title>
<para>
- Seam grew out of the frustration of the Hibernate team with the
- statelessness typical of the previous generation of Java application
- architectures. The state management architecture of Seam was originally
- designed to solve problems relating to persistence—in particular
- problems associated with <emphasis>optimistic transaction processing</emphasis>.
- Scalable online applications always use optimistic transactions. An atomic
- (database/JTA) level transaction should not span a user interaction unless
- the application is designed to support only a very small number of concurrent
- clients. But almost all interesting work involves first displaying data
- to a user, and then, slightly later, updating the same data. So Hibernate was
- designed to support the idea of a persistence context which spanned an
- optimistic transaction.
+
+ Seam was created because of frustration with the statelessness typical of the
+ previous generation of Java application architectures. Seam's state management
+ architecture was originally designed to solve problems relating to persistence,
+ particularly problems associated with optimistic transaction processing. Scalable
+ online applications always use optimistic transactions. An atomic (database/JTA)
+ level transaction should not span a user interaction unless the application is
+ designed to support only a very small number of concurrent clients. But almost all
+ work involves first displaying data to a user, and then updating that data.
+ Hibernate was designed to support a persistence context that spanned an optimistic
+ transaction.
</para>
<para>
- Unfortunately, the so-called "stateless" architectures that preceded Seam and
- EJB 3.0 had no construct for representing an optimistic transaction. So, instead,
- these architectures provided persistence contexts scoped to the atomic
- transaction. Of course, this resulted in many problems for users, and is the
- cause of the number one user complaint about Hibernate: the dreaded
- <literal>LazyInitializationException</literal>. What we need is a construct
- for representing an optimistic transaction in the application tier.
+ Unfortunately, the "stateless" architectures that preceded Seam and EJB3 had no
+ construct to represent an optimistic transaction. Instead, these architectures
+ provided persistence contexts scoped to the atomic transaction. This resulted in
+ many problems for users, and causes the number one user complaint: Hibernate's
+ <exceptionname>LazyInitializationException</exceptionname>. A construct was
+ required to represent an optimistic transaction in the application tier.
</para>
<para>
@@ -42,15 +40,14 @@
component (a stateful session bean) with an <emphasis>extended persistence
context</emphasis> scoped to the lifetime of the component. This is a
partial solution to the problem (and is a useful construct in and of
- itself) however there are two problems:
+ itself), but there are still two issues with this approach:
</para>
<itemizedlist>
<listitem>
<para>
The lifecycle of the stateful session bean must be managed manually
- via code in the web tier (it turns out that this is a subtle problem
- and much more difficult in practice than it sounds).
+ via code in the web tier.
</para>
</listitem>
<listitem>
@@ -62,16 +59,15 @@
</itemizedlist>
<para>
- Seam solves the first problem by providing conversations, and stateful
- session bean components scoped to the conversation. (Most conversations
- actually represent optimistic transactions in the data layer.) This is
- sufficient for many simple applications (such as the Seam booking
- demo) where persistence context propagation is not needed. For more
- complex applications, with many loosly-interacting components in each
- conversation, propagation of the persistence context across components
- becomes an important issue. So Seam extends the persistence context
- management model of EJB 3.0, to provide conversation-scoped extended
- persistence contexts.
+ Seam solves the first problem by providing conversations, and scoping stateful
+ session bean components to the conversation. (Most conversations actually
+ represent optimistic transactions in the data layer.) This is sufficient for many
+ simple applications where persistence context propagation is not required, such as
+ the Seam booking example application. For more complex applications, with many
+ loosely-interacting components in each conversation, propagation of the
+ persistence context across components becomes an important issue. Therefore, Seam
+ extends the persistence context management model of EJB3, to provide conversation-
+ scoped extended persistence contexts.
</para>
</section>
@@ -79,96 +75,93 @@
<section id="persistence.seam-managed-transactions">
<title>Seam managed transactions</title>
<para>
- EJB session beans feature declarative transaction management. The EJB container is able
- to start a transaction transparently when the bean is invoked, and end it when the
- invocation ends. If we write a session bean method that acts as a JSF action listener,
- we can do all the work associated with that action in one transaction, and be sure that
- it is committed or rolled back when we finish processing the action. This is a great feature,
- and all that is needed by some Seam applications.
+ EEJB session beans feature declarative transaction management. The EJB
+ container can start a transaction transparently when the bean is invoked, and
+ end it when the invocation ends. If we write a session bean method that acts
+ as a JSF action listener, all work associated with that action can be
+ performed as one transaction, and committed or rolled back when the action is
+ completely processed. This is a useful feature, and for some Seam
+ applications, this is all that is required.
</para>
<para>
- However, there is a problem with this approach. A Seam application may not perform all data
- access for a request from a single method call to a session bean.
+ However, there is a problem with this approach: in a request from a single
+ method call to a session bean, a Seam application may not perform all data
+ access.
</para>
<itemizedlist>
<listitem>
<para>
- The request might require processing by several loosly-coupled components, each
- of which is called independently from the web layer. It is common to see several
- or even many calls per request from the web layer to EJB components in Seam.
+ when the request requires processing by several loosely-coupled
+ components, with each component being called independently from the
+ web layer. It is common to see multiple calls per request from the web
+ layer to EJB components in Seam.
</para>
</listitem>
<listitem>
<para>
- Rendering of the view might require lazy fetching of associations.
+ when view rendering requires lazily-fetched associations.
</para>
</listitem>
</itemizedlist>
<para>
- The more transactions per request, the more likely we are to encounter atomicity
- and isolation problems when our application is processing many concurrent requests.
- Certainly, all write operations should occur in the same transaction!
+ The more transactions that exist per request, the more likely we are to
+ encounter atomicity and isolation problems while our application processes
+ many concurrent requests. All write operations should occur in the same
+ transaction.
</para>
<para>
- Hibernate users developed the <emphasis>"open session in view"</emphasis> pattern to work
- around this problem. In the Hibernate community, "open session in view" was historically
- even more important because frameworks like Spring use transaction-scoped persistence contexts.
- So rendering the view would cause <literal>LazyInitializationException</literal>s when
- unfetched associations were accessed.
+ To work around this problem, Hibernate users developed the <emphasis>open
+ session in view</emphasis> pattern. This is also important because some
+ frameworks (Spring, for example) use transaction-scoped persistence contexts,
+ which caused <exceptionname>LazyInitializationException</exceptionname>s when
+ unfetched associations were accessed.
</para>
<para>
- This pattern is usually implemented as a single transaction which spans the entire request.
- There are several problems with this implementation, the most serious being that we
- can never be sure that a transaction is successful until we commit it—but by the
- time the "open session in view" transaction is committed, the view is fully rendered, and
- the rendered response may already have been flushed to the client. How can we notify the
- user that their transaction was unsuccessful?
+ <emphasis>Open session in view</emphasis> is usually implemented as a single
+ transaction that spans the entire request. The most serious problem with this
+ implementation is that we cannot be certain that a transaction is successful
+ until we commit it — but when the transaction commits, the view is fully
+ rendered, and the rendered response may already be synchronized the client, so
+ there is no way to notify the user that their transaction did not succeed.
</para>
<para>
- Seam solves both the transaction isolation problem and the association fetching problem,
- while working around the problems with "open session in view". The solution comes in two
- parts:
+ Seam solves the problems with transaction isolation and association fetching,
+ while working around the major flaw in <emphasis>open session in
+ view</emphasis>, with two changes:
</para>
<itemizedlist>
<listitem>
<para>
- use an extended persistence context that is scoped to the conversation,
- instead of to the transaction
+ Seam uses an extended persistence context that is scoped to the
+ conversation instead of the transaction.
</para>
</listitem>
<listitem>
<para>
- use two transactions per request; the first spans the beginning of the restore view
- phase (some transaction managers begin the transaction later at the beginning of the
- apply request vaues phase) until the end of the invoke application phase; the second spans the
- render response phase
+ Seam uses two transactions per request. The first spans from the
+ beginning of the restore view phase until the end of the invoke
+ application phase; the second spans the length of the render response
+ phase. (In some applications, the first phase will begin later, at the
+ beginning of the apply request values phase.)
</para>
</listitem>
</itemizedlist>
<para>
- In the next section, we'll tell you how to set up a conversation-scope persistence
- context. But first we need to tell you how to enable Seam transaction management.
- Note that you can use conversation-scoped persistence contexts without Seam
- transaction management, and there are good reasons to use Seam transaction management
- even when you're not using Seam-managed persistence contexts. However, the two
- facilities were designed to work together, and work best when used together.
+ The next section takes you through the setup of a conversation-scoped
+ persistence context. Before this, we will enable Seam transaction management.
+ You can use conversation-scoped persistence contexts without Seam transaction
+ management, and Seam transaction management is useful even without Seam-
+ managed persistence contexts, but they work most effectively together.
</para>
- <para>
- Seam transaction management is useful even if you're using EJB 3.0
- container-managed persistence contexts. But it is especially useful
- if you use Seam outside a Java EE 5 environment, or in any other
- case where you would use a Seam-managed persistence context.
- </para>
-
<section>
<title>Disabling Seam-managed transactions</title>
@@ -197,7 +190,7 @@
<programlisting role="XML"><![CDATA[<transaction:ejb-transaction />]]></programlisting>
<para>
- However, if you are working in a non EE 5 container, Seam will try auto detect the transaction
+ However, if you are working in a non EE 5 container, Seam will try to auto detect the transaction
synchronization mechanism to use. However, if Seam is unable to detect the correct transaction
synchronization to use, you may find you need configure one of the following:
</para>
@@ -234,23 +227,23 @@
</listitem>
</itemizedlist>
<para>
- Configure JPA RESOURCE_LOCAL transaction management by adding the following to your components.xml where
+ Configure JPA RESOURCE_LOCAL transaction management by adding the following to your <filename>components.xml</filename> where
<literal>#{em}</literal>
is the name of the
<literal>persistence:managed-persistence-context</literal>
component. If your managed persistence context is named <literal>entityManager</literal>, you can
opt to leave out the <literal>entity-manager</literal> attribute. (see
- <xref linkend="persistence.seam-managed-persistence-contexts"/>Seam-managed persistence contexts)
+ <xref linkend="persistence.seam-managed-persistence-contexts"/>.)
</para>
<programlisting role="XML"><![CDATA[<transaction:entity-transaction entity-manager="#{em}"/>]]></programlisting>
<para>
- To configure Hibernate managed transactions declare the following in your components.xml where
+ To configure Hibernate managed transactions declare the following in your <filename>components.xml</filename> where
<literal>#{hibernateSession}</literal>
is the name of the project's
<literal>persistence:managed-hibernate-session</literal>
component. If your managed hibernate session is named <literal>session</literal>, you can
- opt to leave out the <literal>session</literal> attribute. (see
- <xref linkend="persistence.seam-managed-persistence-contexts"/>Seam-managed persistence contexts)
+ opt to leave out the <literal>session</literal> attribute. (See
+ <xref linkend="persistence.seam-managed-persistence-contexts"/>.)
</para>
<programlisting role="XML"><![CDATA[<transaction:hibernate-transaction session="#{hibernateSession}"/>]]></programlisting>
<para>
@@ -259,8 +252,7 @@
<programlisting role="XML"><![CDATA[<transaction:no-transaction />]]></programlisting>
<para>
For configuring Spring managed transactions see
- <xref linkend="spring-transactions"/>using Spring PlatformTransactionManagement.
- .
+ <xref linkend="spring-transactions"/>.
</para>
</section>
<section>
@@ -283,29 +275,24 @@
<title>Seam-managed persistence contexts</title>
<para>
- If you're using Seam outside of a Java EE 5 environment, you can't rely upon the
- container to manage the persistence context lifecycle for you. Even if you are
- in an EE 5 environment, you might have a complex application with many loosly
- coupled components that collaborate together in the scope of a single conversation,
- and in this case you might find that propagation of the persistence context between
- component is tricky and error-prone.
+ If you use Seam outside a Java EE 5 environment, you cannot rely upon the
+ container to manage the persistence context lifestyle. Even within EE 5
+ environments, propagating the persistence context between loosely-coupled
+ components in a complex application can be difficult and error-prone.
</para>
<para>
- In either case, you'll need to use a <emphasis>managed persistence context</emphasis>
- (for JPA) or a <emphasis>managed session</emphasis> (for Hibernate) in your components.
- A Seam-managed persistence context is just a built-in Seam component that manages an
- instance of <literal>EntityManager</literal> or <literal>Session</literal> in the
- conversation context. You can inject it with <literal>@In</literal>.
+ In this case, you will need to use a <emphasis>managed persistence context</emphasis> (for JPA) or a <emphasis>managed session</emphasis> (for Hibernate) in your components. A Seam-managed persistence context is just a built-in Seam component that manages an instance of <literal>EntityManager</literal> or <literal>Session</literal> in the conversation context. You can inject it with <literal>@In</literal>.
+
</para>
<para>
- Seam-managed persistence contexts are extremely efficient in a clustered environment.
- Seam is able to perform an optimization that EJB 3.0 specification does not allow
- containers to use for container-managed extended persistence contexts. Seam supports
- transparent failover of extended persisence contexts, without the need to replicate
- any persistence context state between nodes. (We hope to fix this oversight in the
- next revision of the EJB spec.)
+ Seam-managed persistence contexts are extremely efficient in a clustered
+ environment. Seam can perform optimizations for container-managed persistence
+ contexts that the EJB3 specification does not allow. Seam supports transparent
+ failover of extended persistence contexts, without replicating any persistence
+ context state between nodes. (We hope to add this support to the next revision
+ of the EJB specification.)
</para>
<section>
@@ -381,13 +368,14 @@
<property name="connection.datasource">java:/bookingDatasource</property>
...
</session-factory>]]></programlisting>
-
+ <note>
<para>
- Note that Seam does not flush the session, so you should always enable
- <literal>hibernate.transaction.flush_before_completion</literal> to
- ensure that the session is automatically flushed before the JTA transaction
- commits.
+ Seam does not synchronize the session with the database, so always enable
+ <literal>hibernate.transaction.flush_before_completion</literal> to ensure
+ that the session is automatically synchronized before the JTA transaction
+ commits.
</para>
+ </note>
<para>
We can now have a managed Hibernate <literal>Session</literal> injected into our
@@ -417,17 +405,13 @@
</para>
<para>
- By default, the persistence context is flushed (synchronized with the database)
- at the end of each transaction. This is sometimes the desired behavior. But very
- often, we would prefer that all changes are held in memory and only written to
- the database when the conversation ends successfully. This allows for truly
- atomic conversations. As the result of a truly stupid and shortsighted decision
- by certain non-JBoss, non-Sun and non-Sybase members of the EJB 3.0 expert group,
- there is currently no simple, usable and portable way to implement atomic
- conversations using EJB 3.0 persistence. However, Hibernate provides this feature
- as a vendor extension to the <literal>FlushModeType</literal>s defined by the
- specification, and it is our expectation that other vendors will soon provide
- a similar extension.
+ By default, the persistence context is synchronized with the database
+ (flushed) at the end of each transaction. Sometimes this is desirable, but
+ often we prefer all changes to be held in memory, and only written to the
+ database when the conversation ends successfully. This allows for truly atomic
+ conversations with EJB3 persistence. However, Hibernate provides this feature
+ as a vendor extension to the <literal>FlushModeTypes</literal> defined by the specification. We
+ expect other vendors will soon provide a similar extension.
</para>
<para>
@@ -478,19 +462,11 @@
<title>Using the JPA "delegate"</title>
<para>
- The <literal>EntityManager</literal> interface lets you access a vendor-specific
- API via the <literal>getDelegate()</literal> method. Naturally, the most interesting
- vendor is Hibernate, and the most powerful delegate interface is
- <literal>org.hibernate.Session</literal>. You'd be nuts to use anything else. Trust
- me, I'm not biased at all. If you must use a different JPA provider see
- <xref linkend="alt-jpa-providers"/>Using Alternate JPA Providers.
+ The <literal>EntityManager</literal> interface lets you access a vendor-specific API with the <literal>getDelegate()</literal> method. We recommend using Hibernate as your vendor, and <literal>org.hibernate.Session</literal> as your delegate interface, but if you require a different JPA provider, <xref linkend="alt-jpa-providers"/> for further information.
</para>
<para>
- But regardless of whether you're using Hibernate (genius!) or something else
- (masochist, or just not very bright), you'll almost certainly want to use the
- delegate in your Seam components from time to time. One approach would be the
- following:
+ Regardless of your vendor, there are several approaches to using the delegate in your Seam components. One approach is:
</para>
<programlisting role="JAVA"><![CDATA[@In EntityManager entityManager;
@@ -501,9 +477,7 @@
}]]></programlisting>
<para>
- But typecasts are unquestionably the ugliest syntax in the Java language, so most
- people avoid them whenever possible. Here's a different way to get at the
- delegate. First, add the following line to <literal>components.xml</literal>:
+ If you, like most Java users, would rather avoid using typecasts, you can also access the delegate by adding the following line to <filename>components.xml</filename>:
</para>
<programlisting role="XML"><![CDATA[<factory name="session"
@@ -542,17 +516,19 @@
<programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=:username")
.setParameter("username", user.getUsername())
.getSingleResult();]]></programlisting>
-
+
+ <warning>
<para>
- Of course, you should never, ever write it like this:
+ This should never be written as:
</para>
- <programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=" + user.getUsername()) //BAD!
+ <programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=" + user.getUsername())
.getSingleResult();]]></programlisting>
<para>
- (It is inefficient and vulnerable to SQL injection attacks.)
+ This is inefficient, but more importantly, it is vulnerable to SQL injection attacks.
</para>
+ </warning>
</section>
@@ -560,18 +536,11 @@
<title>Using Hibernate filters</title>
<para>
- The coolest, and most unique, feature of Hibernate is <emphasis>filters</emphasis>.
- Filters let you provide a restricted view of the data in the database. You can find
- out more about filters in the Hibernate documentation. But we thought we'd mention
- an easy way to incorporate filters into a Seam application, one that works especially
- well with the Seam Application Framework.
+ Hibernate's most unique, useful feature is the filter. Filters provide a restricted view of the data in the database. You can find more information in the Hibernate documentation, but this section takes you through one easy, effective method of incorporating filters into Seam.
</para>
<para>
- Seam-managed persistence contexts may have a list of filters defined, which will be
- enabled whenever an <literal>EntityManager</literal> or Hibernate <literal>Session</literal>
- is first created. (Of course, they may only be used when Hibernate is the underlying
- persistence provider.)
+ Seam-managed persistence contexts can have a list of filters defined, which will be enabled whenever an <literal>EntityManager</literal> or Hibernate <literal>Session</literal> is first created. (These can only be used when Hibernate is the underlying persistence provider.)
</para>
<programlisting role="XML"><![CDATA[<persistence:filter name="regionFilter">
15 years
- 1
- 0
Seam SVN: r11665 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.
by seam-commits＠lists.jboss.org
Author: laubai
Date: 2009-11-24 00:55:24 -0500 (Tue, 24 Nov 2009)
New Revision: 11665
Modified:
tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Migration.xml
Log:
Edited Migration chapter.
Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Migration.xml
===================================================================
--- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Migration.xml 2009-11-24 05:27:45 UTC (rev 11664)
+++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Migration.xml 2009-11-24 05:55:24 UTC (rev 11665)
@@ -11,13 +11,13 @@
is to create a new project using seam-gen in Seam 2, and migrate your code
across. We recognize that many projects may have extensive customizations
to their project, so we also provide instructions for how to upgrade your
- project in-situ in <xref linkend="migrating.insitu" /> Due to the number
+ project in-situ in <xref linkend="migrating.insitu" />. Due to the number
of changes introduced between Seam 1.2 and Seam 2, this may not always be
a straightforward process!
</para>
<para>
- However you decide to migrate your application, you'll need to alter your
+ However you decide to migrate your application, you will need to alter your
code, as many components have moved. <xref linkend="migrating.general"/>
details those changes.
</para>
@@ -26,7 +26,7 @@
<title>Creating a new project skeleton using seam-gen</title>
<para>
- Start by creating a new skeleton seam project. In your Seam 2
+ Start by creating a new skeleton Seam project. In your Seam 2
directory run:
</para>
@@ -34,7 +34,7 @@
<para>
Customize the defaults as needed. You'll want to set the location of
- JBoss EAP, name your project and select an EAR or WAR as needed; you
+ JBoss Enterprise Application Platform, name your project and select an EAR or WAR as needed; you
can accept the defaults for Java package names (as we aren't going to
use the reverse engineering features of seam-gen); you'll want to set
your JDBC driver, URL, username and password correctly, and configure
@@ -69,13 +69,13 @@
<warning>
<para>
You only need to do this if you are migrating from the community
- edition of Seam, JBoss EAP 4.2 and 4.3 shipped a version of Seam
+ edition of Seam. JBoss Enterprise Application Platform 4.2 and 4.3 shipped a version of Seam
1.2 which used JSF 1.2.
</para>
</warning>
<para>
- Seam 2.0 requires JSF 1.2, and JBoss EAP supports Sun's JSF RI. To
+ Seam 2.0 requires JSF 1.2, and JBoss Enterprise Application Platform supports Sun's JSF RI. To
switch to JSF 1.2, you need to remove the MyFaces listener:
</para>
@@ -117,8 +117,8 @@
</web-app>]]></programlisting>
<para>
- In your Seam 1.2 app you may have specified some Seam specific
- configuration in <literal>web.xml</literal>. First, we'll discuss
+ In your Seam 1.2 application you may have specified some Seam specific
+ configuration in <literal>web.xml</literal>. First, we'll discuss
all the Seam related elements you need in
<literal>web.xml</literal>, not just those that have changed, noting
any changes.
@@ -134,8 +134,7 @@
</listener>]]></programlisting>
<para>
- Modify the Seam master filter (note the package of the class
- changed):
+ Modify the Seam master filter (note the change to the class package):
</para>
<programlisting role="XML"><![CDATA[<filter>
@@ -170,7 +169,7 @@
</servlet-mapping>]]></programlisting>
<para>
- Seam 2 will automatically install RichFaces' Ajax4JSF if it present
+ Seam 2 will automatically install RichFaces Ajax4JSF if it present
in your project so you should make sure the Ajax4JSF filter isn't
declared:
</para>
@@ -295,7 +294,7 @@
</para>
<para>
- For testing, you need the jars in Seam's <literal>lib/test</literal>,
+ For testing, you need the jars in Seam's <literal>lib/test</literal> directory,
the jars in Seam's <literal>lib/</literal> directory, your test
classes and application classes together with the
<literal>bootstrap/</literal> directory in your classpath.
@@ -341,7 +340,7 @@
<important>
<para>
- Don't forget to update the XSD's in <literal>pages.xml</literal> and
+ Don't forget to update the XSDs in <literal>pages.xml</literal> and
<literal>components.xml</literal> to point at the ones for Seam 2.
Just change the suffix from <literal>-1.2.xsd</literal> to
<literal>-2.0.xsd</literal>.
@@ -353,7 +352,7 @@
<para>
Seam's built-in components have undergone a major reorganization
- designed to organize them for easier learning, and to isolate
+ designed to make them easier to learn, and to isolate
dependencies upon particular technologies like JSF into specific
packages.
</para>
@@ -406,13 +405,13 @@
</listitem>
<listitem>
<para>
- The Pageflow component are located in
+ The Pageflow components are located in
<literal>org.jboss.seam.pageflow</literal>
</para>
</listitem>
<listitem>
<para>
- The Pages component are located in
+ The Pages components are located in
<literal>org.jboss.seam.navigation</literal>
</para>
</listitem>
@@ -1047,7 +1046,7 @@
<title>Annotation changes in Seam 2</title>
<para>
- Annotations have also moved to reflect their purpose. In
+ Annotations have also moved to reflect their purpose.
</para>
<itemizedlist>
@@ -1209,7 +1208,7 @@
</listitem>
<listitem>
<para>
- Exception handling annotations moved to
+ Annotations related to exception handling have moved to
<literal>org.jboss.seam.annotations.exception</literal>
</para>
<itemizedlist>
@@ -1284,7 +1283,7 @@
<para>
If you are using jBPM for business processes,
- you need to add the tx service to <literal>jbpm.cfg.xml</literal>:
+ you need to add the <classname>tx</classname> service to <literal>jbpm.cfg.xml</literal>:
</para>
<programlisting role="XML"><![CDATA[<service name="tx" factory="org.jbpm.tx.TxServiceFactory" />]]></programlisting>
@@ -1318,7 +1317,7 @@
to the data picker from your stylesheet to save on unnecessary bandwidth use.
</para>
<para>
- You should check the RichFaces documentation for more information on
+ Check the RichFaces documentation for more information on
parameter name changes and namespace changes.
</para>
@@ -1354,7 +1353,7 @@
<title>Changes to seam-gen</title>
<para>There was a change in seam-gen regarding
- how the generated classes are organized when generate-entities is
+ how generated classes are organized when generate-entities is
executed.</para>
<variablelist>
15 years
- 1
- 0