[seam-commits] Seam SVN: r11670 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US.

Author: laubai Date: 2009-11-24 02:37:05 -0500 (Tue, 24 Nov 2009) New Revision: 11670 Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Testing.xml tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Text.xml tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Validation.xml tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Webservices.xml tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Xml.xml Log: Edited testing, text, tools, validation, webservices and xml chapters. Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Testing.xml =================================================================== --- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Testing.xml 2009-11-24 07:35:44 UTC (rev 11669) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Testing.xml 2009-11-24 07:37:05 UTC (rev 11670) @@ -3,7 +3,7 @@ <para> Most Seam applications will need at least two kinds of automated tests: <emphasis>unit tests</emphasis>, which test a particular Seam component - in isolation, and scripted <emphasis>integration tests</emphasis> which + in isolation, and <emphasis>scripted integration tests</emphasis> which exercise all Java layers of the application (that is, everything except the view pages). </para> @@ -15,7 +15,7 @@ <title>Unit testing Seam components</title> <para> All Seam components are POJOs. This is a great place to start if you - want easy unit testing. And since Seam emphasises the use of bijection + want easy unit testing. And since Seam emphasises the use of bijection for inter-component interactions and access to contextual objects, it's very easy to test a Seam component outside of its normal runtime environment. @@ -76,11 +76,11 @@ ]]></programlisting> <para> - You'll notice we aren't testing retrieving data from or persisting - data to the database; nor are we testing any functionality - provided by Seam. We are just testing the logic of our POJOs. Seam - components don't usually depend directly upon container infrastructure, - so most unit testing as as easy as that! + In this case, we aren't testing retrieving data from the database, or + pushing data to it; nor are we testing any functionality provided + by Seam. We are just testing the logic of our POJOs. Seam components + don't usually depend directly upon container infrastructure, + so most unit testing is a simple process. </para> <para> However, if you want to test the entire application, read on. @@ -93,18 +93,16 @@ <para> Integration testing is slightly more difficult. In this case, we can't eliminate - the container infrastructure; indeed, that is part of what is being tested! At - the same time, we don't want to be forced to deploy our application to an - application server to run the automated tests. We need to be able to reproduce - just enough of the container infrastructure inside our testing environment to be - able to exercise the whole application, without hurting performance too much. + the container infrastructure, as it is also being tested. At the same time, we don't + want to be forced to deploy our application to an application server to run the + automated tests. We need to be able to reproduce just enough of the container + infrastructure inside our testing environment to be able to exercise the whole + application, without hurting performance too much. </para> <para> - The approach taken by Seam is to let you write tests that exercise your - components while running inside a pruned down container environment (Seam, - together with the JBoss Embedded container; n.b. JBoss Embedded requires - JDK 1.5 and does not work with JDK 1.6). + Seam allows you to test your components while running inside a pruned down container environment. This environment, incorporating Seam and the JBoss Embedded Container, requires JDK 1.5, and does not work with + JDK 1.6. </para> <programlisting role="JAVA"><![CDATA[public class RegisterTest extends SeamTest @@ -143,7 +141,7 @@ Occasionally, we need to be able to replace the implementation of some Seam component that depends upon resources which are not available in the integration test environment. For example, suppose we have some - Seam component which is a facade to some payment processing system: + Seam component which is a facade to a payment processing system: </para> <programlisting role="JAVA"><![CDATA[@Name("paymentProcessor") @@ -176,20 +174,19 @@ </section> <section> - <title>Integration testing Seam application user interactions</title> + <title>Integration testing Seam application User Interactions</title> <para> - An even harder problem is emulating user interactions. A third problem is where - to put our assertions. Some test frameworks let us test the whole application - by reproducing user interactions with the web browser. These frameworks have - their place, but they are not appropriate for use at development time. + Emulating user interactions is a difficult, as is correctly placing our assertions. + Some test frameworks let us test the whole application by reproducing user + interactions with the web browser. These frameworks have their place, but are not + appropriate for use at development time. </para> <para> <literal>SeamTest</literal> lets you write <emphasis>scripted</emphasis> tests, in a simulated JSF environment. The role of a scripted test is to reproduce - the interaction between the view and the Seam components. In other words, you - get to pretend you are the JSF implementation! + the interaction between the view and the Seam components. </para> <para> @@ -283,7 +280,7 @@ }]]></programlisting> <para> - Notice that we've extended <literal>SeamTest</literal>, which provides a + We have extended <literal>SeamTest</literal>, which provides a Seam environment for our components, and written our test script as an anonymous class that extends <literal>SeamTest.FacesRequest</literal>, which provides an emulated JSF request lifecycle. (There is also a @@ -296,7 +293,7 @@ <para> You'll find plenty of integration tests for the Seam example applications which demonstrate more complex cases. There are instructions for running - these tests using Ant, or using the TestNG plugin for eclipse: + these tests using Ant, or using the TestNG plugin for Eclipse: </para> <mediaobject> @@ -436,17 +433,17 @@ dependencies from <literal>lib/</literal> (e.g. <literal>jboss-system.jar</literal>) on the classpath, these will cause Embedded JBoss to not boot. So, just add the - dependencies (e.g. Drools, jBPM)you need as you go. + dependencies (e.g. Drools, jBPM) you need as you go. </para> <para> You also need to include the <literal>bootstrap/</literal> - directory on the classpath; <literal>bootstrap/</literal> contains + directory on the classpath. <literal>Bootstrap/</literal> contains the configuration for Embedded JBoss. </para> <para> - And, of course you need to put your built project and tests onto + You also need to put your built project and tests onto the classpath. Don't forget to put all the correct configuration files for JPA and Seam onto the classpath as well.Seam asks Embedded JBoss to deploy any resource (jar or directory) @@ -458,7 +455,7 @@ <para> By default, a generated project will use the - <literal>java:/DefaultDS</literal> (a built in HSQL datasource in + <literal>java:/DefaultDS</literal> (a built-in HSQL datasource in Embedded JBoss) for testing. If you want to use another datasource place the <literal>foo-ds.xml</literal> into <literal>bootstrap/deploy</literal> directory. @@ -471,7 +468,7 @@ <para> Seam provides TestNG support out of the box, but you can also use - another test framework, such as JUnit, if you want. + another test framework, such as JUnit, if you prefer. </para> <para> @@ -532,7 +529,7 @@ <para> You need to provide a dataset for DBUnit. IMPORTANT NOTE: DBUnit supports two formats for dataset files, flat and XML. Seam's DBUnitSeamTest assumes the flat - format is used, so please ensure that your dataset is in this format also. + format is used, so please ensure that your dataset is in this format: </para> <programlisting role="XML"><![CDATA[<dataset> @@ -550,7 +547,7 @@ </dataset>]]></programlisting> <para> - and tell Seam about it by overriding <literal>prepareDBUnitOperations()</literal>: + Then override the <literal>prepareDBUnitOperations()</literal> to announce the changes to Seam: </para> <programlisting role="JAVA"><![CDATA[protected void prepareDBUnitOperations() { @@ -644,4 +641,4 @@ </section> -</chapter> \ No newline at end of file +</chapter> Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Text.xml =================================================================== --- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Text.xml 2009-11-24 07:35:44 UTC (rev 11669) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Text.xml 2009-11-24 07:37:05 UTC (rev 11670) @@ -43,7 +43,7 @@ This is the second paragraph.]]></programlisting> <para> - (Note that a simple newline is ignored, you need an additional blank line to wrap text into a new paragraph.) + A simple newline will be ignored, and you need an additional blank line to wrap text into a new paragraph. This is the HTML that results: </para> @@ -220,10 +220,6 @@ <tr><td>Last name:</td><td>King</td></tr> </table>]]></programlisting> - <para> - But you can do much more if you want! - </para> - </section> -</chapter> \ No newline at end of file +</chapter> Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Validation.xml =================================================================== --- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Validation.xml 2009-11-24 07:35:44 UTC (rev 11669) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Validation.xml 2009-11-24 07:37:05 UTC (rev 11670) @@ -105,7 +105,7 @@ <para> <emphasis>Note:</emphasis> specifying <literal>@NotNull</literal> on the model does <emphasis>not</emphasis> eliminate the requirement - for <literal>required="true"</literal> to appear on the control! + for <literal>required="true"</literal> to appear on the control. This is due to a limitation of the JSF validation architecture. </para> @@ -144,8 +144,7 @@ <para> This tag simply adds an <literal>&lt;s:validate&gt;</literal> - to every input in the form. For a large form, it can save a lot - of typing! + to every input in the form. </para> <para> @@ -248,7 +247,7 @@ <para> It's better style to define explicit ids for important controls on the page, especially if you want to do - automated testing for the UI, using some toolkit like + automated testing for the UI, using a toolkit like Selenium. If you don't provide explicit ids, JSF will generate them, but the generated values will change if you change anything on the page. @@ -277,10 +276,9 @@ </h:form>]]></programlisting> <para> - And what if you want to specify a different message to be - displayed when validation fails? You can use the Seam message - bundle (and all it's goodies like el expressions inside the message, - and per-view message bundles) with the Hibernate Validator: + You can use the Seam message bundle (and all it's goodies like el expressions inside the message, + and per-view message bundles) with the Hibernate Validator to specify a different + message to be displayed when validation fails: </para> <programlisting role="JAVA"><![CDATA[public class Location { @@ -300,4 +298,4 @@ location.zipCode.invalid = The zip code is not valid for #{location.name} </programlisting> -</chapter> \ No newline at end of file +</chapter> Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Webservices.xml =================================================================== --- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Webservices.xml 2009-11-24 07:35:44 UTC (rev 11669) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Webservices.xml 2009-11-24 07:37:05 UTC (rev 11670) @@ -45,9 +45,7 @@ <section> <title>Conversational Web Services</title> <para> - So how are conversations propagated between web service requests? Seam uses a SOAP header element present - in both the SOAP request and response messages to carry the conversation ID from the consumer to the service, - and back again. Here's an example of a web service request that contains a conversation ID: + Seam uses a SOAP header element present in both the SOAP request and response messages to carry the conversation ID from the consumer to the service, and back again. Below is an example of a web service request that contains a conversation ID: </para> <programlisting role="XML"><![CDATA[<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" @@ -72,7 +70,7 @@ <para> An important thing to note is that the <literal>conversationId</literal> header element must be qualified with a namespace of <literal>http://www.jboss.org/seam/webservice</literal>;, otherwise Seam will not be - able to read the conversation ID from the request. Here's an example of a response to the above request message: + able to read the conversation ID from the request. Below is an example of a response to the above request message: </para> <programlisting role="XML"><![CDATA[<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Xml.xml =================================================================== --- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Xml.xml 2009-11-24 07:35:44 UTC (rev 11669) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Xml.xml 2009-11-24 07:37:05 UTC (rev 11670) @@ -1,12 +1,13 @@ <chapter id="xml"> - <title>Configuring Seam components</title> + <title>Configuring Seam Components</title> <para> The philosophy of minimizing XML-based configuration is extremely strong in Seam. Nevertheless, there are various reasons why we might want to configure a Seam component using XML: to isolate deployment-specific information from the Java code, to enable the creation of re-usable frameworks, to configure Seam's built-in functionality, etc. + </para><para> Seam provides two basic approaches to configuring components: configuration via property settings in a properties file or in <literal>web.xml</literal>, and configuration via <literal>components.xml</literal>. </para> @@ -38,8 +39,8 @@ <title>Configuring components via <literal>components.xml</literal></title> <para> - The <literal>components.xml</literal> file is a bit more powerful than property settings. It lets - you: + The <literal>components.xml</literal> file is a bit more powerful than property settings. It allows + you to: </para> <itemizedlist> @@ -92,8 +93,11 @@ </para> <para> - For example, the following <literal>components.xml</literal> file installs jBPM: + For example, the following three examples install jBPM: </para> + <para> + Example One: + </para> <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -102,7 +106,7 @@ </components>]]></programlisting> <para> - This example does the same thing: + Example Two: </para> <programlisting role="XML"><![CDATA[<components> @@ -125,7 +129,7 @@ </components>]]></programlisting> <para> - As does this one: + Example Three: </para> <programlisting role="XML"><![CDATA[<components> @@ -203,7 +207,7 @@ </components>]]></programlisting> <para> - You can create an "alias" (a second name) for a Seam component like so: + You can create an alias for a Seam component like so: </para> <programlisting role="XML"><![CDATA[<components> @@ -213,7 +217,7 @@ </components>]]></programlisting> <para> - You can even create an "alias" for a commonly used expression: + You can even create an alias for a commonly used expression: </para> <programlisting role="XML"><![CDATA[<components> @@ -334,7 +338,7 @@ <para> Finally, you may wire together components using a value-binding expression. Note that this is quite - different to injection using <literal>@In</literal>, since it happens at component instantiation time + different to injection using <literal>@In</literal>, since it happens at component creation time instead of invocation time. It is therefore much more similar to the dependency injection facilities offered by traditional IoC containers like JSF or Spring. </para> @@ -396,9 +400,8 @@ <para> Now, this works great for the built-in Seam components, but what about user components? There are two options. - First, Seam supports mixing the two models, allowing the use of the generic <literal>&lt;component&gt;</literal> - declarations for user components, along with namespaced declarations for built-in components. But even better, - Seam allows you to quickly declare namespaces for your own components. + Firstly, Seam supports mixing the two models, allowing the use of the generic <literal>&lt;component&gt;</literal> + declarations for user components, along with namespaced declarations for built-in components. Secondly, Seam allows you to quickly declare namespaces for your own components. </para> <para>