[jboss-cvs] JBossAS SVN: r105528 - projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Jun 1 21:30:14 EDT 2010
Author: misty at redhat.com
Date: 2010-06-01 21:30:13 -0400 (Tue, 01 Jun 2010)
New Revision: 105528
Modified:
projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Concepts.xml
Log:
JBPAPP-4387
Modified: projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Concepts.xml
===================================================================
--- projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Concepts.xml 2010-06-02 01:19:47 UTC (rev 105527)
+++ projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Concepts.xml 2010-06-02 01:30:13 UTC (rev 105528)
@@ -137,14 +137,12 @@
The context variable name identifies a component instance within a context. (The context variable name usually matches the component name.) You can programmatically access a named component instance in a particula scope with the <literal>Contexts</literal> class, which provides access to several thread-bound instances of the <literal>Context</literal> interface:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[User user = (User) Contexts.getSessionContext().get("user");
-]]></programlisting>
+<programlisting language="Java" role="JAVA">User user = (User) Contexts.getSessionContext().get("user");</programlisting>
<para>
You may also set or change the value associated with a name:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[Contexts.getSessionContext().set("user", user);
-]]></programlisting>
+<programlisting language="Java" role="JAVA">Contexts.getSessionContext().set("user", user);</programlisting>
<para>
However, components are usually obtained from a context via <emphasis>injection</emphasis>. Component instances are subsequently given to contexts via <emphasis>outjection</emphasis>.
</para>
@@ -346,31 +344,30 @@
To perform actions such as bijection, context demarcation, and validation, Seam must intercept component invocations. For JavaBeans, Seam controls component instantiation completely, and no special configuration is required. For entity beans, interception is not required, since bijection and context demarcation are not defined. For session beans, an EJB interceptor must be registered for the session bean component. This can be done with an annotation, as follows:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Stateless
+<programlisting language="Java" role="JAVA">@Stateless
@Interceptors(SeamInterceptor.class)
-public class LoginAction implements Login { ... }
-]]></programlisting>
+public class LoginAction implements Login { ... }</programlisting>
<para>
However, it is better to define the interceptor in <filename>ejb-jar.xml</filename>:
</para>
-<programlisting language="XML" role="XML"><![CDATA[<interceptors>
- <interceptor>
- <interceptor-class>
+<programlisting language="XML" role="XML">
+ <interceptors>
+ <interceptor>
+ <interceptor-class>
org.jboss.seam.ejb.SeamInterceptor
- </interceptor-class>
- </interceptor>
-</interceptors>
+ </interceptor-class>
+ </interceptor>
+</interceptors>
-<assembly-descriptor>
- <interceptor-binding>
- <ejb-name>*</ejb-name>
- <interceptor-class>
+<assembly-descriptor>
+ <interceptor-binding>
+ <ejb-name>*</ejb-name>
+ <interceptor-class>
org.jboss.seam.ejb.SeamInterceptor
- </interceptor-class>
- </interceptor-binding>
-</assembly-descriptor>
-]]></programlisting>
+ </interceptor-class>
+ </interceptor-binding>
+</assembly-descriptor></programlisting>
</section>
<section>
@@ -379,10 +376,9 @@
All Seam components require names. Assign a name with the <literal>@Name</literal> annotation:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("loginAction")
+<programlisting language="Java" role="JAVA">@Name("loginAction")
@Stateless
-public class LoginAction implements Login { ... }
-]]></programlisting>
+public class LoginAction implements Login { ... }</programlisting>
<para>
This is the <emphasis>Seam component name</emphasis>, and does not relate to any other name defined by the EJB specification. However, Seam component names work like JSF managed bean names, and can be thought of in identical terms.
</para>
@@ -396,24 +392,21 @@
For very large applications, and for built-in Seam components, qualified component names are often used to avoid naming conflicts.
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("com.jboss.myapp.loginAction")
+<programlisting language="Java" role="JAVA">@Name("com.jboss.myapp.loginAction")
@Stateless
-public class LoginAction implements Login { ... }
-]]></programlisting>
+public class LoginAction implements Login { ... }</programlisting>
<para>
The qualified component name can be used both in Java code and in JSF's expression language:
</para>
-<programlisting language="XML" role="XHTML"><![CDATA[<h:commandButton type="submit" value="Login"
- action="#{com.jboss.myapp.loginAction.login}"/>
-]]></programlisting>
+<programlisting language="XML" role="XML"><![CDATA[<h:commandButton type="submit" value="Login"
+ action="#{com.jboss.myapp.loginAction.login}"/>]]></programlisting>
<para>
Since this is noisy, Seam also provides a means of aliasing a qualified name to a simple name. Add a line like this to the <filename>components.xml</filename> file:
</para>
<programlisting language="XML" role="XML"><![CDATA[<factory name="loginAction" scope="STATELESS"
- value="#{com.jboss.myapp.loginAction}"/>
-]]></programlisting>
+ value="#{com.jboss.myapp.loginAction}"/>]]></programlisting>
<para>
All built-in Seam components have qualified names, but can be accessed through their unqualified names with Seam's <emphasis>namespace-import</emphasis> feature. The <filename>components.xml</filename> file included in the Seam JAR defines the following namespaces:
</para>
@@ -437,8 +430,7 @@
<import>org.jboss.seam.captcha</import>
<import>org.jboss.seam.excel.exporter</import>
<!-- ... --->
-</components>
-]]></programlisting>
+</components>]]></programlisting>
<para>
When attempting to resolve an unqualified name, Seam will check each of these namespaces, in order. Additional application-specific namespaces can be included in your application's <filename>components.xml</filename> file.
</para>
@@ -450,11 +442,10 @@
The <literal>@Scope</literal> annotation lets us override the scope (context) of a component to define the context a component instance is bound to when instantiated by Seam.
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("user")
+<programlisting language="Java" role="JAVA">@Name("user")
@Entity
@Scope(SESSION)
-public class User { ... }
-]]></programlisting>
+public class User { ... }</programlisting>
<para>
<literal>org.jboss.seam.ScopeType</literal> defines an enumeration of possible scopes.
</para>
@@ -466,23 +457,21 @@
Some Seam component classes can fulfill multiple roles in the system. For example, the <literal>User</literal> class is usually a session-scoped component representing the current user, but in user administration screens becomes 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 Seam component <emphasis>instance</emphasis> can be bound to multiple context variables, but this lets us do it at the class level to take advantage of automatic instantiation.)
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("user")
+<programlisting language="Java" role="JAVA">@Name("user")
@Entity
@Scope(CONVERSATION)
@Role(name="currentUser", scope=SESSION)
-public class User { ... }
-]]></programlisting>
+public class User { ... }</programlisting>
<para>
The <literal>@Roles</literal> annotation lets us specify additional roles as required.
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("user")
+<programlisting language="Java" role="JAVA">@Name("user")
@Entity
@Scope(CONVERSATION)
@Roles({ @Role(name="currentUser", scope=SESSION),
@Role(name="tempUser", scope=EVENT)})
-public class User { ... }
-]]></programlisting>
+public class User { ... }</programlisting>
</section>
<section>
@@ -494,9 +483,7 @@
The built-in components may be injected like any other Seam component, but they also provide convenient static <literal>instance()</literal> methods:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[FacesMessages.instance().add("Welcome back, #{user.name}!");
-]]>
-</programlisting>
+<programlisting language="Java" role="JAVA">FacesMessages.instance().add("Welcome back, #{user.name}!");</programlisting>
</section>
</section>
@@ -539,27 +526,24 @@
The <literal>@In</literal> annotation specifies that a value should be injected, either into an instance variable:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("loginAction")
+<programlisting language="Java" role="JAVA">@Name("loginAction")
@Stateless
public class LoginAction implements Login {
@In User user;
...
-}
-]]>
-</programlisting>
+}</programlisting>
<para>
or into a setter method:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("loginAction")
+<programlisting language="Java" role="JAVA">@Name("loginAction")
@Stateless
public class LoginAction implements Login {
User user;
@In
public void setUser(User user) { this.user=user; }
- ...
-}
-]]></programlisting>
+ ...
+ }</programlisting>
<para>
By default, Seam performs a priority search of all contexts, using the name of the property or instance variable being injected. You may wish to specify the context variable name explicitly, using, for example, <literal>@In("currentUser")</literal>.
</para>
@@ -573,13 +557,12 @@
You can even inject the value of an expression:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("loginAction")
+<programlisting language="Java" role="JAVA">@Name("loginAction")
@Stateless
public class LoginAction implements Login {
@In("#{user.username}") String username;
...
-}
-]]></programlisting>
+}</programlisting>
<para>
Injected values are disinjected (that is, set to <literal>null</literal>) immediately after method completion and outjection.
</para>
@@ -590,18 +573,17 @@
The <literal>@Out</literal> annotation specifies that an attribute should be outjected, either from an instance variable:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("loginAction")
+<programlisting language="Java" role="JAVA">@Name("loginAction")
@Stateless
public class LoginAction implements Login {
@Out User user;
...
-}
-]]></programlisting>
+}</programlisting>
<para>
or from a getter method:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("loginAction")
+<programlisting language="Java" role="JAVA">@Name("loginAction")
@Stateless
public class LoginAction implements Login {
User user;
@@ -611,25 +593,23 @@
return user;
}
...
-}
-]]></programlisting>
+}</programlisting>
<para>
An attribute may be both injected and outjected:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("loginAction")
+<programlisting language="Java" role="JAVA">@Name("loginAction")
@Stateless
public class LoginAction implements Login {
@In
@Out User user;
...
-}
-]]></programlisting>
+}</programlisting>
<para>
or:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("loginAction")
+<programlisting language="Java" role="JAVA">@Name("loginAction")
@Stateless
public class LoginAction implements Login {
User user;
@@ -643,8 +623,7 @@
public User getUser() {
return user; }
...
-}
-]]></programlisting>
+}</programlisting>
</section>
<section>
@@ -725,26 +704,24 @@
Suppose we have a component named <literal>messageSender</literal> that talks to a JMS queue.
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("messageSender")
+<programlisting language="Java" role="JAVA">@Name("messageSender")
public class MessageSender {
public void sendMessage() {
//do something with JMS
}
-}
- ]]></programlisting>
+}</programlisting>
<para>
In our unit tests, there is no available JMS queue, so we would like to stub out this method. We'll create a <emphasis>mock</emphasis> component that exists in the classpath when unit tests are running, but is never deployed with the application:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("messageSender")
+<programlisting language="Java" role="JAVA">@Name("messageSender")
@Install(precedence=MOCK)
public class MockMessageSender extends MessageSender {
public void sendMessage() {
//do nothing!
}
-}
-]]></programlisting>
+}</programlisting>
<para>
The <literal>precedence</literal> helps Seam decide which version to use when it finds both components in the classpath.
</para>
@@ -759,7 +736,7 @@
Before Seam, even the simplest log message required verbose code:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[private static final Log log = LogFactory.getLog(CreateOrderAction.class);
+<programlisting language="Java" role="JAVA">private static final Log log = LogFactory.getLog(CreateOrderAction.class);
public Order createOrder(User user, Product product, int quantity) {
if ( log.isDebugEnabled() ) {
@@ -767,22 +744,19 @@
" product: " + product.name() + " quantity: " + quantity);
}
return new Order(user, product, quantity);
-}
-]]></programlisting>
+}</programlisting>
<para>
Seam provides a logging API that simplifies this code significantly:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Logger private Log log;
+<programlisting language="Java" role="JAVA">@Logger private Log log;
public Order createOrder(User user, Product product, int quantity) {
log.debug("Creating new order for user: #0 product: #1 quantity: #2",
user.username(), product.name(), quantity);
return new Order(user, product, quantity);
-}
-
-]]></programlisting>
+}</programlisting>
<para>
Except for entity bean components (which require the <literal>log</literal> variable to be static), this will work regardless of whether the <literal>log</literal> variable is declared static.
</para>
@@ -794,13 +768,12 @@
If <literal>User</literal> and <literal>Product</literal> are Seam components available in the current contexts, the code is even more concise:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Logger private Log log;
+<programlisting language="Java" role="JAVA">@Logger private Log log;
public Order createOrder(User user, Product product, int quantity) {
log.debug("Creating new order for user: #{user.username}
product: #{product.name} quantity: #0", quantity);
return new Order(user, product, quantity);
-}
-]]></programlisting>
+}</programlisting>
<para>
Seam logging automatically chooses whether to send output to log4j or JDK logging — if log4j is in the classpath, it will be used; if not, Seam uses JDK logging.
</para>
@@ -818,7 +791,7 @@
For session- or conversation-scoped JavaBean components, Seam automatically forces replication by calling <literal>setAttribute()</literal> once in every request where the component was invoked by the application. However, this strategy is inefficient for read-mostly components. 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,
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("account")
+<programlisting language="Java" role="JAVA">@Name("account")
public class Account extends AbstractMutable {
private BigDecimal balance;
public void setBalance(BigDecimal balance) {
@@ -830,13 +803,12 @@
return balance;
}
...
-}
-]]></programlisting>
+}</programlisting>
<para>
Or, you can use the <literal>@ReadOnly</literal> annotation to achieve a similar effect:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("account")
+<programlisting language="Java" role="JAVA">@Name("account")
public class Account {
private BigDecimal balance;
public void setBalance(BigDecimal balance) {
@@ -848,13 +820,12 @@
return balance;
}
...
-}
-]]></programlisting>
+}</programlisting>
<para>
For session- or conversation-scoped entity bean components, Seam automatically forces replication by calling <literal>setAttribute()</literal> once in every request, unless the (conversation-scoped) entity is currently associated with a Seam-managed persistence context, in which case replication is unnecessary. 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 entity bean instance. For example:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Stateful @Name("account")
+<programlisting language="Java" role="JAVA">@Stateful @Name("account")
public class AccountManager extends AbstractMutable {
private Account account; // an entity bean
@Unwrap
@@ -862,8 +833,7 @@
return account;
}
...
-}
-]]></programlisting>
+}</programlisting>
<para>
Note that the <literal>EntityHome</literal> class in the Seam Application Framework is an excellent example of managing an entity bean instance using a Seam component.
</para>
@@ -878,21 +848,19 @@
The <emphasis>factory component pattern</emphasis> lets a Seam component act as the instantiator for a non-component object. A <emphasis>factory method</emphasis> will be called when a context variable is referenced but has no value bound to it. Factory methods are defined with the <literal>@Factory</literal> annotation. The factory method binds a value to the context variable, and determines the scope of the bound value. There are two styles of factory method. The first style returns a value, which is bound to the context by Seam:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Factory(scope=CONVERSATION)
-public List<Customer> getCustomerList() {
+<programlisting language="Java" role="JAVA">@Factory(scope=CONVERSATION)
+public List<Customer> getCustomerList() {
return ... ;
-}
-]]></programlisting>
+}</programlisting>
<para>
The second style is a method of type <literal>void</literal>, which binds the value to the context variable itself:
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@DataModel List<Customer> customerList;
+<programlisting language="Java" role="JAVA">@DataModel List<Customer> customerList;
@Factory("customerList")
public void initCustomerList() {
customerList = ... ;
-}
-]]></programlisting>
+}</programlisting>
<para>
In either case, the factory method is called when the <literal>customerList</literal> context variable is referenced, and its value is null. The factory method then has no further part in the lifecycle of the value. The <emphasis>manager component pattern</emphasis> is an even more powerful pattern. In this case, a Seam component bound to a context variable manages the value of the context variable while remaining invisible to clients.
</para>
@@ -900,29 +868,28 @@
A manager component is any component with an <literal>@Unwrap</literal> method. This method returns the value that will be visible to clients, and is called every time a context variable is referenced.
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("customerList")
+<programlisting language="Java" role="JAVA">@Name("customerList")
@Scope(CONVERSATION)
public class CustomerListManager {
...
@Unwrap
- public List<Customer> getCustomerList() {
+ public List<Customer> getCustomerList() {
return ... ;
}
-}
-]]></programlisting>
+}</programlisting>
<para>
The manager component pattern is especially useful where more control is required over component lifecycle. For example, if you have a heavyweight object that needs a cleanup operation when the context ends, you could <literal>@Unwrap</literal> the object, and perform cleanup in the <literal>@Destroy</literal> method of the manager component.
</para>
-<programlisting language="Java" role="JAVA"><![CDATA[@Name("hens")
+<programlisting language="Java" role="JAVA">@Name("hens")
@Scope(APPLICATION)
public class HenHouse {
- Set<Hen> hens;
+ Set<Hen> hens;
@In(required=false) Hen hen;
@Unwrap
- public List<Hen> getHens()
+ public List<Hen> getHens()
{
if (hens == null) {
// Setup our hens }
@@ -945,8 +912,7 @@
}
...
-
-}]]></programlisting>
+}</programlisting>
<para>
Here, the managed component observes many events that change the underlying object. The component manages these actions itself, and because the object is unwrapped each time it is accessed, a consistent view is provided.
</para>
More information about the jboss-cvs-commits
mailing list