Errata for Seam in Action [ISBN: 1933988401]

The end of the first paragraph after the callout should read as follows:

When the course editor page is being used to modify an existing course, you can provide the user with a button to cancel changes and return to the course detail page using the following component tag:

<s:button view="/Course.xhtml" value="Cancel"/>

Assuming the course with an ID of 1 is being edited, the page parameters configured for the /Course.xhtml view ID are applied to the target URL as follows:

/Course.seam?courseId=1

seam-gen creates an s:button in this case, though an s:link would work exactly the same (it would just appear differently). In Seam 2.0, when seam-gen generates this button, it uses the name Done rather than Cancel. Technically, it should be Cancel because Done makes absolutely no sense in this context. This has been corrected in Seam 2.1.

Two sets of boxes in figure 6.3 were transposed. Fix the diagram as follows:

1. Reverse Retrieve value from specified scope and Perform hierarchical search for context variable + note
2. Reverse yes and no outcomes for the first Scope specified? decision

I lobbied to allow an entity component to be scoped to the stateless context for the purpose of building prototypes, but I ultimately lost the battle. Therefore, my recommendation to scope the roundPrototype component to the stateless context is invalid. The next best alternative is to scope the prototype to the event context, which works perfectly well for the use case in this section. (Recall that the conversation scope is the default scope for entity components).

<component name="roundPrototype" class="org.open18.model.Round"
  scope="event">
  <property name="golfer">#{currentGolfer}</property>
  <property name="date">#{currentDate}</property>
</component>

To read the debate over this functionality, see JBSEAM-3262.

In order to use the built-in messages component a property of a filter configured in the Seam descriptor, it is necessary to make that filter a startup component. The reason is that the Seam container is not active when many of the filters, including the AuthenticationFilter, are executed. However, the Seam container and all of the Seam contexts are active during startup.

<web:authentication-filter url-pattern="*.seam" auth-type="digest"
  key="g0!f15f#n" realm="#{messages['application.title']}"
  startup="true"/>

In the declaration for the securityRules component, the name of the XML element that maps to the class RuleBase and the XML attribute that maps to the ruleFiles property are both mistyped in the manuscript. The securityRules component should be declared as follows:

<security:rule-base name="securityRules" rule-files="/security.drl"/>

There is an error in the sentence that explains which parameters are passed to the s:hasPermission when it is called by the entity security listener.

incorrect:

The first argument to s:hasPermission is always the context variable name of the entity class, if it has been assigned one, or the fully qualified class name.

correct:

The first argument to s:hasPermission is always the component name of the entity class, if it has been assigned one, or the fully qualified class name.

To provide a custom CAPTCHA implementation, you must name the override component name org.jboss.seam.captcha.captcha, rather than captcha, as the book suggests. Seam looks for the qualified name explicitly when serving the CAPTCHA image.

@Name("org.jboss.seam.captcha.captcha")
public class CustomCaptcha extends Captcha { ... }

The reason you can refer to the component using the unqualified name, captcha, from elsewhere in the application is because Seam imports the org.jboss.seam.captcha context variable prefix. But to override a built-in component, you must name your component using the fully-qualified name.

Note that when overriding a built-in Seam component class, you must supply the @Name annotation since this annotation is not inherited.

The instructions for setting the conversation id on the Seam remoting context are incorrect. The setConversationId() is called on the context, retrieved from Seam.Remoting.getContext(), rather than on the Seam.Remoting object directly, as the book suggests.

Here's how you correctly bridge the Seam remoting context to the conversation of the current page:

Seam.Remoting.getContext().setConversationId(#{conversation.id});

The same mistake is made on the next page in the JavaScript function that starts the quiz. The corrected version of that function is shown here:

function startQuiz(ready, context) {
    Seam.Remoting.getContext()
        .setConversationId(context.getConversationId());
    askQuestion();
}

This section discusses how the multipartFilter built-in component controls the file upload settings, but references the XML element incorrectly in the code snippet. Additionally, the property on this component that controls the maximum multipart request size is maxRequestSize, not maxUploadSize as the book states. Here's what the configuration of the component should look like:

<web:multipart-filter max-request-size="5242880" create-temp-files="true"/>

And in case you were wondering, the maxRequestSize value is 5 MB in this example.

The Scorecard component class needs to have the method getCourseId() in order for the JPQL query with the embedded EL value expression to work.

public Long getCourseId() {
    return courseId;
}

Listing 13.8 should have <s:convertDateTime> not <s:convertDatetime> (3 instances). Notice that the T is uppercase in Time.

Where things get confusing is that the built-in Seam component for the current datetime is named currentDatetime (lowercase t in time).

Must use <h:commandLink> to select a locale from a link since the method-binding expression in the action references an iteration variable and the collection is not a JSF DataModel (Seam UI command components have built-in DataModel support). Additionally, the value of the select items was missing.

<ui:repeat var="_locale" value="#{localeSelector.supportedLocales}">
  #{' '}
  <h:commandLink value="#{_locale.label}"
    action="#{localeSelector.selectLanguage(_locale.value)}"/>
</ui:repeat>

Under the replacement token heading in section 5.5.3, the text claims you can set the value of the debug property on <core:init> dynamically using the EL. This example is misleading. The org.jboss.seam.core.init is the one component whose properties you cannot set using the EL. This technique is valid for any other component. However, you must consider what variables are available at the time when the component is instantiated when you are authoring the EL expression.

As an alternative, you could set the debug property dynamically in an observer or startup component.

If an injection (@In) is marked as optional (i.e., required = false) and the field to which the annotation is applied is a primitive, Seam will fail attempting to assign a null value to it. In this case, you must make the field a primitive wrapper type.

If a page is set to redirect after a transition (the redirect attribute on <page> is true or a nested <redirect/> element is present), it's not possible to use the back button to return to that page even when back is enabled for a page further in the flow. The reason is because Seam stores information about the pageflow in the page scope and the back button must result in a POST for that information to be restored. The redirect severs this linkage.

Recall that enabling back on a page allows the user to back up to any page leading up to that page.

The fully-qualified class name for the Lucene Query class is incorrect in the code block that shows an example Hibernate Search query. The method must also declare the Lucene ParseException to be thrown. Here is the updated listing with the change highlighted.

@Name("courseSearch")
public class CourseSearchAction {
    @In private FullTextEntityManager entityManager;
    @Out private List<Course> searchResults;
    public void search(String searchString) throws ParseException {
         org.apache.lucene.search.Query luceneQuery =
             new MultiFieldQueryParser(new String[] {"name", "description"},
             new StandardAnalyzer()).parse(searchString);
         javax.persistence.Query query = entityManager
             .createFullTextQuery(luceneQuery, Course.class);
         searchResults = (List<Course>) query.getResultList();
   }
}

The nodes within the <navigation> elements in RoundEdit.page.xml that match the CRUD operations should be wrapped in a <rule> node to ensure that the navigations are not used when the outcome of the action method is null.

<navigation from-action="#{roundHome.persist}">
  <rule>
    <end-conversation/>
    <redirect view-id="/Round.xhtml"/>
  </rule>
</navigation>
...

A header facet must be defined for the checkbox column. Otherwise, the headers of all the subsequent columns will shift over to the left by one and therefore be misaligned with the content in the table cells.

<h:column>
  <f:facet name="header">&#160;</f:facet>
  <h:selectBooleanCheckbox value="#{_round.selected}"/>
</h:column>

The query named coursesQuery incorrectly references the state property on the Course entity class rather than the Facility entity class. Therefore, the query for Course entities should join to Facility to allow the results to be sorted by state.

<framework:entity-query name="coursesQuery"
  ejbql="select c from Course c join fetch c.facility f"
  order="f.state asc, c.name asc">

The state should be retrieved via the facility property on Course when building the label of each select item for the UISelectOne component.

<s:selectItems var="_course" value="#{courses}"
  label="#{_course.facility.state} - #{_course.name}"/>

In the expression within the @Restrict annotation, the closing bracket for the s:hasPermission function, which should immediately follow facilityHome.instance, is missing in the manuscript. It should appear as follows:

@Restrict(
  "#{s:hasPermission('facilityHome', 'update', facilityHome.instance)}")
public String update() {
    return super.update();
}

The expression is correct in figure 11.4.

The Golfer entity class needs to be imported for saving a favorite since it is not present in the method signatures of the FavoritesAction component class:

<s:remote include="favoritesAction,org.open18.model.Golfer"/>

The category parameter is missing from the call to the selectQuiz method:

Seam.Component.getInstance("trivia").selectQuiz(category, startQuiz);

When a color name is used that is not in the standard color palette for the PDF template tags, Seam throws an exception. I had to do some tricks with colors (namely a color filter method) to get most scorecards to display with these invalid colors.

The valid color names, which come from the java.awt.Color class, are as follows:

• white
• gray
• lightgray
• darkgray
• black
• red
• pink
• yellow
• green
• magenta
• cyan
• blue
• orange

For a more flexible workaround that avoids the risk of errors, use hex values instead of color names. All hex values are accepted.

The built-in component named documentStore is not an auto-create component. Therefore, the create flag must be true when it is injected, in this case into the ReportGenerator component class.

@In(create = true) private DocumentStore documentStore

The value-binding expression #{timeZone.availableIDs} should be #{timeZone.getAvailableIDs()}. The JBoss EL syntax is necessary since the getAvailableIDs() method is static and hence not a true JavaBean property accessor.

I anticipated that the release date of Seam 2.0.3.GA would come before the book's print date. Unfortunately, I was wrong. The release got held back. For a couple weeks following the release of the book (Sept 5, 2008), you aren't going to find version 2.0.3.GA of Seam on the Seam download page or the JBoss Maven 2 repository, as the book suggests. Until Seam 2.0.3.GA is released, you should use Seam 2.0.3.CR1 or better.

Monitor seamframework.org for the latest news about releases.

During a postback, a short-circuit may happen as the result of a validation or conversation error, an event designated as "immediate," or a call to the renderResponse() method on the FacesContext.

should read

During a postback, a short-circuit may happen as the result of a validation or conversion error, an event designated as "immediate", or a call to the renderResponse() method on the FacesContext.

The definition of the system exception is backwards.

If the @Remove method is invoked directly, it leads to an immediate removal of the session bean reference, unless a runtime or remote exception is thrown and the exception class is marked with @ApplicationException (it’s not a system exception) or an exception is thrown that isn’t a runtime or remote exception and the retainIfException attribute on the @Remove annotation is set to true.

should read

If the @Remove method is invoked directly, it leads to an immediate removal of the session bean reference, unless a runtime or remote exception is thrown and the exception class is marked with @ApplicationException (it is a system exception) or an exception is thrown that isn't a runtime or remote exception and the retainIfException attribute on the @Remove annotation is set to true.

Let's put it in other terms. If the @Remove method throws a RuntimeException that is annotated with @ApplicationException, then the reference is not removed. If the @Remove method throws a checked exception, the reference is removed unless the @Remove annotation has the retainIfException attribute set to true (i.e., @Remove(retainIfException = true)). So when an exception is thrown, removal is dictated by the exception class when it's a runtime case and the remove method when it's a checked case.

The ProfileAction component class should be Serializable since it is scoped to the conversation (a cardinal rule of Seam). This component should also remain scoped to the conversation for the remainder of the chapter, though it's not shown this way.

@Name("profileAction")
@Scope(ScopeType.CONVERSATION)
public class ProfileAction implements Serializable { ... }

There are missing brackets around the cast to RegisterAction in the first code snippet of section 6.4.3.

((RegisterAction) Component.getInstance("registerAction", ScopeType.EVENT))
    .isUsernameAvailable(newGolfer.getUsername())

The class keyword was missing from the following class definition:

@Stateful
@Name("courseAction")
public class CourseActionBean implements CourseAction {
    @PersistenceContext private EntityManager em;
    @Out private Course course;
    @Begin public void editCourse(Long id) {
        course = em.find(Course.class, id);
    }
    ...
}

In the lazy-loading case in section 9.4.1, I am referring specifically to the serializable transaction isolation case. Even without this level of transaction isolation, it's still prudent to use formal transaction boundaries when performing database access.

action="#{roundHome.delete}"

should be:

action="#{roundHome.remove}"

The textarea field for the text property for the course comment should be marked as required.

<h:inputTextarea id="text" value="#{courseComment.text}" required="true"/>

The style classes for the sort links need additional properties to layout correctly, shown here in bold.

th a.asc {
    background-image: url(../img/sort_asc.gif);
    background-repeat: no-repeat;
    background-position: right;
    padding-right: 15px;
}

th a.desc {
    background-image: url(../img/sort_desc.gif);
    background-repeat: no-repeat;
    background-position: right;
    padding-right: 15px;
}

The RoundCriteria component class should be Serializable since it is scoped to the conversation (a cardinal rule of Seam).

@Name("roundCriteria")
@Scope(ScopeType.CONVERSATION)
public class RoundCriteria implements Serializable { ... }

In order to add the @Role annotation to the Golfer entity class, you must also also add the @Name annotation.

@Name("golfer")
@Role("currentGolfer", scope = ScopeType.SESSION)
...
public class Golfer implements Serializable { ... }

The @ManyToMany annotation is required on the getRoles() method in order to setup the association between Role entities properly.

@UserRoles @ManyToMany
public Set<Role> getRoles() { return this.roles; }

A @JoinTable annotation is necessary if you don't want the default table and column names to be used.

@UserRoles @ManyToMany
@JoinTable(name = "member_roles",
    joinColumns = @JoinColumn(name = "member_id"),
    inverseJoinColumns = @JoinColumn(name = "role_id"))
public Set<Role> getRoles() { return this.roles; }

The getName() method returns both void and String, but it should just be String.

@RoleName
public String getName() { return this.name; }

The import org.open18.model.Round is required in the security.drl file for the ModifyOwnRound rule.

import org.open18.model.Round;

The <h:inputText> is assumed to have nested <a:support> and be surrounded by an <s:decorate> tag that is rerendered in the case that the username is taken:

<s:decorate id="usernameField" template="layout/edit.xhtml">
  <ui:define name="label">Username</ui:define>
  <h:inputText id="username" value="#{newGolfer.username}"
    required="true" size="20"
    valueChangeListener="#{registerAction.verifyUsernameAvailable}">
    <a:support id="usernameCheck" event="onblur"
      reRender="usernameField" ajaxSingle="true" bypassUpdates="true"/>
  </h:inputText>    
</s:decorate>

The class keyword was missing from the following class definition:

@Name("trivia")
@Scope(ScopeType.CONVERSATION)
public class Trivia implements Serializable { ... }

The interface keyword was missing from the following interface definition:

public interface TriviaAsync implements RemotingService {
    public void drawQuestion(AsyncCallback callback);
    public void answerQuestion(Long id, String response,
        AsyncCallback callback);
}

Don't need semi-colons at end of folded methods of the Scorecard component class.

The signature for the getMensAndUnisexTeeSets() used by the template is missing.

public List<TeeSet> getMensAndUnisexTeeSets() { ... }

The following page action is required in exportScorecard.page.xml to prepare the scorecard to render the PDF:

<page action="#{scorecard.load}"/>

The comma is missing after the report parameter in the call to the constructor of DocumentData in the ReportGenerator component class.

There are erroneous brackets at the end of the class name in the RegistrationMailer class defintion. It should be:

public class RegistrationMailer { ... }

The expression #{newGolfers} should be #{newGolfersList} to be consistent with the collection defined in chapter 6. #{newGolfers} is a JSF DataModel that is only available after outjection occurs on the ProfileAction component class, whereas #{newGolfersList} references a manager component that is always available.

The book states that <s:decorate> extends <ui:composition> from Facelets, but technically it extends <ui:decorate>, which is a non-clipping variation of <ui:composition>. In addition, <s:decorate> is a naming container, making it fundamentally different from <ui:decorate>.

I regretfully overlooked thanking Megan Yockey, who managed various stages of this project including the contract negotiation, the proposal reviews, and setting up the accounts on Gregor. Megan is one of the acquisitions editors for Manning, so you can thank her for originating projects such as Seam in Action.

I also failed to credit Shane Bryzak for reviewing the security chapter (chapter 11) at the last hour, giving me some valuable corrections that came just in time.

Although I provide the JVM settings for improving memory management in the sidebar titled Sun JVM options when running JBoss AS, I never explain how these flags solve the PermGen space problem.

Regardless of how large you make the PermGen space, it will inevitably top out after enough deployments. With each deployment, new class objects get placed into the PermGen and thus occupy an ever increasing amount of space. What you need to do is take measures to flush the PermGen so that you can stabilize its size. There are two flags which handle this cleaning:

-XX:+CMSPermGenSweepingEnabled

This setting includes the PermGen in a garbage collection run. By default, the PermGen space is never included in garbage collection (and thus grows without bounds).

-XX:+CMSClassUnloadingEnabled

This setting tells the PermGen garbage collection sweep to take action on class objects. By default, class objects get an exemption, even when the PermGen space is being visited during a garabage collection.

There are hundreds of blog entries telling people to increase the PermGen size and an equal number of frustrated readers who still have a problem. You want to avoid the crutch of making the barrel bigger (PermGen space) and hoping that it never fills up.

In Seam 2.1, the following directory structure changes were made in seam-gen projects.

src/action => src/hot
src/model => src/main

Please see the details in JBSEAM-3529 and this blog entry.

There is only one catchall allowed per view-id. However, if method returns void or null, any <rule> containing an if attribute is still consulted. The if attribute provides a contextual alternative to returning a logical outcome from the action method.

The unconverted value of each page parameter is stored in page context under the name of page parameter. The converted value is stored in the event context under the name of the page parameter. These assignments are in addition to the converted value being bound to the model if an EL expression is provided.

In Seam 2.1, the sort property on the Query component was divided into orderDirection and orderColumn to better protect against SQL injection.

It should be noted in section 4.4.1 that in addition to synchronizing session-scoped components, Seam serializes access to each conversation. As a result, all conversation-scoped components are naturally synchronized and thread-safe.

SeamTest does work with JDK >= 6. Please see the FAQ entry DoesSeamWorkWithJDK60 on the Seam wiki. This document explains why it doesn't work out of the box, which versions of JDK 6 are compatible, and the JVM flag you need to use.

It's possible to inject one Seam session bean component into another using the @EJB annotation. However, by doing so you don't get Seam's state management and the client-side interceptors don't get applied, since those are the two concerns that the Seam half of a Seam session bean component provide. Server-side interceptors are still applied since they tie into the EJB interceptor chain.

The @In annotation and the @PersistenceContext annotation on a property of type EntityManager are distinctly different. The @In annotation signals Seam to inject a Seam-managed persistence context (i.e., EntityManager) whereas the @PersistenceContext annotation signals the Java EE container to inject a container-managed persistence context. The latter can only be used on Java EE components (EJB 3, JSF managed beans, etc) and does not have the management benefits that Seam offers for persistence. Seam does wrap the container-managed persistence manager to support EL in JPQL queries and wraps it with a Hibernate Search proxy, but Seam does not manage the scope of the persistence context in this case.

Please see chapters 8 and 9 for further explanation.

Technically, the <s:conversationName value="Course"/> isn't needed for command buttons on the /CourseEdit.xhtml page. It's only needed when you are coming from a page that's not already using the natural conversation and you want to join into it as you navigate to that page through a JSF navigation rule.

See the /auction.xhtml page from the seambay example in the examples directory of the Seam distribution for a working example.

In general, natural conversations are tricky. You often find yourself in a situation where the EL value expression you provide as the conversation ID is null, causing Seam to throw an exception. Don't get discouraged if you are having difficulty with natural conversations because the design is not yet perfect.

Here is the definition of the natural conversation that I now use for the /CourseEdit.xhtml page:

<conversation name="Course" parameter-name="courseId"
  parameter-value="#{redirect.parameters.courseId != null ?
    redirect.parameters.courseId : (courseHome.instance.id != null ?
    courseHome.instance.id : '')}"/>

I am taking into account the redirect parameters that are stored into the page-scoped redirect component when the user is interrupted and directed to the login page.

Hibernate Search uses event listeners to keep the index synchronized with the records in the database. If you are using Hibernate's JPA implementation with Hibernate Annotations 3.3.0.GA or greater, you don't need to worry about registering the index event listeners since this step happens automatically. However, JBoss AS 4.2.x uses Hibernate Annotations 3.2.1.GA. Therefore, you must do one of the following to use Hibernate Search.

1. Upgrade the Hibernate libraries in JBoss AS. Copy hibernate.jar (and rename to hibernate3.jar), hibernate-annotations.jar and hibernate-entitymanager.jar from the seam-gen project's lib directory to ${jboss.home}/server/default/lib.

2. Explicitly add the event listeners to your persistence unit configuration (i.e., /META-INF/persistence.xml) using vendor properties.

<property name="hibernate.ejb.event.post-insert"
  value="org.hibernate.search.event.FullTextIndexEventListener"/>
<property name="hibernate.ejb.event.post-update"
  value="org.hibernate.search.event.FullTextIndexEventListener"/>
<property name="hibernate.ejb.event.post-delete"
  value="org.hibernate.search.event.FullTextIndexEventListener"/>

In order to see the query comments added using the query hint property org.hibernate.comment, you must enable the property hibernate.use_sql_comments in /META-INF/persistence.xml:

<property name="hibernate.use_sql_comments" value="true"/>

By supplying a comment using the query hint, you override the default comment that Hibernate uses, which is the HQL query.

In order to use the https scheme in the page descriptor, you must first configure JBoss AS to accept HTTP connections over SSL. Please see this wiki page for instructions:

EnableSSLJBossAS

Add xmlns:a="http://richfaces.org/a4j" to root tag in a Facelets template to use the Ajax4jsf tags:

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
  xmlns:a="http://richfaces.org/a4j" ...>
  ...
  <a:outputPanel ajaxRendered="true" layout="none">
    ...
  </a:outputPanel>
  ...
</ui:composition>

I never formally introduce the component namespace http://jboss.com/products/seam/theme, prefixed as theme.

If the requested key is not defined in the theme map, the name of the key is returned.