[seam-issues] [JBoss JIRA] (JBSEAM-5008) Seam 2.3 documentation issues - required updates

Seam 2.3 documentation issues - required updates ------------------------------------------------ Key: JBSEAM-5008 URL: https://issues.jboss.org/browse/JBSEAM-5008 Project: Seam 2 Issue Type: Bug Components: Documentation Issues Affects Versions: 2.3.0.BETA2 Reporter: Marek Schmidt Assignee: Marek Novotny Fix For: 2.3.0.CR1 Introduction.xml: * " Seam 2 and its extensions was added a little re-factored into Java EE 6 as CDI technology. So this should be a current focus of majority users. But for previous Seam 2 users who doesn't want or can't use that, we bring some new features from the Java EE 6 set like JSF 2, JPA 2 and Bean Validation integrations into Seam 2." The wording could be improved a bit. Also there should be noted that EE6 support (JSF2, JPA2, bean validation) is Seam2.3 specific. Tutorial.xml: 1.1 * examples directory (the "examples-ee6" should be renamed to "examples" in SVN) * view, resources, src items should be removed * "The example applications run both on JBoss AS 7.1.1 with no additional configuration." ** remove "both" 1.1.1 * "Once you've set the location of JBoss AS and started the application server, you can build and deploy any example by typing mvn install in the example root directory. And deploys it by changing to *-ear or *-web directory in case of existence only *-web submodule. Type in that submodule mvn jboss-as:deploy" ** The text is not clear, as "mvn install" doesn't deploy the example, so "you can build and deploy any example by typing mvn install in the example root directory." is not true. 1.2.1.1. The entity bean: User.java * "The @NotNull and @Size annotations are part of the Hibernate Validator framework. Seam integrates Hibernate Validator and lets you use it for data validation (even if you are not using Hibernate for persistence). " ** These are now Bean Validation annotations (JSR 303) 1.2.1.2. The stateless session bean class: RegisterAction.java * "JSF action listener methods return a string-valued outcome that determines what page will be displayed next. A null outcome (or a void action listener method) redisplays the previous page. In plain JSF, it is normal to always use a JSF navigation rule to determine the JSF view id from the outcome. For complex application this indirection is useful and a good practice. However, for very simple examples like this one, Seam lets you use the JSF view id as the outcome, eliminating the requirement for a navigation rule. Note that when you use a view id as an outcome, Seam always performs a browser redirect." ** The text should be updated wrt JSF2, as it also doesn't need navigation rules. * <f:view> in JSF2 examples (...the examples should be fixed too), should be updated to also use h:head, h:body as a best practise * This JSF component tells JSF to validate all the contained input fields against the Hibernate Validator annotations specified on the entity bean. ** should be "Bean Validation" 1.2.1.5. The Seam component deployment descriptor: components.xml * The example should use "${jndiPattern}" instead of "@jndiPattern@" by default, as it is already discouraging the "funny @" symbols in the "Eclipse M2e Web" note. 1.2.1.7. The JSF configuration: faces-config.xml * The file is not actually required at all, since we don't need to configure FaceletViewHandler in JSF2 1.2.1.10. The EAR deployment descriptor: application.xml * "registration application has got this set up registration-ear/pom.xml." something missing after "set up" (e.g. ", see ", or "in", ...) * "Just for imagination", czechism, I am afraid... 1.2.2. How it works * The form input values are now validated against the Hibernate Validator constraints specified on the User entity ** Bean Validation 1.3. Clickable lists in Seam: the messages example * Example 1.11. MessageManagerBean.java is not syntax highlighted 1.4. Seam and jBPM: the todo list example * Example 1.14. todo.jpdl.xml is not syntax highlighted * Example 1.17. TodoList.java is not syntax highlighted * "If we view this process definition using the process definition editor provided by JBossIDE, this is what it looks like: " ** The process definition editor is not available in JBDS 5. * Example 1.18. todo.xhtml should be updated to a facelet (contains JSP taglib tags in the headers, should be changed to XML) 1.5. Seam pageflow: the numberguess example * Example 1.20. pageflow.jpdl.xml is not syntax highlighted * "Here is what the pageflow looks like in the JBoss Developer Studio pageflow editor:" , the pageflow editor is not available in JBDS 5 AFAIK * Example 1.22. win.xhtml is not syntax highlighted * Example 1.23. NumberGuess.java is not syntax highlighted * Example 1.25. HotelSearchingAction.java is not syntax highlighted * Example 1.26. main.xhtml is not syntax highlighted * "Even better, the reRender attribute lets us render a fragment of the JSF page and perform a partial page update when the asynchronous response is received." ** the attribute is "render" now in RF4 * "Also notice that we use a method binding with a parameter: #{hotelBooking.selectHotel(hot)}. This is not possible in the standard Unified EL" ** I belive that is now also possible in the standard since EL 2.1 * Example 1.27. HotelBookingAction.java is not syntax highlighted * Example 1.28. RoomPreferenceAction.java is not syntax highlighted * Example 1.29. rooms.xhtml is not syntax highlighed * Example 1.29. rooms.xhtml the commented line numbers are several lines off the line they are commenting on and there is no "(3)" line * Example 1.30. HotelBookingAction.java is not syntax highlighted 1.9.1. Using "pull"-style MVC * Example 1.32. (BlogService) is not syntax highlighted Chapter 2. Getting started with Seam, using seam-gen * "In JBoss this may be accomplished by touching the top level deployment descriptor: application.xml for an EAR deployment, or web.xml for a WAR deployment.)" ** the behavior has changed in AS7, depending on deplyment mode, in automatic mode any file change will cause redeployment, none will in manual, see $JBOSS_HOME/standalone/deployments/README.txt Chapter 4. Concepts * "Concurrent requests to session-scoped stateful session beans are always serialized by Seam as long as the Seam interceptors are not disabled for the bean." ** That is not true anymore, since EJB3.1 changes, Seam 2.3 doesn't serialize access to SFSB anymore, it lets the ejb SFSB synchronization handle it itself. There should be a not that this has changed since previous versions. 4.2.7. Component names * the list of imports (component.xml) is not syntax highlighted. (the block after "The components.xml file included in the Seam JAR defines the following namespaces. ") Chapter 6. events * Some examples mention "hello.jsp", "calculator.jsp" view-ids, while there is nothing wrong with that, it should probably be changed to .xhtml Chapter 9. persistence * "Seam provides extensive support for the two most popular persistence architectures for Java: Hibernate, and the Java Persistence API introduced with EJB 3.1." ** Not precise, JPA was introduced with EJB 3.0. Perhaps ".. architectures for Java: Hibernate, and the Java Persistence API 2.0." was meant? * Mentions "Java EE 5" environment multiple times in the chapter, not clear if "EE 6" also applies. (mostly it refers to EJB >=3.0 / JPA) Should be probably changed just to "Java EE" Chapter 10. validation * JSF with bean validation is a standard now AFAIK and BV is also used with Seam now, so any mention of "Hibernate Validator" should be updated. * The two RichFaces example blocks after "Finally, we can use RichFaces Ajax to display validation messages as the user is navigating around the form" needs to be updated to RF4. Chapter 11. Groovy * "TODO: write a quick overview of the Groovy syntax add-on" should be probably removed as noone will write it anyway * "You will find a live example of the Booking demo written completely in Groovy and supporting incremental hot deployment in examples/groovybooking." the groovybooking example in Seam2.3 doesn't seem to support incremental hot deployment (as it uses WEB-INF/classes, not WEB-INF/dev and there are no special maven profiles) Chapter 12. wicket * "We are working to improve this." I doubt that... Chapter 13. framework * view-ids should probably be changed from .jsp to .xhtml Chapter 15. Security * 15.4.2.3.1. Minimal schema example, Role class not syntax highlighted * 15.4.2.3.2. Complex Schema Example, Role class not syntax highlighted Chapter 16. i18n * "In addition, Seam provides the <s:convertDateTime> tag which always performs conversions in the Seam timezone." ** s:convertDateTime is not available in Seam2.3 (yet?) Chapter 21. mail 21.2. Receiving emails * Section should be updated wrt AS7. I don't think there is any mail-ra in AS7, though, so should seam2.3 distribute one after all? (I haven't tested if that one works yet, though...) 22.2.1. Asynchronous methods * There should be a note that the Seam @Asynchronous is a different thing from the new EJB3.1 @Asynchronous Chapter 29. search 29.2. Configuration * The directory_provider now takes a provider name instead of the class name, e.g: <property name="hibernate.search.default.directory_provider" value="filesystem"/> * The rendered "Maven coordinates for using from Hibernate Search:" looks broken in the docbook html output. Chapter 30 configuration * add a note that setting a STATE_SAVING_METHOD to "client" can lead to security issues and com.sun.faces.ClientStateSavingPassword env-entry should be set in such cases 30.1.4. Integrating Seam with your EJB container * "For JBoss AS, the following pattern is correct" the section should be updated for AS7 and the problem with a different pattern for individual ejb jars should be noted. (there are multiple references to the old pattern in this chapter) * "(when using the JBoss Embeddable EJB3 container)" remove mention of JBoss Embeddable EJB3 container 30.3. Configuring Seam in Java EE 5 * make it EE 5 or EE 6. (or just EE 6) * Remove the jsf-facelets.jar from the example app tree 30.9. Deploying custom resources * all examples in the section not syntax highlighted Chapter 31 annotations * "The annotations for data validation are defined by the Hibernate Validator package." the Bean Validation standard. Chapter 34 JBoss EL 34.1. Parameterized Expressions * It should be explained how it relates to the new standard EL which also allows methods with parameters. Chapter 35 ClusteringAndEJBPassivation * Needs to be updated, see JBSEAM-5004 Chapter 36 performance * example not syntax highlighted Chapter 37 testing * The "Testing Seam with Arquillian" section should be merged with the "Integration testing Seam components", as since the latter is unusable by itself since the JBoss Embedded parts were removed.