[jboss-cvs] JBossAS SVN: r105539 - 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 23:40:25 EDT 2010
Author: misty at redhat.com
Date: 2010-06-01 23:40:24 -0400 (Tue, 01 Jun 2010)
New Revision: 105539
Modified:
projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Framework.xml
Log:
JBPAPP-4387
Modified: projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Framework.xml
===================================================================
--- projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Framework.xml 2010-06-02 03:33:46 UTC (rev 105538)
+++ projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Framework.xml 2010-06-02 03:40:24 UTC (rev 105539)
@@ -16,7 +16,7 @@
The components provided by the Seam Application Framework can be used in two separate approaches. The first approach is to install and configure an instance of the component in <filename>components.xml</filename>, as with other built-in Seam components. For example, the following fragment (from <filename>components.xml</filename>) installs a component that performs basic CRUD operations for a <literal>Person</literal> entity:
</para>
-<programlisting role="XML"><![CDATA[<framework:entity-home name="personHome" entity-class="eg.Person"
+<programlisting language="XML" role="XML"><![CDATA[<framework:entity-home name="personHome" entity-class="eg.Person"
entity-manager="#{personDatabase}">
<framework:id>#{param.personId}</framework:id>
</framework:entity-home>]]>
@@ -25,13 +25,13 @@
If this approach seems too XML-heavy, you can approach this through extension:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
+<programlisting language="Java" role="JAVA">@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
@In EntityManager personDatabase;
public EntityManager getEntityManager() {
return personDatabase;
}
-}]]>
+}
</programlisting>
<para>
The major advantage to the second approach is that the framework classes were designed for extension and customization, so it is easy to add extra functionality or override the built-in functionality.
@@ -40,24 +40,24 @@
Another advantage is that you have the option of using EJB stateful session beans (or plain JavaBean components) as your classes:
</para>
-<programlisting role="JAVA"><![CDATA[@Stateful
+<programlisting language="Java" role="JAVA">@Stateful
@Name("personHome")
-public class PersonHome extends EntityHome<Person>
- implements LocalPersonHome { }]]>
+public class PersonHome extends EntityHome<Person>
+ implements LocalPersonHome { }
</programlisting>
<para>
You can also make your classes stateless session beans. In this case you <emphasis>must</emphasis> use injection to provide the persistence context, even if it is called <literal>entityManager</literal>:
</para>
-<programlisting role="JAVA"><![CDATA[@Stateless
+<programlisting language="Java" role="JAVA">@Stateless
@Name("personHome")
-public class PersonHome extends EntityHome<Person>
+public class PersonHome extends EntityHome<Person>
implements LocalPersonHome {
@In EntityManager entityManager;
public EntityManager getPersistenceContext() {
entityManager;
}
-}]]>
+}
</programlisting>
<para>
At present, the Seam Application Framework provides four main built-in components: <literal>EntityHome</literal> and <literal>HibernateEntityHome</literal> for CRUD, and <literal>EntityQuery</literal> and <literal>HibernateEntityQuery</literal> for queries.
@@ -76,27 +76,27 @@
A Home object provides persistence operations for a particular entity class. Suppose we have our <literal>Person</literal> class:
</para>
-<programlisting role="JAVA"><![CDATA[@Entity
+<programlisting language="Java" role="JAVA">@Entity
public class Person {
@Id private Long id;
private String firstName;
private String lastName;
private Country nationality;
//getters and setters...
-}]]>
+}
</programlisting>
<para>
We can define a <literal>personHome</literal> component either through configuration:
</para>
-<programlisting role="XML"><![CDATA[<framework:entity-home name="personHome" entity-class="eg.Person" />]]>
+<programlisting language="XML" role="XML"><![CDATA[<framework:entity-home name="personHome" entity-class="eg.Person" />]]>
</programlisting>
<para>
Or through extension:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {}]]>
+<programlisting language="Java" role="JAVA">@Name("personHome")
+public class PersonHome extends EntityHome<Person> {}
</programlisting>
<para>
A Home object provides operations like <literal>persist()</literal>, <literal>remove()</literal>, <literal>update()</literal> and <literal>getInstance()</literal>. Before you can call <literal>remove()</literal> or <literal>update()</literal>, you must set the identifier of the object you are interested in, using the <literal>setId()</literal> method.
@@ -105,7 +105,7 @@
For example, we can use a Home directly from a JSF page:
</para>
-<programlisting role="XHTML"><![CDATA[<h1>Create Person</h1>
+<programlisting language="XML" role="XML"><![CDATA[<h1>Create Person</h1>
<h:form>
<div>
First name: <h:inputText value="#{personHome.instance.firstName}"/>
@@ -123,26 +123,26 @@
It is useful to be able to refer to <literal>Person</literal> as <literal>person</literal>, so we will add that line to <filename>components.xml</filename> (if we are using configuration):
</para>
-<programlisting role="XML"><![CDATA[<factory name="person" value="#{personHome.instance}"/>
+<programlisting language="XML" role="XML"><![CDATA[<factory name="person" value="#{personHome.instance}"/>
<framework:entity-home name="personHome" entity-class="eg.Person" />]]>
</programlisting>
<para>
Or, if we are using extension, we can add a <literal>@Factory</literal> method to <literal>PersonHome</literal>:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
+<programlisting language="Java" role="JAVA">@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
@Factory("person")
public Person initPerson() {
return getInstance();
}
-}]]>
+}
</programlisting>
<para>
This change simplifies our JSF page to the following:
</para>
-<programlisting role="XHTML"><![CDATA[<h1>Create Person</h1>
+<programlisting language="XML" role="XML"><![CDATA[<h1>Create Person</h1>
<h:form>
<div>
First name: <h:inputText value="#{person.firstName}"/>
@@ -160,7 +160,7 @@
This is all the code required to create new <literal>Person</literal> entries. If we want to be able to display, update, and delete pre-existing <literal>Person</literal> entries in the database, we need to be able to pass the entry identifier to the <literal>PersonHome</literal>. An excellent method is through page parameters:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/editPerson.jsp">
<param name="personId" value="#{personHome.id}"/>
</page>
@@ -170,7 +170,7 @@
Now we can add the extra operations to our JSF page:
</para>
-<programlisting role="XHTML"><![CDATA[<h1>
+<programlisting language="XML" role="XML"><![CDATA[<h1>
<h:outputText rendered="#{!personHome.managed}" value="Create Person"/>
<h:outputText rendered="#{personHome.managed}" value="Edit Person"/>
</h1>
@@ -198,7 +198,7 @@
If we need to create <literal>Person</literal> entries with their nationality initialized, we can do so easily. Via configuration:
</para>
-<programlisting role="XML"><![CDATA[<factory name="person" value="#{personHome.instance}"/>
+<programlisting language="XML" role="XML"><![CDATA[<factory name="person" value="#{personHome.instance}"/>
<framework:entity-home name="personHome" entity-class="eg.Person"
new-instance="#{newPerson}"/>
<component name="newPerson" class="eg.Person">
@@ -209,8 +209,8 @@
Or via extension:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
+<programlisting language="Java" role="JAVA">@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
@In Country country;
@Factory("person")
public Person initPerson() {
@@ -219,7 +219,7 @@
protected Person createInstance() {
return new Person(country);
}
-}]]>
+}
</programlisting>
<para>
The <literal>Country</literal> could be an object managed by another Home object, for example, <literal>CountryHome</literal>.
@@ -228,8 +228,8 @@
To add more sophisticated operations (association management, etc.), we simply add methods to <literal>PersonHome</literal>.
</para>
-<programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
+<programlisting language="Java" role="JAVA">@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
@In Country country;
@Factory("person")
public Person initPerson() {
@@ -242,7 +242,7 @@
getInstance().setCountry(country);
update();
}
-}]]>
+}
</programlisting>
<para>
The Home object raises an <literal>org.jboss.seam.afterTransactionSuccess</literal> event when a transaction (a call to <literal>persist()</literal>, <literal>update()</literal> or <literal>remove()</literal>) succeeds. By observing this event, we can refresh our querues when the underlying entities change. If we only want to refresh certain queries when a particular entry is persisted, updated, or removed, we can observe the <literal>org.jboss.seam.afterTransactionSuccess.<![CDATA[<name>]]></literal> (where <literal><![CDATA[<name>]]></literal> is the name of the entity).
@@ -251,7 +251,7 @@
The Home object automatically displays Faces messages when an operation succeeds. To customize these messages we can, again, use configuration:
</para>
-<programlisting role="XML"><![CDATA[<factory name="person" value="#{personHome.instance}"/>
+<programlisting language="XML" role="XML"><![CDATA[<factory name="person" value="#{personHome.instance}"/>
<framework:entity-home name="personHome" entity-class="eg.Person"
new-instance="#{newPerson}">
<framework:created-message>
@@ -272,8 +272,8 @@
Or extension:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
+<programlisting language="Java" role="JAVA">@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
@In Country country;
@Factory("person")
public Person initPerson() {
@@ -294,15 +294,15 @@
return createValueExpression("Person #{person.firstName}
#{person.lastName} deleted");
}
-}]]>
+}
</programlisting>
<para>
The best way to specify messages is to put them in a resource bundle known to Seam — by default, the bundle named <literal>messages</literal>.
</para>
-<programlisting><![CDATA[Person_created=New person #{person.firstName} #{person.lastName} created
+<programlisting language="Java" role="JAVA">Person_created=New person #{person.firstName} #{person.lastName} created
Person_deleted=Person #{person.firstName} #{person.lastName} deleted
-Person_updated=Person #{person.firstName} #{person.lastName} updated]]>
+Person_updated=Person #{person.firstName} #{person.lastName} updated
</programlisting>
<para>
This enables internationalization, and keeps your code and configuration clean of presentation concerns.
@@ -316,13 +316,13 @@
If we need a list of all <literal>Person</literal> instances in the database, we can use a Query object, like the following.
</para>
-<programlisting role="XML"><![CDATA[<framework:entity-query name="people" ejbql="select p from Person p"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<framework:entity-query name="people" ejbql="select p from Person p"/>]]>
</programlisting>
<para>
We can use it from a JSF page:
</para>
-<programlisting role="XHTML"><![CDATA[<h1>List of people</h1>
+<programlisting language="XML" role="XML"><![CDATA[<h1>List of people</h1>
<h:dataTable value="#{people.resultList}" var="person">
<h:column>
<s:link view="/editPerson.jsp"
@@ -336,14 +336,14 @@
If you require pagination support:
</para>
-<programlisting role="XML"><![CDATA[<framework:entity-query name="people" ejbql="select p from Person p"
+<programlisting language="XML" role="XML"><![CDATA[<framework:entity-query name="people" ejbql="select p from Person p"
order="lastName" max-results="20"/>]]>
</programlisting>
<para>
Use a page parameter to determine which page to display:
</para>
-<programlisting role="XML"><![CDATA[<pages>
+<programlisting language="XML" role="XML"><![CDATA[<pages>
<page view-id="/searchPerson.jsp">
<param name="firstResult" value="#{people.firstResult}"/>
</page>
@@ -353,7 +353,7 @@
The JSF code for pagination control is slightly verbose, but manageable:
</para>
-<programlisting role="XHTML"><![CDATA[<h1>Search for people</h1>
+<programlisting language="XML" role="XML"><![CDATA[<h1>Search for people</h1>
<h:dataTable value="#{people.resultList}" var="person">
<h:column>
@@ -390,7 +390,7 @@
Real search screens let the user enter optional search criteria to narrow the list of returned results. The Query object lets you specify optional restrictions to support this usecase:
</para>
-<programlisting role="XML"><![CDATA[<component name="examplePerson" class="Person"/>
+<programlisting language="XML" role="XML"><![CDATA[<component name="examplePerson" class="Person"/>
<framework:entity-query name="people" ejbql="select p from Person p"
order="lastName" max-results="20">
<framework:restrictions>
@@ -410,7 +410,7 @@
Notice the use of an "example" object.
</para>
-<programlisting role="XHTML"><![CDATA[<h1>Search for people</h1>
+<programlisting language="XML" role="XML"><![CDATA[<h1>Search for people</h1>
<h:form>
<div>
@@ -440,7 +440,7 @@
To refresh the query when the underlying entities change, we observe the <literal>org.jboss.seam.afterTransactionSuccess</literal> event:
</para>
-<programlisting role="XML"><![CDATA[<event type="org.jboss.seam.afterTransactionSuccess">
+<programlisting language="XML" role="XML"><![CDATA[<event type="org.jboss.seam.afterTransactionSuccess">
<action execute="#{people.refresh}" />
</event>]]>
</programlisting>
@@ -448,7 +448,7 @@
Or, to refresh the query when the person entity is persisted, updated or removed through <literal>PersonHome</literal>:
</para>
-<programlisting role="XML"><![CDATA[<event type="org.jboss.seam.afterTransactionSuccess.Person">
+<programlisting language="XML" role="XML"><![CDATA[<event type="org.jboss.seam.afterTransactionSuccess.Person">
<action execute="#{people.refresh}" />
</event>]]>
</programlisting>
@@ -469,7 +469,7 @@
For example, <literal>RegisterAction</literal> (from the Seam registration example) looks like this:
</para>
-<programlisting role="JAVA"><![CDATA[@Stateless
+<programlisting language="Java" role="JAVA">@Stateless
@Name("register")
public class RegisterAction extends EntityController implements Register {
@In private User user;
@@ -487,7 +487,7 @@
return null;
}
}
-}]]>
+}
</programlisting>
</section>
More information about the jboss-cvs-commits
mailing list