[jboss-cvs] JBossAS SVN: r84083 - projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Feb 10 21:46:19 EST 2009
Author: irooskov at redhat.com
Date: 2009-02-10 21:46:19 -0500 (Tue, 10 Feb 2009)
New Revision: 84083
Modified:
projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Concepts.xml
projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Conversations.xml
projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Events.xml
projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml
projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Gettingstarted.xml
projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Introduction.xml
projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Migration.xml
projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Tutorial.xml
Log:
updated guide with editorial corrections for JBPAPP-1583
Modified: projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Concepts.xml
===================================================================
--- projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Concepts.xml 2009-02-11 02:06:04 UTC (rev 84082)
+++ projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Concepts.xml 2009-02-11 02:46:19 UTC (rev 84083)
@@ -12,7 +12,7 @@
</para>
<para>
- Let's start by describing the contexts built in to Seam.
+ Let us start by describing the contexts built in to Seam.
</para>
<sect1>
@@ -58,7 +58,7 @@
</para>
<para>
- Let's look at each context in turn.
+ Let us look at each context in turn.
</para>
<sect2>
@@ -73,7 +73,7 @@
<sect2>
<title>Event context</title>
<para>
- The event context is the "narrowest" stateful context, and is a generalization of the notion of the
+ The event context is the <emphasis>narrowest</emphasis> stateful context, and is a generalization of the notion of the
web request context to cover other kinds of events. Nevertheless, the event context associated with the
lifecycle of a JSF request is the most important example of an event context, and the one you will work
with most often. Components associated with the event context are destroyed at the end of the request,
@@ -103,20 +103,19 @@
The conversation context is a truly central concept in Seam. A <emphasis>conversation</emphasis> is a
unit of work from the point of view of the user. It might span several interactions with the user,
several requests, and several database transactions. But to the user, a conversation solves a single
- problem. For example, "book hotel", "approve contract", "create order" are all conversations. You might
- like to think of a conversation implementing a single "use case" or "user story", but the relationship
+ problem. For example, <emphasis>book hotel</emphasis>, <emphasis>approve contract</emphasis>, <emphasis>create order</emphasis> are all conversations. You might
+ like to think of a conversation implementing a single <emphasis>use case</emphasis> or <emphasis>user story</emphasis>, but the relationship
is not necessarily quite exact.
</para>
<para>
- A conversation holds state associated with "what the user is doing now, in this window". A single
+ A conversation holds state associated with <emphasis>what the user is doing now, in this window</emphasis>. A single
user may have multiple conversations in progress at any point in time, usually in multiple windows. The
conversation context allows us to ensure that state from the different conversations does not collide
and cause bugs.
</para>
<para>
- It might take you some time to get used to thinking of applications in terms of conversations. But
- once you get used to it, we think you'll love the notion, and never be able to not think in terms of
- conversations again!
+ It might take some time to get used to thinking of applications in terms of conversations, but
+ once you get used to it the advantages to such a setup will be apparent to you.
</para>
<para>
Some conversations last for just a single request. Conversations that span multiple requests must be
@@ -129,7 +128,7 @@
demarcation.
</para>
<para>
- Conversations may be <emphasis>nested</emphasis>, with one conversation taking place "inside" a wider
+ Conversations may be <emphasis>nested</emphasis>, with one conversation taking place within a wider
conversation. This is an advanced feature.
</para>
<para>
@@ -143,7 +142,7 @@
conversation context, in the same process.
</para>
<para>
- Alternatively, Seam may be configured to keep conversational state in the client browser.
+ Alternatively, Seam may be configured to keep the conversational state in the client browser.
</para>
</sect2>
@@ -151,7 +150,7 @@
<title>Session context</title>
<para>
A session context holds state associated with the user login session. While there are some cases
- where it is useful to share state between several conversations, we generally frown on the use of
+ where it is useful to share state information between several conversations, it is generally not advised to use the
session context for holding components other than global information about the logged in user.
</para>
<para>
@@ -204,7 +203,7 @@
<programlisting role="JAVA"><![CDATA[Contexts.getSessionContext().set("user", user);]]></programlisting>
<para>
- Usually, however, we obtain components from a context via injection, and put component instances into
+ Usually, however, we obtain components from a context via injection, and place component instances into
a context via querying.
</para>
</sect2>
@@ -253,9 +252,9 @@
accessed concurrently, and throws an exception if multiple threads access a stateful session bean.
</para>
<para>
- This behavior might have been okay in old-style web applications which were based around
- fine-grained, synchronous requests. But for modern applications which make heavy use of many
- fine-grained, asynchronous (AJAX) requests, concurrency is a fact of life, and must be supported by the
+ This behavior might have been okay in older web applications which were based around
+ precise, synchronous requests. But for modern applications which make heavy use of many
+ precise, asynchronous (AJAX) requests, concurrency is a fact of life, and must be supported by the
programming model. Seam weaves a concurrency management layer into its context model.
</para>
<para>
@@ -272,7 +271,7 @@
scope session beans and JavaBeans by default (and detects and breaks any deadlocks that occur). This is
not the default behavior for application scoped components however, since application scoped components
do not usually hold volatile state and because synchronization at the global level is
- <emphasis>extremely</emphasis> expensive. However, you can force a serialized threading model on any
+ <emphasis>extremely</emphasis> expensive to the application. However, you can force a serialized threading model on any
session bean or JavaBean component by adding the <literal>@Synchronized</literal> annotation.
</para>
<para>
@@ -313,7 +312,7 @@
<sect2>
<title>Stateless session beans</title>
<para>
- Stateless session bean components are not able to hold state across multiple invocations. Therefore,
+ Stateless session bean components are not able to hold a state across multiple invocations. Therefore,
they usually work by operating upon the state of other components in the various Seam contexts. They may
be used as JSF action listeners, but cannot provide properties to JSF components for display.
</para>
@@ -326,9 +325,9 @@
will be allocated from a reusable pool meaning that you may find any instance variables contain data
from previous uses of the bean).
</para>
- <para>
+ <!-- <para>
Stateless session beans are the least interesting kind of Seam component.
- </para>
+ </para> -->
<para>
Seam stateless session bean components may be instantiated using <literal>Component.getInstance()</literal>
or <literal>@In(create=true)</literal>. They should not be directly instantiated via JNDI lookup
@@ -374,7 +373,7 @@
explicitly in Java code, rather than being instantiated implicitly by Seam.
</para>
<para>
- Entity bean components do not support bijection or context demarcation. Nor does invocation of an
+ Entity bean components do not support bijection or context demarcation, neither does invocation of an
entity bean trigger validation.
</para>
<para>
@@ -387,16 +386,18 @@
By default, entity beans are bound to the conversation context. They may never be bound to the
stateless context.
</para>
- <para>
- Note that it in a clustered environment is somewhat less efficient to bind an entity bean directly to
- a conversation or session scoped Seam context variable than it would be to hold a reference to the
- entity bean in a stateful session bean. For this reason, not all Seam applications define entity beans
- to be Seam components.
- </para>
<para>
Seam entity bean components may be instantiated using <literal>Component.getInstance()</literal>,
<literal>@In(create=true)</literal> or directly using the <literal>new</literal> operator.
</para>
+ <note>
+ <para>
+ In a clustered environment it is somewhat less efficient to bind an entity bean directly to
+ a conversation or session scoped Seam context variable than it would be to hold a reference to the
+ entity bean in a stateful session bean. For this reason, not all Seam applications define entity beans
+ to be Seam components.
+ </para>
+ </note>
</sect2>
<sect2>
@@ -408,10 +409,15 @@
</para>
<para>
In a later chapter, we show you how to use Seam and Hibernate without an EJB container. In this use
- case, components are JavaBeans instead of session beans. Note, however, that in many application servers
+ case, components are JavaBeans instead of session beans.
+ </para>
+ <note>
+ <para>
+ In many application servers
it is somewhat less efficient to cluster conversation or session scoped Seam JavaBean components than it
is to cluster stateful session bean components.
</para>
+ </note>
<para>
By default, JavaBeans are bound to the event context.
</para>
@@ -433,8 +439,8 @@
for messages sent to a JMS queue or topic.
</para>
<para>
- Message-driven beans may not be bound to a Seam context. Nor do they have access to the session or
- conversation state of their "caller". However, they do support bijection and some other Seam
+ Message-driven beans may not be bound to a Seam context. Neither do they have access to the session or
+ conversation state of their <emphasis>caller</emphasis>. However, they do support bijection and some other Seam
functionality.
</para>
<para>
@@ -446,7 +452,7 @@
<sect2>
<title>Interception</title>
<para>
- In order to perform its magic (bijection, context demarcation, validation, etc), Seam must intercept
+ In order to perform bijection, context demarcation, validation, etc, Seam must intercept
component invocations. For JavaBeans, Seam is in full control of instantiation of the component, and no
special configuration is needed. For entity beans, interception is not required since bijection and
context demarcation are not defined. For session beans, we must register an EJB interceptor for the
@@ -575,7 +581,7 @@
a <literal>User</literal> class which is usually used as a session-scoped component representing the
current user but is used in user administration screens as a conversation-scoped component. The
<literal>@Role</literal> annotation lets us define an additional named role for a component, with a
- different scope—it lets us bind the same component class to different context variables. (Any
+ different scope; allowing for the same component class to bind to different context variables. (Any
Seam component <emphasis>instance</emphasis> may be bound to multiple context variables, but this lets
us do it at the class level, and take advantage of auto-instantiation.)
</para>
@@ -606,7 +612,7 @@
<sect2>
<title>Built-in components</title>
<para>
- Like many good frameworks, Seam eats its own dogfood and is implemented mostly as a set of built-in
+ Seam is implemented mostly as a set of built-in
Seam interceptors (see later) and Seam components. This makes it easy for applications to interact with
built-in components at runtime or even customize the basic functionality of Seam by replacing the
built-in components with custom implementations. The built-in components are defined in the Seam
@@ -626,7 +632,7 @@
<para>
<emphasis>Dependency injection</emphasis> or <emphasis>inversion of control</emphasis> is by now a familiar
concept to most Java developers. Dependency injection allows a component to obtain a reference to another
- component by having the container "inject" the other component to a setter method or instance variable. In
+ component by having the container <emphasis>inject</emphasis> the other component to a setter method or instance variable. In
all dependency injection implementations that we have seen, injection occurs when the component is
constructed, and the reference does not subsequently change for the lifetime of the component instance. For
stateless components, this is reasonable. From the point of view of a client, all instances of a particular
@@ -639,8 +645,8 @@
<listitem>
<para>
<emphasis>contextual</emphasis> - bijection is used to assemble stateful components from various
- different contexts (a component from a "wider" context may even have a reference to a component from
- a "narrower" context)
+ different contexts (a component from a <emphasis>wider</emphasis> context may even have a reference to a component from
+ a <emphasis>narrower</emphasis> context)
</para>
</listitem>
<listitem>
@@ -661,7 +667,7 @@
<para>
In essence, bijection lets you alias a context variable to a component instance variable, by specifying
- that the value of the instance variable is injected, outjected, or both. Of course, we use annotations to
+ that the value of the instance variable is injected, outjected, or bothl; annotations is used to
enable bijection.
</para>
@@ -725,7 +731,7 @@
}]]></programlisting>
<para>
- Injected values are disinjected (i.e, set to <literal>null</literal>) immediately after method
+ Injected values are disinjected (for instance, set to <literal>null</literal>) immediately after method
completion and being retrived by a user.
</para>
@@ -814,7 +820,7 @@
</para>
<para>
- The <literal>@Destroy</literal> method is called when the context that the Seam component is bound to
+ The <literal>@Destroy</literal> method is called when the context that the Seam component is bound to,
ends. Components may define only one <literal>@Destroy</literal> method.
</para>
@@ -849,13 +855,13 @@
</listitem>
<listitem>
<para>
- You want change the implementation of a component in certain
+ You wish to change the implementation of a component in certain
deployment scenarios.
</para>
</listitem>
<listitem>
<para>
- You want to install some components only if their dependencies are
+ You wish to install some components only if their dependencies are
available (useful for framework authors).
</para>
</listitem>
@@ -919,8 +925,7 @@
}]]></programlisting>
<para>
- In our unit tests, we don't have a JMS queue available, so we would like to stub
- out this method. We'll create a <emphasis>mock</emphasis> component that exists
+ In our unit tests, we don't have a JMS queue available, so we would like to remove this method. We will create a <emphasis>mock</emphasis> component that exists
in the classpath when unit tests are running, but is never deployed with the
application:
</para>
@@ -939,9 +944,9 @@
</para>
<para>
- This is nice if we are able to control exactly which classes are in the classpath. But
- if I'm writing a reusable framework with many dependencies, I don't want to have to
- break that framework across many jars. I want to be able to decide which components
+ This is advantageous if we are able to control exactly which classes are in the classpath. But
+ if you are writing a reusable framework with many dependencies, you don't want to have to
+ break that framework across many jars. The answer would be to be able to decide which components
to install depending upon what other components are installed, and upon what classes
are available in the classpath. The <literal>@Install</literal> annotation also
controls this functionality. Seam uses this mechanism internally to enable conditional
@@ -955,7 +960,7 @@
<title>Logging</title>
<para>
- Who is not totally fed up with seeing noisy code like this?
+ An example of generic logging code:
</para>
<programlisting role="JAVA"><![CDATA[private static final Log log = LogFactory.getLog(CreateOrderAction.class);
@@ -970,12 +975,6 @@
}]]></programlisting>
<para>
- It is difficult to imagine how the code for a simple log message could possibly be more verbose. There is
- more lines of code tied up in logging than in the actual business logic! I remain totally astonished that
- the Java community has not come up with anything better in 10 years.
- </para>
-
- <para>
Seam provides a logging API that simplifies this code significantly:
</para>
@@ -987,17 +986,18 @@
}]]></programlisting>
<para>
- It doesn't matter if you declare the <literal>log</literal> variable static or not—it will work
+ It doesn't matter if you declare the <literal>log</literal> variable static or not; it will work
either way, except for entity bean components which require the <literal>log</literal> variable to be
static.
</para>
+ <note>
<para>
- Note that we don't need the noisy <literal>if ( log.isDebugEnabled() )</literal> guard, since string
- concatenation happens <emphasis>inside</emphasis> the <literal>debug()</literal> method. Note also that we
- don't usually need to specify the log category explicitly, since Seam knows what component it is injecting
+ The <literal>if ( log.isDebugEnabled() )</literal> guard is no longer necessary, since string
+ concatenation happens <emphasis>inside</emphasis> the <literal>debug()</literal> method. Also the log category does not usually require specification since Seam knows what component it is injecting
the <literal>Log</literal> into.
</para>
+ </note>
<!-- Lets not document this now, cos we should migrate to use the printf format
<para>
@@ -1020,7 +1020,7 @@
}]]></programlisting>
<para>
- Seam logging automagically chooses whether to send output to log4j or JDK logging. If log4j is in the
+ Seam logging decides whether to send output to log4j or JDK logging. If log4j is in the
classpath, Seam with use it. If it is not, Seam will use JDK logging.
</para>
@@ -1038,7 +1038,7 @@
</para>
<para>
- Of course, EJB stateful session beans must perform automatic dirty checking and replication of mutable
+ EJB stateful session beans must perform automatic checking and replication of mutable
state and a sophisticated EJB container can introduce optimizations such as attribute-level replication.
Unfortunately, not all Seam users have the good fortune to be working in an environment that supports EJB
3.0. So, for session and conversation scoped JavaBean and entity bean components, Seam provides an extra
@@ -1048,7 +1048,7 @@
<para>
For session or conversation scoped JavaBean components, Seam automatically forces replication to occur by
calling <literal>setAttribute()</literal> once in every request that the component was invoked by the
- application. Of course, this strategy is inefficient for read-mostly components. You can control this
+ application. Of course, this strategy is inefficient for some read components. You can control this
behavior by implementing the <literal>org.jboss.seam.core.Mutable</literal> interface, or by extending
<literal>org.jboss.seam.core.AbstractMutable</literal>, and writing your own dirty-checking logic inside
the component. For example,
@@ -1103,7 +1103,7 @@
by calling <literal>setAttribute()</literal> once in every request, <emphasis>unless the (conversation-scoped)
entity is currently associated with a Seam-managed persistence context, in which case no replication is
needed</emphasis>. This strategy is not necessarily efficient, so session or conversation scope entity beans
- should be used with care. You can always write a stateful session bean or JavaBean component to "manage" the
+ should be used with care. You can always write a stateful session bean or JavaBean component to <emphasis>manage</emphasis> the
entity bean instance. For example,
</para>
@@ -1123,10 +1123,12 @@
}]]></programlisting>
+ <note>
<para>
- Note that the <literal>EntityHome</literal> class in the Seam Application Framework provides a great example
+ The <literal>EntityHome</literal> class in the Seam Application Framework provides a great example
of managing an entity bean instance using a Seam component.
</para>
+ </note>
</sect1>
Modified: projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Conversations.xml
===================================================================
--- projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Conversations.xml 2009-02-11 02:06:04 UTC (rev 84082)
+++ projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Conversations.xml 2009-02-11 02:46:19 UTC (rev 84083)
@@ -6,11 +6,11 @@
<title>Conversations and workspace management</title>
<para>
- It's time to understand Seam's conversation model in more detail.
+ It is time to understand Seam's conversation model in more detail.
</para>
-
+ <!--
<para>
- Historically, the notion of a Seam "conversation" came about as
+ Historically, the notion of a Seam <emphasis>conversation</emphasis> came about as
a merger of three different ideas:
</para>
@@ -51,7 +51,7 @@
we have a powerful construct that lets us build richer and more efficient
applications with less code than before.
</para>
-
+ -->
<section>
<title>Seam's conversation model</title>
@@ -104,7 +104,7 @@
Any faces request (a JSF postback) will propagate the
conversation context. By default, non-faces requests (GET
requests, for example) do not propagate the conversation
- context, but see below for more information on this.
+ context; see below for more information on this.
</para>
</listitem>
<listitem>
@@ -120,7 +120,7 @@
<para>
Seam transparently propagates the conversation context (including
the temporary conversation context) across JSF postbacks and
- redirects. If you don't do anything special, a <emphasis>non-faces request</emphasis>
+ redirects. If you do not do anything, a <emphasis>non-faces request</emphasis>
(a GET request for example) will not propagate the conversation context and
will be processed in a new temporary conversation. This is usually - but not
always - the desired behavior.
@@ -169,10 +169,12 @@
<s:conversationPropagation type="none"/>
</h:commandLink>]]></programlisting>
- <para>
- Note that disabling conversation context propagation is absolutely not the
+ <important>
+ <para>
+ Disabling conversation context propagation is not the
same thing as ending the conversation.
- </para>
+ </para>
+ </important>
<para>
The <literal>conversationPropagation</literal> request parameter, or
@@ -237,7 +239,7 @@
conversation's context variables, but not write to them.)
When an <literal>@End</literal> is subsequently encountered,
the nested conversation will be destroyed, and the outer
- conversation will resume, by "popping" the conversation stack.
+ conversation will resume, by <emphasis>popping</emphasis> the conversation stack.
Conversations may be nested to any arbitrary depth.
</para>
@@ -287,13 +289,13 @@
<para>
Sometimes we want to begin a conversation immediately the page is
- accessed. Since there is no JSF action method, we can't solve the problem
+ accessed. Since there is no JSF action method, we cannot solve the problem
in the usual way, by annotating the action with <literal>@Begin</literal>.
</para>
<para>
A further problem arises if the page needs some state to be fetched
- into a context variable. We've already seen two ways to solve this
+ into a context variable. We have already seen two ways to solve this
problem. If that state is held in a Seam component, we can fetch the
state in a <literal>@Create</literal> method. If not, we can define a
<literal>@Factory</literal> method for the context variable.
@@ -329,11 +331,13 @@
...
</pages>]]></programlisting>
+<note>
<para>
- Note that you can also call this built-in action from a JSF
+ This built-in action can also be executed from a JSF
control, and, similarly, you can use
<literal>#{conversation.end}</literal> to end conversations.
</para>
+</note>
<para>
If you want more control, to join existing conversations or
@@ -405,7 +409,7 @@
<para>
JSF command links always perform a form submission via JavaScript,
- which breaks the web browser's "open in new window" or "open in new tab"
+ which breaks the web browser's <emphasis>open in new window</emphasis> or <emphasis>open in new tab</emphasis>
feature. In plain JSF, you need to use an <literal><h:outputLink></literal>
if you need this functionality. But there are two major limitations to
<literal><h:outputLink></literal>.
@@ -460,7 +464,7 @@
<para>
If you specify <emphasis>both</emphasis> a JSF view id and an action method, the
- 'view' will be used <emphasis>unless</emphasis> the action method returns a
+ <emphasis>view</emphasis> will be used <emphasis>unless</emphasis> the action method returns a
non-null outcome:
</para>
@@ -567,7 +571,7 @@
<para>
When working with conversations that deal with persistent objects, it may be
desirable to use the natural business key of the object instead of the standard,
- "surrogate" conversation id:
+ <emphasis>surrogate</emphasis> conversation id:
</para>
<para>
@@ -578,10 +582,10 @@
the user requests the same operation twice. Take this example:
<quote>
- You are on ebay, half way through paying for an item you just
- won as a Christmas present for your parents. Lets say you're
+ You are on Ebay, half way through paying for an item you just
+ won as a Christmas present for your parents. Lets say you are
sending it straight to them - you enter your payment details
- but you can't remember their address. You accidentally reuse
+ but you cannot remember their address. You accidentally reuse
the same browser window finding out their address. Now you
need to return to the payment for the item.
</quote>
@@ -590,7 +594,7 @@
With a natural conversation its really 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.
+ with the itemId as the conversation ID.
</para>
<para>
@@ -598,11 +602,10 @@
</para>
<para>
- For me this consists of a navigable
+ 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
- important, of course.
+ URL; for some applications user friendly URLs are less
+ important.
</para>
<para>
@@ -616,9 +619,9 @@
http://seam-hotels/book/BestWesternAntwerpen.
</para>
- <para>
+ <!-- <para>
Much better!
- </para>
+ </para> -->
</section>
<section>
@@ -641,7 +644,7 @@
<para>
The next attribute, <literal>parameter-name</literal> defines the request parameter
- that will contain the natural conversation id, in place of the default conversation
+ that will contain the natural conversation ID, in place of the default conversation
id parameter. In this example, the <literal>parameter-name</literal> is <literal>auctionId</literal>.
This means that instead of a conversation parameter like <literal>cid=123</literal>
appearing in the URL for your page, it will contain <literal>auctionId=765432</literal>
@@ -678,7 +681,7 @@
<para>
When starting, or redirecting to, a natural conversation there are a number
- of options for specifying the natural conversation name. Let's start by looking at
+ of options for specifying the natural conversation name. Let us start by looking at
the following page definition:
</para>
@@ -729,7 +732,7 @@
<title>Workspace management</title>
<para>
- Workspace management is the ability to "switch" conversations in
+ Workspace management is the ability to <emphasis>switch</emphasis> conversations in
a single window. Seam makes workspace management completely
transparent at the level of the Java code. To enable workspace
management, all you need to do is:
@@ -780,11 +783,13 @@
</page>
</pages>]]></programlisting>
+<important>
<para>
- Note that if this file is missing, the Seam application will
- continue to work perfectly! The only missing functionality
+ If this file is missing, the Seam application will
+ continue to work perfectly, with the only missing functionality
will be the ability to switch workspaces.
</para>
+</important>
</section>
@@ -986,7 +991,7 @@
}]]></programlisting>
<para>
- Also, you can't inject a conversation scoped component into an event
+ Also, you cannot inject a conversation scoped component into an event
scoped component which you bind a JSF control to. This includes Seam
built in components like <literal>facesMessages</literal>.
</para>
@@ -1041,8 +1046,8 @@
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!
+ let them know what's going on. It is therefore very important not to
+ flood the server with AJAX events.
</para>
<para>
@@ -1059,10 +1064,10 @@
<page view-id="/book.xhtml" conversation-required="true" login-required="true" concurrent-request-timeout="2000" />]]></programlisting>
<para>
- So far we've discussed serial AJAX requests - the client tells the
+ So far we have discussed serial AJAX requests - the client tells the
server that an event has occur, and then re-renders part of the page based
on the result. This approach is great when the AJAX request is
- lightweight (the methods called are simple e.g. calculating the sum of a
+ lightweight (the methods called are simple for example, calculating the sum of a
column of numbers). But what if we need to do a complex computation?
</para>
<para>
@@ -1071,7 +1076,7 @@
causes action to be executed asynchronously on the server (so the the
response to the client is immediate); the client then polls the server
for updates. This is useful when you have a long-running action for
- which it is important that every action executes (you don't want some to
+ which it is important that every action executes (you do not want some to
be dropped as duplicates, or to timeout).
</para>
@@ -1082,17 +1087,17 @@
<title>How should we design our conversational AJAX application?</title>
<para>
Well first, you need to decide whether you want to use the simpler
- "synchronous" request or whether you want to add using a poll-style
+ <emphasis>synchronous</emphasis> request or whether you want to add using a poll-style
approach.
</para>
<para>
- If you go for a "synchronous" approach, then you need to make an
+ If you go for a <emphasis>synchronous</emphasis> approach, then you need to make an
estimate of how long your AJAX request will take to complete - is it much
shorter than the concurrent request timeout? If not, you probably want to
alter the concurrent request timeout for this method (as discussed
above). Next you probably want a queue on the client side to prevent
- flooding the server with requests. If the event occurs often (e.g. a
+ flooding the server with requests. If the event occurs often (for example, a
keypress, onblur of input fields) and immediate update of the client is
not a priority you should set a request delay on the client side. When
working out your request delay, factor in that the event may also be
@@ -1189,7 +1194,7 @@
<listitem>
<para>
<literal>ignoreDupResponses</literal> — ignore the response
- produced by the request if a more recent 'similar' request is
+ produced by the request if a more recent <emphasis>similar</emphasis> request is
already in the queue. ignoreDupResponses="true" does <emphasis>not
cancel</emphasis> the the processing of the request on the server
side — just prevents unnecessary updates on the client side.
Modified: projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Events.xml
===================================================================
--- projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Events.xml 2009-02-11 02:06:04 UTC (rev 84082)
+++ projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Events.xml 2009-02-11 02:46:19 UTC (rev 84083)
@@ -62,8 +62,7 @@
</start-page>]]></programlisting>
<para>
- You can find out more information about JSF events and jBPM events elsewhere.
- Let's concentrate for now upon the two additional kinds of events defined by Seam.
+ You can find out more information about JSF events and jBPM events throughout the rest of the documentation. For now we will concentrate upon the two additional types of events defined by Seam.
</para>
</section>
@@ -72,8 +71,7 @@
<para>
A Seam page action is an event that occurs just before we render a page.
- We declare page actions in <literal>WEB-INF/pages.xml</literal>. We
- can define a page action for either a particular JSF view id:
+ We declare page actions in <literal>WEB-INF/pages.xml</literal> and define them for either a particular JSF view id:
</para>
<programlisting role="XML"><![CDATA[<pages>
@@ -91,7 +89,7 @@
</pages>]]></programlisting>
<para>
- If multiple wildcarded page actions match the current view-id, Seam
+ If multiple wildcarded page actions match the current <literal>view-id</literal>, Seam
will call all the actions, in order of least-specific to most-specific.
</para>
@@ -101,7 +99,7 @@
</para>
<para>
- Furthermore, the view id mentioned in the <literal><page></literal>
+ Furthermore, the <literal>view-id</literal> mentioned in the <literal><page></literal>
element need not correspond to a real JSP or Facelets page! So, we can
reproduce the functionality of a traditional action-oriented framework
like Struts or WebWork using page actions. For example:
@@ -134,15 +132,14 @@
<title>Page parameters</title>
<para>
- A JSF faces request (a form submission) encapsulates both an "action"
- (a method binding) and "parameters" (input value bindings). A page
- action might also needs parameters!
+ A JSF faces request (a form submission) encapsulates both an <emphasis>action</emphasis>
+ (a method binding) and <emphasis>parameters</emphasis> (input value bindings). A page
+ action might also require parameters.
</para>
<para>
Since GET requests are bookmarkable, page parameters are passed as
- human-readable request parameters. (Unlike JSF form inputs, which are
- anything but!)
+ human-readable request parameters.
</para>
<para>
@@ -208,7 +205,7 @@
we get from any other page to <literal>/hello.jsp</literal> (or from
<literal>/hello.jsp</literal> back to <literal>/hello.jsp</literal>),
the value of the model attribute referred to in the value binding is
- "remembered", without the need for a conversation (or other server-side
+ <emphasis>remembered</emphasis>, without the need for a conversation (or other server-side
state).
</para>
@@ -234,8 +231,8 @@
<para>
Propagation of page parameters is especially useful if you want to build multi-layer
- master-detail CRUD pages. You can use it to "remember" which view you were previously
- on (e.g. when pressing the Save button), and which entity you were editing.
+ master-detail CRUD pages. You can use it to <emphasis>remember</emphasis> which view you were previously
+ on (e.g. when pressing the <literal>Save</literal> button), and which entity you were editing.
</para>
<itemizedlist>
<listitem>
@@ -256,11 +253,11 @@
</itemizedlist>
<para>
- This all sounds pretty complex, and you're probably wondering if such an
+ This all sounds rather complex, and you are probably wondering if such an
exotic construct is really worth the effort. Actually, the idea is very
- natural once you "get it". It is definitely worth taking the time to
- understand this stuff. Page parameters are the most elegant way to
- propagate state across a non-faces request. They are especially cool for
+ natural once the thought behind it becomes apparent; it is definitely worth taking the time to
+ understand. Page parameters are the most elegant way to
+ propagate state across a non-faces request. They are especially useful for
problems like search screens with bookmarkable results pages, where we
would like to be able to write our application code to handle both POST
and GET requests with the same code. Page parameters eliminate repetitive
@@ -454,9 +451,9 @@
</page>]]></programlisting>
<para>
- As we've ended conversation any subsequent requests won't know
+ Since we have ended the conversation, any subsequent requests will not know
which document we are interested in. We can pass the document
- id as a request parameter which also makes the view bookmarkable:
+ ID as a request parameter which also makes the view bookmarkable:
</para>
<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
@@ -474,7 +471,7 @@
<para>
Null outcomes are a special case in JSF. The null outcome is interpreted to
- mean "redisplay the page". The following navigation rule matches any non-null
+ mean <emphasis>redisplay the page</emphasis>. The following navigation rule matches any non-null
outcome, but <emphasis>not</emphasis> the null outcome:
</para>
@@ -502,7 +499,7 @@
</page>]]></programlisting>
<para>
- The view-id may be given as a JSF EL expression:
+ The <varname>view-id</varname> may be given as a JSF EL expression:
</para>
<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
@@ -525,10 +522,10 @@
or even just a lot of navigation rules,
you will almost certainly want to split the declarations up over
multiple files. You can define actions and parameters for a page
- with the view id <literal>/calc/calculator.jsp</literal> in a
+ with the <varname>view-id</varname> <literal>/calc/calculator.jsp</literal> in a
resource named <literal>calc/calculator.page.xml</literal>. The
root element in this case is the <literal><page></literal>
- element, and the view id is implied:
+ element, and the <varname>view-id</varname> is implied:
</para>
<programlisting role="XML"><![CDATA[<page action="#{calculator.calculate}">
@@ -546,8 +543,7 @@
<para>
Seam components can interact by simply calling each others methods.
- Stateful components may even implement the observer/observable pattern.
- But to enable components to interact in a more loosely-coupled fashion
+ Stateful components may even implement the observer/observable pattern. However to enable components to interact in a more loosely-coupled fashion
than is possible when the components call each others methods directly,
Seam provides <emphasis>component-driven events</emphasis>.
</para>
@@ -622,10 +618,9 @@
}]]></programlisting>
<para>
- You might wonder why I've not mentioned anything about event objects in
- this discussion. In Seam, there is no need for an event object to propagate
+ You might wonder why event objects have not been mentioned. In Seam, there is no need for an event object to propagate
state between event producer and listener. State is held in the Seam
- contexts, and is shared between components. However, if you really want
+ contexts, and is shared between components. However, if you wish
to pass an event object, you can:
</para>
@@ -803,7 +798,7 @@
</para>
<para>
- You can even use Seam interceptors with JavaBean components, not just EJB3 beans!
+ You can even use Seam interceptors with JavaBean components, not just EJB3 beans.
</para>
<para>
@@ -977,7 +972,7 @@
<para>
You can also access the handled exception instance through EL, Seam places it in the
- conversation context, e.g. to access the message of the exception:
+ conversation context, for example, to access the message of the exception:
</para>
<programlisting role="XML"><![CDATA[...
Modified: projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml
===================================================================
--- projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml 2009-02-11 02:06:04 UTC (rev 84082)
+++ projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml 2009-02-11 02:46:19 UTC (rev 84083)
@@ -5,21 +5,17 @@
<title>Getting started with Seam, using JBoss Tools</title>
<para>
- JBoss Tools is a collection of Eclipse plugins. JBoss Tools a project
+ JBoss Tools is a collection of Eclipse plugins and contains a project
creation wizard for Seam, Content Assist for the Unified Expression
Language (EL) in both facelets and Java code, a graphical editor for jPDL,
a graphical editor for Seam configuration files, support for running Seam
- integration tests from within Eclipse, and much more.
+ integration tests from within Eclipse, and much more. In short, if you are an Eclipse user, then you'll want JBoss Tools!
</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
+ JBoss Tools, as with <filename>seam-gen</filename>, works best with the JBoss Enterprise Application Platform, 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
+ The changes are much like those described for <filename>seam-gen</filename> later in this
reference manual.
</para>
@@ -56,7 +52,7 @@
</mediaobject>
<para>
- First, enter a name for your new project. For this tutorial, we're
+ First, enter a name for your new project. For this tutorial, we are
going to use
<literal>helloworld</literal>
.
@@ -64,7 +60,7 @@
<para>
- Now, we need to tell JBoss Tools about JBoss AS. This is a two stage
+ Now, we need to tell JBoss Tools about the JBoss Enterprise Application Server. This is a two stage
process, first we need to define a runtime, make sure you select JBoss
AS 4.2:
</para>
@@ -146,7 +142,7 @@
<para>
The next 3 screens allow you to further customize your new project, but
- for us the defaults are fine. So just hit <emphasis>Next</emphasis>
+ for us the defaults are fine. Just click <emphasis>Next</emphasis>
until you reach the final screen.
</para>
Modified: projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Gettingstarted.xml
===================================================================
--- projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Gettingstarted.xml 2009-02-11 02:06:04 UTC (rev 84082)
+++ projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Gettingstarted.xml 2009-02-11 02:46:19 UTC (rev 84083)
@@ -7,16 +7,9 @@
<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>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
- 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
+ <para>You can use <filename>seam-gen</filename> 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>
+ you can still follow along with this tutorial and 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.
That makes it easy to customize if you need to.</para>
@@ -24,14 +17,14 @@
<section>
<title>Before you start</title>
- <para>Make sure you have JDK 5 or JDK 6, JBoss EAP 4.3 CP03 and Ant 1.6, along with recent versions of Eclipse, the
+ <para>Make sure you have JDK 5 or JDK 6, JBoss EAP 4.3 CP04 and Ant 1.6, along with recent versions of Eclipse, the
JBoss IDE plugin for Eclipse and the TestNG plugin for Eclipse correctly installed before starting. Add your
JBoss installation to the JBoss Server View in Eclipse. Start JBoss in debug mode. Finally, start a command
prompt in the directory where you unzipped the Seam distribution.</para>
<para>JBoss has sophisticated support for hot re-deployment of WARs and EARs. Unfortunately, due to bugs in the
- JVM, repeated redeployment of an EAR—which is common during development—eventually causes the JVM to run out
- of perm gen space. For this reason, we recommend running JBoss in a JVM with a large perm gen space at
+ JVM, repeated redeployment of an EAR (common during development) eventually causes the JVM to run out
+ of permanent generation space. For this reason, we recommend running JBoss in a JVM with a large permanent generation space at
development time. If you're running JBoss from JBoss IDE, you can configure this in the server launch
configuration, under "VM arguments". We suggest the following values:</para>
@@ -43,15 +36,15 @@
<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>
+ your first <literal>OutOfMemoryException</literal>.</para> -->
</section>
<section>
<title>Setting up a new Eclipse project</title>
- <para>The first thing we need to do is configure seam-gen for your environment: JBoss AS installation directory,
+ <para>The first thing we need to do is configure <filename>seam-gen</filename> for your environment: JBoss Enterprise Application Platform installation directory,
Eclipse workspace, and database connection. It's easy, just type:</para>
<programlisting>cd jboss-seam-2.0.x
@@ -119,11 +112,11 @@
<para>The most important choice you need to make is between EAR deployment and WAR deployment of your project.
EAR projects support EJB 3.0 and require Java EE 5. WAR projects do not support EJB 3.0, but may be deployed
to a J2EE environment. The packaging of a WAR is also simpler to understand. If you installed an EJB3-ready
- application server like JBoss, choose <literal>ear</literal>. Otherwise, choose <literal>war</literal>.
- We'll assume that you've chosen an EAR deployment for the rest of the tutorial, but you can follow exactly
+ application server like JBoss, choose <literal>EAR</literal>. Otherwise, choose <literal>WAR</literal>.
+ We will assume that you have chosen an EAR deployment for the rest of the tutorial, but you can follow exactly
the same steps for a WAR deployment.</para>
- <para>If you are working with an existing data model, make sure you tell seam-gen that the tables already exist
+ <para>If you are working with an existing data model, make sure you tell <filename>seam-gen</filename> that the tables already exist
in the database.</para>
<para>The settings are stored in <literal>seam-gen/build.properties</literal>, but you can also modify them
@@ -151,7 +144,7 @@
<para>This copies the Seam jars, dependent jars and the JDBC driver jar to a new Eclipse project, and generates
all needed resources and configuration files, a facelets template file and stylesheet, along with Eclipse
metadata and an Ant build script. The Eclipse project will be automatically deployed to an exploded
- directory structure in JBoss AS as soon as you add the project using <literal>New -> Project...
+ directory structure in the JBoss Enterprise Application Server as soon as you add the project using <literal>New -> Project...
-> General -> Project -> Next</literal>, typing the <literal>Project name</literal>
(<literal>helloworld</literal> in this case), and then clicking <literal>Finish</literal>. Do not select
<literal>Java Project</literal> from the New Project wizard.</para>
@@ -166,9 +159,9 @@
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 generated XML configuration documetents which appear in the project directory releate to Java EE. In general cases these files should not have to be viewed and are usually the same between all Seam projects.
+ </para>
<para>The generated project includes three database and persistence configurations. The
<literal>persistence-test.xml</literal> and
@@ -176,8 +169,7 @@
database schema and the test data in <literal>import-test.sql</literal> is always exported to the database
before running tests. The <literal>myproject-dev-ds.xml</literal>, <literal>persistence-dev.xml</literal>and
<literal>import-dev.sql</literal> files are for use when deploying the application to your development
- database. The schema might be exported automatically at deployment, depending upon whether you told seam-gen
- that you are working with an existing database. The <literal>myproject-prod-ds.xml</literal>,
+ database. The schema might be exported automatically at deployment, depending upon whether <filename>seam-gen</filename> has been configureed to work with an existing database. The <literal>myproject-prod-ds.xml</literal>,
<literal>persistence-prod.xml</literal>and <literal>import-prod.sql</literal> files are for use when
deploying the application to your production database. The schema is not exported automatically at
deployment.</para>
@@ -186,7 +178,7 @@
<section>
<title>Creating a new action</title>
- <para>If you're used to traditional action-style web frameworks, you're probably wondering how you can create a
+ <para>If you are used to traditional action-style web frameworks, you are probably wondering how you can create a
simple web page with a stateless action method in Java. If you type:</para>
<programlisting>seam new-action</programlisting>
@@ -228,14 +220,18 @@
Total time: 13 seconds
C:\Projects\jboss-seam></programlisting>
- <para>Because we've added a new Seam component, we need to restart the exploded directory deployment. You can do
+ <para>Because we have added a new Seam component, we need to restart the exploded directory deployment. You can do
this by typing <literal>seam restart</literal>, or by running the <literal>restart</literal> target in the
generated project <literal>build.xml</literal> file from inside Eclipse. Another way to force a restart is
- to edit the file <literal>resources/META-INF/application.xml</literal> in Eclipse. <emphasis>Note that you
- do not need to restart JBoss each time you change the application.</emphasis></para>
+ to edit the file <literal>resources/META-INF/application.xml</literal> in Eclipse. </para>
+ <note>
+ <para>
+ JBoss does not require a restart each time the application changes.
+ </para>
+ </note>
- <para>Now go to <literal>http://localhost:8080/helloworld/ping.seam</literal> and click the button. You can see
- the code behind this action by looking in the project <literal>src</literal> directory. Put a breakpoint in
+ <para>Go to <literal>http://localhost:8080/helloworld/ping.seam</literal> and click the button to see
+ the code behind this action by looking in the project <literal>src</literal> directory. Place a breakpoint in
the <literal>ping()</literal> method, and click the button again.</para>
<para>Finally, locate the <literal>PingTest.xml</literal> file in the test package and run the integration tests
@@ -292,15 +288,15 @@
<section>
<title>Generating an application from an existing database</title>
- <para>Manually create some tables in your database. (If you need to switch to a different database, just run
+ <para>Manually create some tables in your database. (If you need to switch to a different database, run
<literal>seam setup</literal> again.) Now type:</para>
<programlisting>seam generate-entities</programlisting>
<para>Restart the deployment, and 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 seam-gen.</para>
+ database, edit existing objects, and create new objects. If you look at the generated code, you will 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 use <filename>seam-gen</filename>.</para>
</section>
<section>
@@ -338,7 +334,7 @@
<section id="gettingstarted-hotdeployment">
<title>Seam and incremental hot deployment</title>
- <para>When you deploy your Seam application as an exploded directory, you'll get some support for incremental
+ <para>When you deploy your Seam application as an exploded directory, you will receive support for incremental
hot deployment at development time. You need to enable debug mode in both Seam and Facelets, by adding this
line to <literal>components.xml</literal>:</para>
@@ -402,7 +398,7 @@
</itemizedlist>
<para>If you create a WAR project using seam-gen, incremental hot deployment is available out of the box for
- classes in the <literal>src/action</literal> source directory. However, seam-gen does not support
+ classes in the <literal>src/action</literal> source directory. However, <filename>seam-gen</filename> does not support
incremental hot deployment for EAR projects.</para>
</section>
Modified: projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Introduction.xml
===================================================================
--- projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Introduction.xml 2009-02-11 02:06:04 UTC (rev 84082)
+++ projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Introduction.xml 2009-02-11 02:46:19 UTC (rev 84083)
@@ -13,7 +13,7 @@
<variablelist>
<varlistentry>
- <term><emphasis>One kind of "stuff"</emphasis></term>
+ <term><emphasis>A uniform component model</emphasis></term>
<listitem>
<para>
Seam defines a uniform component model for all business logic in your application.
@@ -24,18 +24,15 @@
</para>
<para>
There is no distinction between presentation tier components and business logic
- components in Seam. You can layer your application according to whatever architecture
- you devise, rather than being forced to shoehorn your application logic into an
- unnatural layering scheme forced upon you by whatever combination of stovepipe
- frameworks you're using today.
+ components in Seam. Your application can be layered according to whatever architecture
+ you devise, rather than forcing your application logic into an
+ unnatural layering scheme forced upon you by whatever combination of
+ frameworks you are using today.
</para>
<para>
Unlike plain Java EE or J2EE components, Seam components may <emphasis>simultaneously</emphasis>
- access state associated with the web request and state held in transactional resources (without
- the need to propagate web request state manually via method parameters). You might object
- that the application layering imposed upon you by the old J2EE platform was a Good Thing.
- Well, nothing stops you creating an equivalent layered architecture using Seam—the difference
- is that <emphasis>you</emphasis> get to architect your own application and decide what the
+ access the state associated with the web request and the state held in transactional resources (without
+ the need to propagate a web request state manually via method parameters). Seam grants you the ability to create a layered architecture in the case that the old J2EE platform is not up-to-date with your needs. In doing this <emphasis>you</emphasis> get to architect your own application and decide what the
layers are and how they work together.
</para>
</listitem>
@@ -45,31 +42,28 @@
<term><emphasis>Integrate JSF with EJB 3.0</emphasis></term>
<listitem>
<para>
- JSF and EJB 3.0 are two of the best new features of Java EE 5. EJB3 is a brand new
- component model for server side business and persistence logic. Meanwhile, JSF is a
- great component model for the presentation tier. Unfortunately, neither component
+ JSF and EJB 3.0 are two of the most outstanding new features of Java EE 5. EJB3 is a brand new
+ component model for server side business and persistence logic. Meanwhile, JSF is an excellent component model for the presentation tier. Unfortunately, neither component
model is able to solve all problems in computing by itself. Indeed, JSF and EJB3
- work best used together. But the Java EE 5 specification provides no standard way
+ work best when used together. But the Java EE 5 specification provides no standard way
to integrate the two component models. Fortunately, the creators of both models
foresaw this situation and provided standard extension points to allow extension
and integration with other frameworks.
</para>
<para>
- Seam unifies the component models of JSF and EJB3, eliminating glue code, and letting
- the developer think about the business problem.
+ Seam unifies the component models of JSF and EJB3, eliminating glue code, and allowing
+ the developer to concentrate on the business problem.
</para>
<para>
- It is possible to write Seam applications where "everything" is an EJB. This may come
- as a surprise if you're used to thinking of EJBs as coarse-grained, so-called
- "heavyweight" objects. However, version 3.0 has completely changed the nature of EJB
- from the point of view of the developer. An EJB is a fine-grained object—nothing
- more complex than an annotated JavaBean. Seam even encourages you to use session beans
- as JSF action listeners!
+ It is possible to write Seam applications where everything is an EJB. This may come
+ as a surprise if you're used to thinking of EJBs as unrefined objects. However, version 3.0 has completely changed the nature of EJB
+ from the point of view of the developer. An EJB is a refined object; nothing
+ more complex than an annotated JavaBean. Furthermore it is encouraged that sessions beans are used as JSF action listeners.
</para>
<para>
On the other hand, if you prefer not to adopt EJB 3.0 at this time, you don't have to.
Virtually any Java class may be a Seam component, and Seam provides all the functionality
- that you expect from a "lightweight" container, and more, for any component, EJB or
+ that you expect from a simplistic container (and more) for any component, EJB or
otherwise.
</para>
</listitem>
@@ -79,8 +73,8 @@
<term><emphasis>Integrated AJAX</emphasis></term>
<listitem>
<para>
- Seam supports the best open source JSF-based AJAX solutions: JBoss RichFaces and
- ICEfaces. These solutions let you add AJAX capability to your user interface without
+ Seam supports the finest open source JSF-based AJAX solutions: JBoss RichFaces and
+ ICEfaces. These solutions allow you to add AJAX capability to your user interface without
the need to write any JavaScript code.
</para>
@@ -97,7 +91,7 @@
</para>
<para>
Neither of these approaches would work well, were it not for Seam's built-in concurrency
- and state management, which ensures that many concurrent fine-grained, asynchronous AJAX
+ and state management, which ensures that many concurrent, asynchronous AJAX
requests are handled safely and efficiently on the server side.
</para>
</listitem>
@@ -107,9 +101,8 @@
<term><emphasis>Business process as a first class construct</emphasis></term>
<listitem>
<para>
- Optionally, Seam provides transparent business process management via jBPM. You won't
- believe how easy it is to implement complex workflows, collaboration and and task management
- using jBPM and Seam.
+ Optionally, Seam provides transparent business process management via jBPM allowing for implemention of complex workflows, collaboration and task management
+ using jBPM and Seam to be relatively simple.
</para>
<para>
Seam even allows you to define presentation tier pageflow using the same language (jPDL)
@@ -127,8 +120,8 @@
<term><emphasis>Declarative state management</emphasis></term>
<listitem>
<para>
- We're all used to the concept of declarative transaction management and declarative
- security from the early days of EJB. EJB 3.0 even introduces declarative persistence context
+ The concept of declarative transaction management and declarative
+ security has been present since the early days of EJB. EJB 3.0 now introduces declarative persistence context
management. These are three examples of a broader problem of managing state that is
associated with a particular <emphasis>context</emphasis>, while ensuring that all needed
cleanup occurs when the context ends. Seam takes the concept of declarative state
@@ -142,14 +135,14 @@
<para>
Declarative application state management is made possible by the richness of the
<emphasis>context model</emphasis> defined by Seam. Seam extends the context model defined
- by the servlet spec—request, session, application—with two new
- contexts—conversation and business process—that are more meaningful from the
+ by the servlet spec (request, session, application) with two new
+ contexts (conversation and business process) that are more meaningful from the
point of view of the business logic.
</para>
<para>
- You'll be amazed at how many things become easier once you start using conversations.
+ You will be amazed at how many things become easier once you start using conversations.
Have you ever suffered pain dealing with lazy association fetching in an ORM solution
- like Hibernate or JPA? Seam's conversation-scoped persistence contexts mean you'll
+ like Hibernate or JPA? Seam's conversation-scoped persistence contexts mean you will
rarely have to see a <literal>LazyInitializationException</literal>. Have you ever
had problems with the refresh button? The back button? With duplicate form submission?
With propagating messages across a post-then-redirect? Seam's conversation management
@@ -165,7 +158,7 @@
<listitem>
<para>
The notion of <emphasis>Inversion of Control</emphasis> or <emphasis>dependency injection</emphasis>
- exists in both JSF and EJB3, as well as in numerous so-called "lightweight containers". Most of
+ exists in both JSF and EJB3, as well as in numerous simplistic containers. Most of
these containers emphasize injection of components that implement <emphasis>stateless services</emphasis>.
Even when injection of stateful components is supported (such as in JSF), it is virtually useless
for handling application state because the scope of the stateful component cannot be defined with
@@ -191,7 +184,7 @@
different, safely isolated, conversation. Applications may even take advantage of <emphasis>workspace
management</emphasis>, allowing the user to switch between conversations (workspaces) in a single
browser tab. Seam provides not only correct multi-window operation, but also multi-window-like
- operation in a single window!
+ operation within a single window.
</para>
</listitem>
</varlistentry>
@@ -201,19 +194,19 @@
<listitem>
<para>
Traditionally, the Java community has been in a state of deep confusion about precisely
- what kinds of meta-information counts as configuration. J2EE and popular "lightweight"
- containers have provided XML-based deployment descriptors both for things which are
- truly configurable between different deployments of the system, and for any other kinds
- or declaration which can not easily be expressed in Java. Java 5 annotations changed
+ what kind of meta-information counts as configuration. J2EE and popular simplistic
+ containers have provided XML-based deployment descriptors for code which is
+ truly configurable between different deployments of the system, and for all other kinds
+ or declarations which can not easily be expressed in Java; Java 5 annotations changed
all this.
</para>
<para>
- EJB 3.0 embraces annotations and "configuration by exception" as the easiest way to provide
+ EJB 3.0 embraces annotations and <emphasis>configuration by exception</emphasis> as the easiest way to provide
information to the container in a declarative form. Unfortunately, JSF is still heavily
dependent on verbose XML configuration files. Seam extends the annotations provided by
EJB 3.0 with a set of annotations for declarative state management and declarative
- context demarcation. This lets you eliminate the noisy JSF managed bean declarations
- and reduce the required XML to just that information which truly belongs in XML
+ context demarcation. This allows for the elimination of the noisy JSF managed bean declarations
+ and reduces the required XML to just that information which truly belongs in XML
(the JSF navigation rules).
</para>
</listitem>
@@ -235,10 +228,10 @@
</varlistentry>
<varlistentry>
- <term><emphasis>The specs ain't perfect</emphasis></term>
+ <term><emphasis>Improving upon Java EE</emphasis></term>
<listitem>
<para>
- We think the latest incarnation of Java EE is great. But we know it's never going to be
+ The latest incarnation of Java EE is a great step forward and we know it's never going to be
perfect. Where there are holes in the specifications (for example, limitations in the
JSF lifecycle for GET requests), Seam fixes them. And the authors of Seam are working
with the JCP expert groups to make sure those fixes make their way back into the next
@@ -252,18 +245,18 @@
<listitem>
<para>
Today's web frameworks think too small. They let you get user input off a form and
- into your Java objects. And then they leave you hanging. A truly complete web application
+ into your Java objects. A truly complete web application
framework should address problems like persistence, concurrency, asynchronously, state
management, security, email, messaging, PDF and chart generation, workflow, wikitext
rendering, webservices, caching and more. Once you scratch the surface of Seam, you'll
- be amazed at how many problems become simpler...
+ be amazed at how many problems become simpler.
</para>
<para>
Seam integrates JPA and Hibernate3 for persistence, the EJB Timer Service and Quartz
- for lightweight asynchronously, jBPM for workflow, JBoss Rules for business rules, Meldware
- Mail for email, Hibernate Search and Lucene for full text search, JMS for messaging and JBoss
- Cache for page fragment caching. Seam layers an innovative rule-based security framework over
- JAAS and JBoss Rules. There's even JSF tag libraries for rendering PDF, outgoing email, charts
+ for simple asynchronous operations, jBPM for workflow, Meldware
+ Mail for email, Hibernate Search and Lucene for full text search, JMS for messaging, JBoss
+ Cache for page fragment caching and JBoss Rules for business rules, layering an innovative rule-based security framework over
+ JAAS and JBoss Rules. Also included is JSF tag libraries for rendering PDF, outgoing email, charts
and wikitext. Seam components may be called synchronously as a Web Service, asynchronously
from client-side JavaScript or Google Web Toolkit or, of course, directly from JSF.
</para>
@@ -290,7 +283,7 @@
</mediaobject>
<para>
- It turns out that the combination of Seam, JSF and EJB3 is <emphasis>the</emphasis> simplest way
+ It turns out that the combination of Seam, JSF and EJB3 is the simplest way
to write a complex web application in Java. You won't believe how little code is required!
</para>
Modified: projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Migration.xml
===================================================================
--- projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Migration.xml 2009-02-11 02:06:04 UTC (rev 84082)
+++ projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Migration.xml 2009-02-11 02:46:19 UTC (rev 84083)
@@ -13,11 +13,11 @@
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
of changes introduced between Seam 1.2 and Seam 2, this may not always be
- a straightforward process!
+ 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,15 +26,15 @@
<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>
<programlisting>~/seam_2_0$ ./seam setup</programlisting>
<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
+ Customize the defaults as needed. You will want to set the location of the
+ 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
@@ -59,7 +59,7 @@
<para>
This requires more work, but is suitable for more complex projects. The
- steps below may not be an exhaustive list, so if you have to any extra
+ steps below may not be an exhaustive list, so if you have any extra
steps please report them through the Customer Support Portal.
</para>
@@ -69,13 +69,12 @@
<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
- 1.2 which used JSF 1.2.
+ edition of Seam, JBoss Enterprise Application Platform 4.2 and 4.3 ship with version 2.0.2.FP of Seam, which uses 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>
@@ -125,7 +124,7 @@
</para>
<para>
- In Seam 2, you need specify a listener (just as you did in Seam
+ In Seam 2, you need to specify a listener (just as you did in Seam
1.2):
</para>
@@ -170,8 +169,8 @@
</servlet-mapping>]]></programlisting>
<para>
- Seam 2 will automatically install RichFaces' Ajax4JSF if it present
- in your project so you should make sure the Ajax4JSF filter isn't
+ Seam 2 will automatically install RichFaces' Ajax4JSF if it is present
+ in your project so you should make sure the Ajax4JSF filter is not
declared:
</para>
@@ -189,7 +188,7 @@
</filter-mapping>-->]]></programlisting>
<para>
- Next, we'll describe the changes you need to make to your JSF
+ Next, we will describe the changes you need to make to your JSF
<literal>ViewHandler</literal> configuration. Previously the
configuration you used depended on whether you were using Seam's EL
enhancements or Ajax4JSF or both. In Seam 2 you should use the
@@ -203,7 +202,7 @@
Ajax4JSF distributed with Seam 1.2 required you to specify which
<literal>ViewHandler</literal> to use when it was in use. Make sure
that the Ajax4JSF configuration is removed from your
- <literal>web.xml:</literal>:
+ <literal>web.xml:</literal> file:
</para>
<programlisting role="XML"><![CDATA[<!--Remove for Seam 2-->
@@ -235,7 +234,7 @@
<literal>SeamPhaseListener</literal> (Seam Managed Transaction were
are disabled) or <literal>SeamTransactionalPhaseListener</literal>
(Seam Managed Transactions are enabled) in
- <literal>faces-config.xml</literal>. Seam 2 lets you enable or
+ <literal>faces-config.xml</literal>. Seam 2 allows you to enable or
disable Seam Managed Transactions in
<literal>components.xml</literal>, and installs the phase listener
for you. Therefore, you should remove any reference to
@@ -253,9 +252,8 @@
<programlisting role="XML"><![CDATA[<core:init transaction-management-enabled="false"/>]]></programlisting>
<para>
- To workaround a bug, you may have specified
- <literal>SeamELResolver</literal> in
- <literal>faces-config.xml</literal>. This is no longer required.
+ You may have specified <literal>SeamELResolver</literal> in
+ <literal>faces-config.xml</literal> as an old workaround to a known bug; this is no longer required.
</para>
<para>
@@ -275,9 +273,9 @@
If you have an EAR application there are some deployment structure
changes needed. You should move all the dependencies which you
previously declared as modules in <literal>application.xml</literal>
- in the <literal>lib/</literal> directory of your EAR
+ to the <literal>lib/</literal> directory of your EAR
<emphasis>except</emphasis> <literal>jboss-seam.jar</literal> which
- should be declared as an ejb module in
+ should be declared as an EJB module in
<literal>application.xml</literal>. Remove the unneeded module
declarations from <literal>application.xml</literal>.
</para>
@@ -313,7 +311,7 @@
</warning>
<para>
- If you want to run tests using the Eclipse TestNG plugin, you'll
+ If you want to run tests using the Eclipse TestNG plugin, you will
need to add these jars to the top of your TestNG classpath. Using
the Run Dialog, select the xml suite to run, and add
<literal>/lib/test/jboss-embedded-all.jar</literal>,
@@ -325,13 +323,13 @@
<literal>/bootstrap</literal> as the first entries in the
<emphasis>User classpath</emphasis>.
</para>
-
+ <note>
<para>
- Note that JBoss Embedded is able to bootstrap a datasource from a
+ JBoss Embedded is able to bootstrap a datasource from a
<literal>-ds.xml</literal> file, so there is no longer a need for
<literal>jboss-beans.xml</literal>.
</para>
-
+ </note>
</section>
</section>
@@ -341,8 +339,8 @@
<important>
<para>
- Don't forget to update the XSD's in <literal>pages.xml</literal> and
- <literal>components.xml</literal> to point at the ones for Seam 2.
+ Do not forget to update the XSD's in <literal>pages.xml</literal> and
+ <literal>components.xml</literal> to point to those for Seam 2.
Just change the suffix from <literal>-1.2.xsd</literal> to
<literal>-2.0.xsd</literal>.
</para>
@@ -359,8 +357,8 @@
</para>
<para>
- You'll need to update both your <literal>components.xml</literal>
- and any references in Java code.
+ You will need to update both your <literal>components.xml</literal> file
+ and any references in the Java code.
</para>
<para>
@@ -862,7 +860,7 @@
<para>
The <literal>conversation-is-long-running-parameter</literal>
attribute has been removed from Seam (and doesn't have a
- replacement), remove it from <literal><core:init /></literal>.
+ replacement); remove it from <literal><core:init /></literal>.
</para>
<para>
@@ -965,7 +963,7 @@
</s:decorate>
</h:form>]]></programlisting>
- <para>If you don't provide an id to <s:decorate>, one will be generated by JSF.</para>
+ <para>If you do not provide an id to <s:decorate>, one will be generated by JSF.</para>
</section>
@@ -1013,7 +1011,7 @@
the <literal>build.xml</literal> file.</para>
<para>To accommodate a change in the RichFaces panel, you need to add the following
- style to your stylesheet. Otherwise, you're search criteria block in pages
+ style to your stylesheet. Otherwise, your search criteria block in pages
created by generate-entities will bleed into the table of results.</para>
<programlisting><![CDATA[.rich-stglpanel-body {
Modified: projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Tutorial.xml
===================================================================
--- projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Tutorial.xml 2009-02-11 02:06:04 UTC (rev 84082)
+++ projects/docs/enterprise/4.3.4.1/Seam/Seam_Reference_Guide/en-US/Tutorial.xml 2009-02-11 02:46:19 UTC (rev 84083)
@@ -6,7 +6,7 @@
<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> In this tutorial, we will assume that you are using JBoss EAP 4.3.</para>
<para> The directory structure of each example in Seam follows this pattern: </para>
@@ -100,11 +100,11 @@
<title>Your first Seam application: the registration example</title>
<para> The registration example is a fairly trivial application that lets a new user store his username, real
- name and password in the database. The example isn't intended to show off all of the cool functionality of
+ name and password in the database. The example isn't intended to show off all of the interesting functionality of
Seam. However, it demonstrates the use of an EJB3 session bean as a JSF action listener, and basic
configuration of Seam. </para>
- <para> We'll go slowly, since we realize you might not yet be familiar with EJB 3.0. </para>
+ <para> We will go slowly, so you can become familiar with EJB 3.0. </para>
<para> The start page displays a very basic form with three input fields. Try filling them in and then
submitting the form. This will save a user object in the database. </para>
@@ -229,7 +229,7 @@
define accessor methods. These are needed when this component is used by JSF in the
render response and update model values phases. </para>
- <para> An empty constructor is both required by both the EJB specification and by Seam.
+ <para> An empty constructor is required by both the EJB specification and by Seam.
</para>
<para> The <literal>@NotNull</literal> and <literal>@Length</literal> annotations are
@@ -242,7 +242,7 @@
<!-- </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
+ <para> We will see below that the properties of our <literal>User</literal> class are bound
directly to JSF components and are populated by JSF during the update model values phase. We
don't need any tedious glue code to copy data back and forth between the JSP pages and the
entity bean domain model. </para>
More information about the jboss-cvs-commits
mailing list