From seam-commits at lists.jboss.org Thu Oct 14 07:20:03 2010
Content-Type: multipart/mixed; boundary="===============7541218212148260329=="
MIME-Version: 1.0
From: seam-commits at lists.jboss.org
To: seam-commits at lists.jboss.org
Subject: [seam-commits] Seam SVN: r13857 -
 modules/xml/trunk/docs/src/main/docbook/en-US.
Date: Thu, 14 Oct 2010 07:20:03 -0400
Message-ID: <201010141120.o9EBK3j6015800@svn01.web.mwc.hst.phx2.redhat.com>

--===============7541218212148260329==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: swd847
Date: 2010-10-14 07:20:03 -0400 (Thu, 14 Oct 2010)
New Revision: 13857

Modified:
   modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml
Log:
minor doc changes


Modified: modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml	2010-10-1=
4 11:19:10 UTC (rev 13856)
+++ modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml	2010-10-1=
4 11:20:03 UTC (rev 13857)
@@ -68,8 +68,8 @@
         </para> =

         =

         <para>
-           For example, say you had a class <literal>com.mydomain.package2=
.Report</literal>. =

-           To configure a <literal>Report</literal> bean you would use =

+           For example, say you had a class <code>com.mydomain.package2.Re=
port</code>. =

+           To configure a <code>Report</code> bean you would use =

            <literal>&lt;ns:Report&gt;</literal>. Methods and fields on the=
 bean are resolved
            from the same namespace as the bean itself. It is possible to d=
istinguish between =

            overloaded methods by specifying the parameter types, for more =
information see
@@ -83,7 +83,7 @@
       <title>Adding, replacing and modifying beans</title>
       =

       <para>
-         By configuring a bean via XML creates a new bean, however there =

+         By default configuring a bean via XML creates a new bean, however=
 there =

          may be cases where you want to modify an existing bean rather than
          adding a new one. The <literal>&lt;s:replaces&gt;</literal> and =

          <literal>&lt;s:modifies&gt;</literal> tags allow you to do this.
@@ -93,20 +93,21 @@
          The <literal>&lt;s:replaces&gt;</literal> tag prevents the existi=
ng bean from being =

          installed, and registers a new one with the given configuration. =
The =

          <literal>&lt;s:modifies&gt;</literal> tag does the same, except t=
hat it merges
-         the annotations on the bean with the annotations defined in XML. =
This has almost
-         the same effect as modifiying an existing bean, except it is poss=
ible to install =

-         multiple beans that modify the same class.
+         the annotations on the bean with the annotations defined in XML. =
Where the
+         same annotation is specified on both the class and in XML the ann=
otation in
+         XML takes precidence. This has almost the same effect as modifiyi=
ng an existing =

+         bean, except it is possible to install multiple beans that modify=
 the same class.
       </para>
         =

-      <programlisting role=3D"XML"><![CDATA[<test:Report>
+      <programlisting role=3D"XML"><![CDATA[<my:Report>
 	<s:modifies>
-	<test:NewQualifier/>
-</test:Report>
+	<my:NewQualifier/>
+</my:Report>
 =

-<test:ReportDatasource>
+<my:ReportDatasource>
 	<s:replaces>
-	<test:NewQualifier/>
-</test:ReportDatasource>]]></programlisting>
+	<my:NewQualifier/>
+</my:ReportDatasource>]]></programlisting>
 =

       <para>
          The first entry above adds a new bean with an extra qualifier, in=
 addition =

@@ -126,7 +127,7 @@
       =

       <para>
          Annotations are resolved in the same way as normal classes. Conce=
ptually =

-         annotations are applied to the object their parent element in the=
 resolves
+         annotations are applied to the object their parent element resolv=
es
          to. It is possible to set the value of annotation members using t=
he xml
          attribute that corresponds to the member name. For example:     =

       </para>
@@ -138,13 +139,12 @@
 }]]></programlisting>
 =

       <programlisting role=3D"XML" ><![CDATA[<test:QualifiedBean1>
-        <test:OtherQualifier value1=3D"AA" value2=3D"1">A</test:OtherQuali=
fier>
-</test:QualifiedBean1>
+        <test:OtherQualifier value1=3D"AA" value2=3D"1">A</my:OtherQualifi=
er>
+</my:QualifiedBean1>
     =

 <test:QualifiedBean2>
         <test:OtherQualifier value1=3D"BB" value2=3D"2" value=3D"B" />
-</test:QualifiedBean2>
-]]></programlisting>
+</my:QualifiedBean2>]]></programlisting>
       =

       <para>
          The <code>value</code> member can be set using the inner text of =
the node, as seen =

@@ -213,43 +213,43 @@
             <literal>Collection</literal> field values. Some examples:
          </para>
          =

-         <programlisting role=3D"XML"><![CDATA[<test:ArrayFieldValue>
+         <programlisting role=3D"XML"><![CDATA[<my:ArrayFieldValue>
 =

-    <test:iarray>
+    <my:intArrayField>
         <s:value>1</s:value>
         <s:value>2</s:value>
-    </test:iarray>
+    </my:intArrayField>
     =

-    <test:carray>
+    <my:classArrayField>
         <s:value>java.lang.Integer</s:value>
         <s:value>java.lang.Long</s:value>
-    </test:carray>
+    </my:classArrayField>
     =

-    <test:sarray>
+    <my:stringArrayField>
         <s:value>hello</s:value>
         <s:value>world</s:value>
-    </test:sarray>
+    </my:stringArrayField>
     =

-</test:ArrayFieldValue>
+</my:ArrayFieldValue>
 =

-<test:MapFieldValue>
+<my:MapFieldValue>
 =

-    <test:map1>
+    <my:map1>
         <s:entry><s:key>1</s:key><s:value>hello</s:value></s:entry>
         <s:entry><s:key>2</s:key><s:value>world</s:value></s:entry>
-    </test:map1>
+    </my:map1>
     =

-    <test:map2>
+    <my:map2>
         <s:e><s:k>1</s:k><s:v>java.lang.Integer</s:v></s:e>
         <s:e><s:k>2</s:k><s:v>java.lang.Long</s:v></s:e>
-    </test:map2>
+    </my:map2>
     =

-</test:MapFieldValue>]]></programlisting>
+</my:MapFieldValue>]]></programlisting>
 =

          <para>
-            Type conversion is done automatically for all primitives and p=
rimitive wrappers, <literal>Date</literal>, =

-            <literal>Calendar</literal>,<literal>Enum</literal> and <liter=
al>Class</literal> fields. =

-            In this instance <literal>ArrayFieldValue.carray</literal> is =
actually an array of classes, not an array of Strings.
+            Type conversion is done automatically for all primitives and p=
rimitive wrappers, =

+            <literal>Date</literal>, <literal>Calendar</literal>,<literal>=
Enum</literal> and =

+            <literal>Class</literal> fields. =

          </para>
         =

          <para>
@@ -263,6 +263,13 @@
       <s:value>#{paramValue}</s:key>
    </m:parameters>
 </m:Report>]]></programlisting>
+
+         <para>
+            Internally field values are set by wrapping the <code>Injectio=
nTarget</code> =

+            for a bean. This means that the expressions are evaluated once=
, at bean =

+            creation time.
+         </para>
+
       </section>
     =

       <section>
@@ -273,7 +280,7 @@
             This allows for the configuration of complex types with nestle=
d classes. Inline beans can be declared inside both
             <literal>&lt;s:value&gt;</literal> and <literal>&lt;s:key&gt;<=
/literal> elements, and may be used in both collections =

             and simple field values. Inline beans must not have any qualif=
ier annotations declared on the bean, instead seam-xml assigns =

-            them an artificial qualifier. Inline beans may have any scope,=
 however the default <literal>Dependent</literal> scope is =

+            them an artificial qualifier. Inline beans may have any scope,=
 however the default <code>Dependent</code> scope is =

             recomended.
          </para>
          =

@@ -288,7 +295,7 @@
         <my:Horse>
            <my:name>
               <value>billy</value>
-           </test:name>
+           </my:name>
            <my:shoe>
               <Inject/>
            </my:shoe>
@@ -308,56 +315,56 @@
          It is also possible to configure methods in a similar way to conf=
iguring fields:
       </para>
       =

+      <programlisting role=3D"JAVA" ><![CDATA[class MethodBean {
+
+   public int doStuff() {
+      return 1;
+   }
+
+   public int doStuff(MethodValueBean bean) {
+      return bean.value + 1;
+   }
+   =

+   public void doStuff(MethodValueBean[][] beans) {
+      /*do stuff */
+   }
+
+}]]></programlisting>
+
       <programlisting role=3D"XML" ><![CDATA[<?xml version=3D"1.0" encodin=
g=3D"UTF-8"?>
 <beans xmlns=3D"http://java.sun.com/xml/ns/javaee"
        xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"
        xmlns:s=3D"urn:java:ee" =

-       xmlns:test=3D"urn:java:org.jboss.seam.xml.test.method">
-    <test:MethodBean>
+       xmlns:my=3D"urn:java:org.jboss.seam.xml.test.method">
+    <my:MethodBean>
     =

-        <test:doStuff>
+        <my:doStuff>
             <s:Produces/>
-        </test:doStuff>
+        </my:doStuff>
         =

-        <test:doStuff>
+        <my:doStuff>
             <s:Produces/>
-            <test:Qualifier1/>
+            <my:Qualifier1/>
             <s:parameters>
-                <test:MethodValueBean>
-                    <test:Qualifier2/>
-                </test:MethodValueBean>
+                <my:MethodValueBean>
+                    <my:Qualifier2/>
+                </my:MethodValueBean>
             </s:parameters>
-        </test:doStuff>
+        </my:doStuff>
         =

-        <test:doStuff>
+        <my:doStuff>
             <s:Produces/>
-            <test:Qualifier1/>
+            <my:Qualifier1/>
             <s:parameters>
                 <s:array dimensions=3D"2">
-                    <test:Qualifier2/>
-                    <test:MethodValueBean/>
+                    <my:Qualifier2/>
+                    <my:MethodValueBean/>
                 </s:array>
             </s:parameters>
-        </test:doStuff>
+        </my:doStuff>
         =

-    </test:MethodBean>
+    </my:MethodBean>
 </beans>]]></programlisting>
-
-<programlisting role=3D"JAVA" ><![CDATA[class MethodBean {
-
-   public int doStuff() {
-      return 1;
-   }
-
-   public int doStuff(MethodValueBean bean) {
-      return bean.value + 1;
-   }
-   =

-   public void doStuff(MethodValueBean[][] beans) {
-      /*do stuff */
-   }
-
-}]]></programlisting>
             =

       <para>
          In this instance <literal>MethodBean</literal> has three methods,=
 all of them rather =

@@ -409,11 +416,11 @@
          the following:
       </para>
 =

-      <programlisting role=3D"XML"><![CDATA[<test:method>
+      <programlisting role=3D"XML"><![CDATA[<my:method>
     <s:array>
-      <test:MethodValueBean/>
+      <my:MethodValueBean/>
     </s:array>
-</test:method>]]>
+</my:method>]]>
       </programlisting>
         =

       <note>
@@ -436,15 +443,15 @@
          <code>@Inject</code> annotation applied to it. Annotations can be=
 applied to the constructor =

          parameters in the same manner as method parameters.
       </para>
-      <programlisting role=3D"XML"><![CDATA[<test:MyBean>
+      <programlisting role=3D"XML"><![CDATA[<my:MyBean>
    <s:parameters>
          <s:Integer>
-            <test:MyQualifier/>
+            <my:MyQualifier/>
          </s:Integer>
    </s:parameters>      =

-</test:MyBean>]]></programlisting>
+</my:MyBean>]]></programlisting>
       <para>
-         The example above is equivilent to the following java:
+         The example above is equivalent to the following java:
       </para>      =

       <programlisting role=3D"JAVA">class MyBean {
    @Inject   =

@@ -459,23 +466,25 @@
       <title>Overriding the type of an injection point</title>
         =

       <para>
-         It is possible to limit which bean types are availible to inject =
int a given injection point:
+         It is possible to limit which bean types are availible to inject =

+         into a given injection point:
       </para>
       <programlisting role=3D"JAVA"><![CDATA[class SomeBean
 {
 	public Object someField;
 }]]></programlisting>
 =

-<programlisting role=3D"XML"><![CDATA[<test:SomeBean>
-        <test:someField>
+<programlisting role=3D"XML"><![CDATA[<my:SomeBean>
+        <my:someField>
          	<s:Inject/>
          	<s:Exact>com.mydomain.InjectedBean</s:Exact>
-        </test:someField>
-</test:SomeBean>]]></programlisting>
+        </my:someField>
+</my:SomeBean>]]></programlisting>
 =

       <para>
          In the example above only beans that are assignable to InjectedBe=
an will be eligable for injection into the field.
-   	   This also works for parameter injection points.
+   	   This also works for parameter injection points. This functionallity=
 is part of Weld Extensions, and the
+         <code>@Exact</code> annotation can be used directly in java. =

       </para>
         =

    </section>    =

@@ -492,26 +501,26 @@
     	   binding and is named:
       </para>
       =

-      <programlisting role=3D"XML" ><![CDATA[<test:SomeStereotype>
-        <s:Stereotype/>
-        <test:InterceptorBinding/>
-        <s:Named/>
-   </test:SomeStereotype>]]></programlisting>   =

+      <programlisting role=3D"XML" ><![CDATA[<my:SomeStereotype>
+  <s:Stereotype/>
+  <my:InterceptorBinding/>
+  <s:Named/>
+</my:SomeStereotype>]]></programlisting>   =

    =

       <para>
          This configures a qualifier annotation:
       </para>
       =

-<programlisting role=3D"XML" ><![CDATA[<test:SomeQualifier>
-        <s:Qualifier/>
-   </test:SomeQualifier>]]></programlisting>   =

+<programlisting role=3D"XML" ><![CDATA[<my:SomeQualifier>
+  <s:Qualifier/>
+</my:SomeQualifier>]]></programlisting>   =

  	=

       <para>
          This configures an interceptor binding:
       </para>
-      <programlisting role=3D"XML" ><![CDATA[<test:SomeInterceptorBinding>
-        <s:InterceptorBinding/>
-   </test:SomeInterceptorBinding>]]></programlisting>  =

+      <programlisting role=3D"XML" ><![CDATA[<my:SomeInterceptorBinding>
+  <s:InterceptorBinding/>
+</my:SomeInterceptorBinding>]]></programlisting>  =

    =

    </section>
     =



--===============7541218212148260329==--