[seam-commits] Seam SVN: r13853 - modules/xml/trunk/docs/src/main/docbook/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Thu Oct 14 06:01:23 EDT 2010
Author: swd847
Date: 2010-10-14 06:01:22 -0400 (Thu, 14 Oct 2010)
New Revision: 13853
Modified:
modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml
modules/xml/trunk/docs/src/main/docbook/en-US/xml-introduction.xml
Log:
more seam-xml documentation work
Modified: modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml
===================================================================
--- modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml 2010-10-14 10:00:04 UTC (rev 13852)
+++ modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml 2010-10-14 10:01:22 UTC (rev 13853)
@@ -4,140 +4,10 @@
<chapter id="xml">
<title>Seam XML Reference</title>
- <section>
- <title>OLD Getting Started - To be removed</title>
- <para>By default XML files are discovered from the classpath. The extension looks for an XML file in the following locations:</para>
- <itemizedlist>
- <listitem><literal>/WEB-INF/beans.xml</literal></listitem>
- <listitem><literal>/META-INF/beans.xml</literal></listitem>
- <listitem><literal>/WEB-INF/seam-beans.xml</literal></listitem>
- <listitem><literal>/META-INF/seam-beans.xml</literal></listitem>
- </itemizedlist>
-
- <para>The <literal>beans.xml</literal> file is the preferred way of configuring beans via XML, however it may be possible that some JSR-299 implementations will not allow this,
- so <literal>seam-beans.xml</literal> is provided as an alternative. </para>
-
- <para>Let's start with a simple example:</para>
- <programlisting role="XML">
- <![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<beans xmlns="http://java.sun.com/xml/ns/javaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:s="urn:java:ee"
- xmlns:test="urn:java:org.jboss.seam.xml.test.injection">
-
- <test:ProducerQualifier>
- <s:Qualifier/>
- </test:ProducerQualifier>
-
- <test:ProducerBean someOtherField="45" >
- <test:someField>
- <s:Produces/>
- <test:ProducerQualifier/>
- <s:value>hello world</s:value>
- </test:someField>
- </test:ProducerBean>
-
- <test:ReceiverBean>
- <test:value>
- <test:ProducerQualifier/>
- <s:Inject/>
- </test:value>
- </test:ReceiverBean>
-
-</beans>
- ]]>
- </programlisting>
-
- <para>You will notice that two new namspace declarations have been added to the
- <literal>beans.xml</literal> file: <literal>urn:java:ee</literal> and
- <literal>urn:java:org.jboss.seam.xml.test.injection</literal>. The
- <literal>urn:java:ee</literal> namespace is the main one used by the XML
- extension, we will cover exactly what lives in this namespace later. The
- <literal>urn:java:org.jboss.seam.xml.test.injection</literal> namespace is used
- to resolve classes in the java package <literal>org.jboss.seam.xml.test.injection</literal>,
- so in the example above <literal><test:ProducerBean></literal> resolves to
- <literal>org.jboss.seam.xml.test.injection.ProducerBean</literal>.</para>
-
- <para>It is possible to map an XML namespace to multiple java packages. This is
- done by sperating the packages with a colon like so:</para>
- <programlisting>
- <![CDATA[
- xmlns:test="urn:java:com.mydomain.package1:com.mydomain.package2"
- ]]>
- </programlisting>
- <para>The namespaces are searched in the order they are specified in the xml
- document.</para>
-
- <programlisting role="XML">
- <![CDATA[
-<test:ProducerQualifier>
- <s:Qualifier/>
-</test:ProducerQualifier>
- ]]>
- </programlisting>
-
- <para>The first entry in the file defines a new qualifier. <literal>ProducerQualifier</literal>
- is an annotation in the package <literal>org.jboss.seam.xml.test.injection</literal>.</para>
-
- <programlisting role="XML">
- <![CDATA[
-<test:ProducerBean someOtherField="45" >
- <test:someField>
- <s:Produces/>
- <test:ProducerQualifier/>
- <s:value>hello world</s:value>
- </test:someField>
-</test:ProducerBean>
- ]]>
- </programlisting>
-
- <para>The next entry in the file is a bean declaration. The bean class is
- <literal>org.jboss.seam.xml.test.injection.ProducerBean</literal>.
- It is important to note that this declaration does not change the existing declaration of
- <literal>ProducerBean</literal>, instead it installs a new bean. In
- this instance there will be two <literal>ProducerBean</literal> CDI beans.</para>
-
- <para>This bean has a field called <literal>someField</literal>, this field is configured to be a producer field using XML (it is also possible to configure producer
- methods, more on this later). The <literal><test:value/></literal> declaration has several child elements. The <literal><s:Produces/></literal>
- element tells the container that this is a producer field. <literal><test:ProducerQualifier/></literal> element defines a qualifier for the producer
- field. The <literal><s:value></literal> element defines an initial value for the field.</para>
-
- <para>This bean also has another field called <literal>someOtherField</literal> this field has it's value to to 45 using a shorthand syntax. A field may not be specified
- twice, trying to set the value using the shorthand syntax and the normal syntax will result in an error.</para>
-
- <para>Child elements of fields, methods and classes that resolve to Annotation types are considered to be annotations on the corresponding element,
- so the corresponding Java declaration for the XML above would be:</para>
-
- <programlisting role="JAVA"><![CDATA[
-public class ProducerBean {
- @Produces
- @ProducerQualifier
- public String someField = "hello world";
-
- int someOtherField = 45;
-
-}
- ]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[
-<test:ReceiverBean>
- <test:value>
- <test:ProducerQualifier/>
- <s:Inject/>
- </test:value>
-</test:ReceiverBean>
- ]]></programlisting>
-
- <para>The XML above declares a new bean that injects the value that was produced above.
- In this case the <literal>@Inject</literal> annotation is applied instead of
- <literal>@Produces</literal> and no initial value is set.</para>
- </section>
-
- <section>
+ <section id="xml.namespaces">
<title>XML Namespaces</title>
- <para>The main namesapce is <literal>urn:java:ee</literal> contains builtin tags and types from core packages.
- The builting tags are:</para>
+ <para>The main namespace is <literal>urn:java:ee</literal> contains builtin tags and types from core packages.
+ The builtin tags are:</para>
<itemizedlist>
<listitem><para><literal>Beans</literal></para></listitem>
@@ -174,23 +44,34 @@
<listitem><para><literal>javax.decorator</literal></para></listitem>
<listitem><para><literal>javax.interceptor</literal></para></listitem>
<listitem><para><literal>org.jboss.weld.extensions.core</literal></para></listitem>
+ <listitem><para><literal>org.jboss.weld.extensions.unwraps</literal></para></listitem>
+ <listitem><para><literal>org.jboss.weld.extensions.resourceLoader</literal></para></listitem>
</itemizedlist>
<para>Other namspaces are specified using the following syntax:</para>
<programlisting>
<![CDATA[xmlns:ns="urn:java:com.mydomain.package1:com.mydomain.package2"]]>
</programlisting>
- <para>This maps <literal>ns</literal> to the packages <literal>com.mydomain.package1</literal>
- and <literal>com.mydomain.package2</literal>. These packages are searched in order to
- resolve elements in this namespace.</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 <literal><ns:Report></literal>. Methods and fields of a bean come
- from the same namespace as the bean iteself.</para>
+ <para>
+ This maps <literal>ns</literal> to the packages <literal>com.mydomain.package1</literal>
+ and <literal>com.mydomain.package2</literal>. These packages are searched in order to
+ resolve elements in this namespace.
+ </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
+ <literal><ns:Report></literal>. Methods and fields on the bean are resolved
+ from the same namespace as the bean itself. It is possible to distinguish between
+ overloaded methods by specifying the parameter types, for more information see
+ <link linkend="xml.configuring-methods">Configuring Methods</link>.
+ </para>
+
+
</section>
- <section>
- <title>Overriding and extending beans</title>
+ <section id="xml.installing-beans">
+ <title>Adding, replacing and modifying beans</title>
<para>By 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><s:replaces></literal> and
@@ -198,8 +79,10 @@
<para>The <literal><s:replaces></literal> tag prevents the existing bean from being
installed, and registers a new one with the given configuration. The
<literal><s:modifies></literal> tag does the same, except that it merges
- the annotations on the bean with the annotations defined in XML. This has the
- same effect as modifiying an existing bean.</para>
+ 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 possible to install
+ multiple beans that modify the same class.
+ </para>
<programlisting role="XML"><![CDATA[
<test:Report>
@@ -217,12 +100,34 @@
<para>The second prevents the existing bean from being installed, and registers a new bean with a single qualifier.</para>
</section>
- <section>
- <title>Initial Field Values</title>
- <para>Inital field values can be set three different ways as shown below:</para>
- <programlisting role="XML">
- <![CDATA[
-<r:MyBean company="Red Hat Inc" />
+ <secion id="xml.configuring-fields" >
+ <title>Configuring Fields</title>
+ <para>
+ It is possible to both apply qualifiers to and set the initial value of a field.
+ Fields reside in the same namespace as the declaring bean, and the element name
+ must exactly match the field name. For example if we have the following class:
+ </para>
+
+ <programlisting role="JAVA">class RobotFactory {
+ Robot robot;
+ }
+ </programlisting>
+
+ <para>
+ The following xml will add the <code>@Produces</code> annotation to the
+ <code>robot</code> field:
+ </para>
+
+ <programlisting role="JAVA" ><![CDATA[<my:RobotFactory>
+ <my:robot>
+ <s:Produces/>
+ </my:robot>
+</my:RobotFactory/>]]></programlisting>
+
+ <section>
+ <title>Initial Field Values</title>
+ <para>Inital field values can be set three different ways as shown below:</para>
+ <programlisting role="XML"><![CDATA[<r:MyBean company="Red Hat Inc" />
<r:MyBean>
<r:company>Red Hat Inc</r:company>
@@ -234,14 +139,12 @@
<r:SomeQualifier/>
</r:company>
</r:MyBean>]]>
- </programlisting>
+ </programlisting>
- <para>The third form is the only one that also allows you to add annotations such as qualifiers to the field.</para>
+ <para>The third form is the only one that also allows you to add annotations such as qualifiers to the field.</para>
- <para>It is possible to set <literal>Map</literal>,<literal>Array</literal> and <literal>Collection</literal> field values. Some examples:</para>
- <programlisting role="XML">
- <![CDATA[
-<test:ArrayFieldValue>
+ <para>It is possible to set <literal>Map</literal>,<literal>Array</literal> and <literal>Collection</literal> field values. Some examples:</para>
+ <programlisting role="XML"><![CDATA[<test:ArrayFieldValue>
<test:iarray>
<s:value>1</s:value>
@@ -272,65 +175,68 @@
<s:e><s:k>2</s:k><s:v>java.lang.Long</s:v></s:e>
</test:map2>
-</test:MapFieldValue>
- ]]>
- </programlisting>
- <para>Type conversion is done automatically for all primitives and primitive wrappers, <literal>Date</literal>,
- <literal>Calendar</literal>,<literal>Enum</literal> and <literal>Class</literal> fields.
- In this instance <literal>ArrayFieldValue.carray</literal> is actually an array of classes, not an array of Strings.</para>
- <para>The use of EL to set field values is also supported:</para>
- <programlisting role="XML">
- <![CDATA[
-<m:Report>
+</test:MapFieldValue>]]></programlisting>
+
+ <para>
+ Type conversion is done automatically for all primitives and primitive wrappers, <literal>Date</literal>,
+ <literal>Calendar</literal>,<literal>Enum</literal> and <literal>Class</literal> fields.
+ In this instance <literal>ArrayFieldValue.carray</literal> is actually an array of classes, not an array of Strings.
+ </para>
+
+ <para>
+ The use of EL to set field values is also supported:
+ </para>
+
+ <programlisting role="XML"><![CDATA[<m:Report>
<m:name>#{reportName}</m:name>
<m:parameters>
<s:key>#{paramName}</s:key>
<s:value>#{paramValue}</s:key>
</m:parameters>
-</m:Report>
-]]>
-</programlisting>
- </section>
- <section>
- <title>Inline Bean Declarations</title>
- <para>Inline beans allow you to set field values to another bean that is declared inline inside the field declaration.
- This allows for the configuration of complex types with nestled classes. Inline beans can be declared inside both
- <literal><s:value></literal> and <literal><s:key></literal> elements, and may be used in both collections
- and simple field values. Inline beans must not have any qualifier 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
- recomended.
- </para>
-<programlisting role="XML">
-<![CDATA[
-<test:Knight>
- <test:sword>
+</m:Report>]]></programlisting>
+ </section>
+
+ <section>
+ <title>Inline Bean Declarations</title>
+
+ <para>
+ Inline beans allow you to set field values to another bean that is declared inline inside the field declaration.
+ This allows for the configuration of complex types with nestled classes. Inline beans can be declared inside both
+ <literal><s:value></literal> and <literal><s:key></literal> elements, and may be used in both collections
+ and simple field values. Inline beans must not have any qualifier 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
+ recomended.
+ </para>
+ <programlisting role="XML"><![CDATA[<my:Knight>
+ <my:sword>
<value>
- <test:Sword type="sharp"/>
+ <my:Sword type="sharp"/>
</value>
- </test:sword>
- <test:horse>
+ </my:sword>
+ <my:horse>
<value>
- <test:Horse>
- <test:name>
+ <my:Horse>
+ <my:name>
<value>billy</value>
</test:name>
- <test:shoe>
+ <my:shoe>
<Inject/>
- </test:shoe>
- </test:Horse>
+ </my:shoe>
+ </my:Horse>
</value>
- </test:horse>
-</test:Knight>
-]]>
-</programlisting>
- </section>
- <section>
- <title>Configuring methods</title>
+ </my:horse>
+</my:Knight>]]></programlisting>
+ </section>
+
+ </secion>
- <para>It is also possible to configure methods in a similar way to configuring fields:</para>
- <programlisting role="XML" >
- <![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
+ <section id="xml.configuring-methods" >
+ <title>Configuring methods</title>
+
+ <para>
+ It is also possible to configure methods in a similar way to configuring fields:
+ </para>
+ <programlisting role="XML" ><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:s="urn:java:ee"
@@ -363,13 +269,10 @@
</test:doStuff>
</test:MethodBean>
-</beans>
-]]>
-</programlisting>
-<programlisting role="JAVA" >
-<![CDATA[
-public class MethodBean {
+</beans>]]></programlisting>
+<programlisting role="JAVA" ><![CDATA[class MethodBean {
+
public int doStuff() {
return 1;
}
@@ -382,29 +285,35 @@
//do stuff
}
-}
-]]>
-</programlisting>
+}]]></programlisting>
- <para>In this instance <literal>MethodBean</literal> has three methods, all of them rather
- imaginatively named <literal>doStuff</literal>.</para>
- <para> The first <literal><test:doStuff></literal>
- entry in the XML file configures the method that takes no arguments. The
- <literal><s:Produces></literal> element makes it into a producer method.
- </para>
- <para>The next entry in the file configures the method that takes a
- <literal>MethodValueBean</literal> as a parameter and the final entry
- configures a method that takes a two dimensional array of<literal>MethodValueBean</literal>'s
- as a parameter. For both these methods a qualifier was added to the method parameter and
- they were made into producer methods.</para>
- <para>Method parameters are specified inside the <literal><s:parameters></literal>
- element. If these parameters have annotation children they are taken to be annotations on
- the parameter. </para>
+ <para>
+ In this instance <literal>MethodBean</literal> has three methods, all of them rather
+ imaginatively named <literal>doStuff</literal>.
+ </para>
+ <para>
+ The first <literal><test:doStuff></literal>
+ entry in the XML file configures the method that takes no arguments. The
+ <literal><s:Produces></literal> element makes it into a producer method.
+ </para>
+ <para>
+ The next entry in the file configures the method that takes a
+ <literal>MethodValueBean</literal> as a parameter and the final entry
+ configures a method that takes a two dimensional array of<literal>MethodValueBean</literal>'s
+ as a parameter. For both these methods a qualifier was added to the method parameter and
+ they were made into producer methods.
+ </para>
+ <para>
+ Method parameters are specified inside the <literal><s:parameters></literal>
+ element. If these parameters have annotation children they are taken to be annotations on
+ the parameter.
+ </para>
- <para>The corresponding Java declaration for the XML above would be:</para>
- <programlisting role="JAVA">
- <![CDATA[
-public class MethodBean {
+ <para>
+ The corresponding Java declaration for the XML above would be:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[class MethodBean {
@Produces
public int doStuff() {//method body}
@@ -416,22 +325,32 @@
@Produces
@Qualifier1
public int doStuff(@Qualifier2 MethodValueBean[][] param) {//method body}
-} ]]>
- </programlisting>
- <para>Array parameters can be represented using the <literal><s:array></literal> element,
- with a child element to represent the type of the array. E.g.</para>
- <programlisting role="JAVA">
-int method(MethodValueBean[] param);
- </programlisting>
- <para>could be configured via xml using the following:</para>
- <programlisting role="XML"><![CDATA[
-<test:method>
+}]]></programlisting>
+
+ <para>
+ Array parameters can be represented using the <literal><s:array></literal> element,
+ with a child element to represent the type of the array. E.g.
+ <code>int method(MethodValueBean[] param);</code> could be configured via xml using
+ the following:
+ </para>
+
+ <programlisting role="XML"><![CDATA[<test:method>
<s:array>
<test:MethodValueBean/>
</s:array>
</test:method>]]>
- </programlisting>
- </section>
+ </programlisting>
+
+ <note>
+ <para>
+ If a class has a field and a method of the same name then by default the
+ field will be resolved, unless the element has a child
+ <code><parameters></code> element, in which case it is resolved
+ as a method.
+ </para>
+ </note>
+ </section>
+
<section>
<title>Configuring the bean constructor</title>
<para>
@@ -458,49 +377,45 @@
...
}
} </programlisting>
- </section>
- <section>
- <title>Overriding the type of an injection point</title>
+ </section>
+
+ <section>
+ <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:</para>
- <programlisting role="JAVA">
- <![CDATA[
-public class SomeBean
+ <para>
+ It is possible to limit which bean types are availible to inject int a given injection point:
+ </para>
+ <programlisting role="JAVA"><![CDATA[class SomeBean
{
public Object someField;
-}
-]]>
-</programlisting>
-<programlisting role="XML">
-<![CDATA[
-<test:SomeBean>
+}]]></programlisting>
+
+<programlisting role="XML"><![CDATA[<test:SomeBean>
<test:someField>
<s:Inject/>
<s:Exact>com.mydomain.InjectedBean</s:Exact>
</test:someField>
-</test:SomeBean>
-]]>
-</programlisting>
-<para>In the example above only beans that are assignable to InjectedBean will be eligable for injection into the field.
- This also works for parameter injection points.</para>
+</test:SomeBean>]]></programlisting>
+
+ <para>
+ In the example above only beans that are assignable to InjectedBean will be eligable for injection into the field.
+ This also works for parameter injection points.
+ </para>
- </section>
+ </section>
- <section>
- <title>Annotation Members</title>
- <para>It is possible to set the value of annotation members using attributes in xml. For example:</para>
- <programlisting role="JAVA" >
- <![CDATA[
-public @interface OtherQualifier {
+ <section>
+ <title>Annotation Members</title>
+ <para>
+ It is possible to set the value of annotation members using attributes in xml. For example:
+ </para>
+ <programlisting role="JAVA" ><![CDATA[public @interface OtherQualifier {
String value1();
int value2();
QualifierEnum value();
-}
-]]>
-</programlisting>
-<programlisting role="XML" >
-<![CDATA[
-<test:QualifiedBean1>
+}]]></programlisting>
+
+ <programlisting role="XML" ><![CDATA[<test:QualifiedBean1>
<test:OtherQualifier value1="AA" value2="1">A</test:OtherQualifier>
</test:QualifiedBean1>
@@ -508,52 +423,58 @@
<test:OtherQualifier value1="BB" value2="2" value="B" />
</test:QualifiedBean2>
]]>
- </programlisting>
- <para>The value member can be set using the inner text of the node, as seen in the first example.</para>
+ </programlisting>
+
+ <para>
+ The value member can be set using the inner text of the node, as seen in the first example.
+ </para>
+
</section>
<section>
<title>Configuring Meta Annotations</title>
- <para>It is possible to make existing annotations into qualifiers, stereotypes or interceptor bindings.</para>
- <para>This configures a stereotype annotation <literal>SomeStereotype</literal> that has a single interceptor
- binding and is named:</para>
-<programlisting role="XML" >
-<![CDATA[
- <test:SomeStereotype>
+
+ <para>
+ It is possible to make existing annotations into qualifiers, stereotypes or interceptor bindings.
+ </para>
+
+ <para>
+ This configures a stereotype annotation <literal>SomeStereotype</literal> that has a single interceptor
+ binding and is named:
+ </para>
+
+ <programlisting role="XML" ><![CDATA[<test:SomeStereotype>
<s:Stereotype/>
<test:InterceptorBinding/>
<s:Named/>
- </test:SomeStereotype>
-]]>
-</programlisting>
-<para>This configures a qualifier annotation:</para>
-<programlisting role="XML" >
-<![CDATA[
- <test:SomeQualifier>
+ </test:SomeStereotype>]]></programlisting>
+
+ <para>
+ This configures a qualifier annotation:
+ </para>
+
+<programlisting role="XML" ><![CDATA[<test:SomeQualifier>
<s:Qualifier/>
- </test:SomeQualifier>
-]]>
-</programlisting>
-<para>This configures an interceptor binding:</para>
-<programlisting role="XML" >
-<![CDATA[
- <test:SomeInterceptorBinding>
+ </test:SomeQualifier>]]></programlisting>
+
+ <para>
+ This configures an interceptor binding:
+ </para>
+ <programlisting role="XML" ><![CDATA[<test:SomeInterceptorBinding>
<s:InterceptorBinding/>
- </test:SomeInterceptorBinding>
-]]>
-</programlisting>
- </section>
+ </test:SomeInterceptorBinding>]]></programlisting>
+
+ </section>
- <section>
+ <section>
<title>Virtual Producer Fields</title>
<para>
Seam XML supports configuration of virtual producer fields. These allow for configuration
of resource producer fields, Weld Extensions generic bean and constant values directly via
XML. First an exmaple:
</para>
-<programlisting role="XML" >
-<![CDATA[
-<s:EntityManager>
+
+<programlisting role="XML" ><![CDATA[<s:EntityManager>
<s:Produces/>
<sPersistenceContext unitName="customerPu" />
</s:EntityManager>
@@ -562,17 +483,15 @@
<s:Produces/>
<my:VersionQualifier />
<value>Version 1.23</value>
-</s:String>
-]]>
-</programlisting>
+</s:String>]]></programlisting>
+
<para>
The first example configures a resource producer field. The second configures a bean
of type String, with the qualifier <literal>@VersionQualifier</literal> and the value
<literal>'Version 1.23'</literal>. The corresponding java for the above XML is:
</para>
-<programlisting role="java" >
-<![CDATA[
-public class SomeClass
+
+<programlisting role="java" ><![CDATA[class SomeClass
{
@Produces
@@ -583,15 +502,15 @@
@VersionQualifier
String field2 = "Version 1.23";
-}
-]]>
-</programlisting>
- <para>
- Although these look superficially like normal bean declarations, the <literal><Produces></literal>
- declaration means it is treated as a producer field instead of a normal bean.
- </para>
- </section>
+}]]></programlisting>
+
+ <para>
+ Although these look superficially like normal bean declarations, the <literal><Produces></literal>
+ declaration means it is treated as a producer field instead of a normal bean.
+ </para>
+ </section>
+
<section>
<title>More Information</title>
<para>For further information look at the units tests in the seam-xml distribution, also the
@@ -599,4 +518,6 @@
so it may also be worthwhile reading.</para>
</section>
+
+
</chapter>
Modified: modules/xml/trunk/docs/src/main/docbook/en-US/xml-introduction.xml
===================================================================
--- modules/xml/trunk/docs/src/main/docbook/en-US/xml-introduction.xml 2010-10-14 10:00:04 UTC (rev 13852)
+++ modules/xml/trunk/docs/src/main/docbook/en-US/xml-introduction.xml 2010-10-14 10:01:22 UTC (rev 13853)
@@ -7,8 +7,7 @@
<para>
Seam provides a method for configuring JSR-299 beans using XML. Using XML
it is possible to add new beans, override existing beans, and add
- extra configuration to existing beans. The default is to add a new
- bean.
+ extra configuration to existing beans.
</para>
<section>
@@ -56,8 +55,7 @@
<para>
And the following support classes:
</para>
- <programlisting role="JAVA">
- <![CDATA[interface Datasource {
+ <programlisting role="JAVA"><![CDATA[interface Datasource {
public Data getData();
}
@@ -84,29 +82,28 @@
configure up multiple <literal>Report</literal>
beans via xml.
</para>
+ <example>
<programlistingco>
<areaspec>
- <area id="namepsace-declaration-seam" coords="6" />
- <area id="namepsace-declaration-reports" coords="7" />
- <area id="resport-dec" coords="9" />
- <area id="specializes" coords="10" />
- <area id="filename" coords="11" />
- <area id="datasource-qualifier" coords="13" />
- <area id="filename-short" coords="17" />
- <area id="replaces" coords="18" />
- <area id="inject" coords="20" />
- <area id="datasource-type" coords="21" />
+ <area id="namepsace-declaration-seam" coords="4" />
+ <area id="namepsace-declaration-reports" coords="5" />
+ <area id="resport-dec" coords="7" />
+ <area id="modifies" coords="8" />
+ <area id="filename" coords="9" />
+ <area id="datasource-qualifier" coords="11" />
+ <area id="filename-short" coords="15" />
+ <area id="replaces" coords="16" />
+ <area id="inject" coords="18" />
+ <area id="datasource-type" coords="19" />
</areaspec>
- <programlisting role="XML">
- <![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
+ <programlisting ><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:s="urn:java:ee"
xmlns:r="urn:java:org.example.reports">
<r:Report>
- <s:specializes/>
+ <s:modifies/>
<r:filename>sales.jrxml<r:filename>
<r:datasource>
<r:SalesQualifier/>
@@ -135,36 +132,53 @@
<callout arearefs="namepsace-declaration-reports">
<para>
+ There are now multiple namespaces in the <literal>beans.xml</literal>
+ file. These namespaces correspond to java package names.
+ </para>
+ <para>
The namespace <literal>urn:java:org.example.reports</literal>
corresponds to the package <literal>org.example.reports</literal>,
where our reporting classes live. Multiple java packages can be aggregated
- into a single namespace declaration by selerating the package names
+ into a single namespace declaration by seperating the package names
with colons, e.g.
- <literal>urn:java:org.example.reports:org.example.model</literal>
+ <literal>urn:java:org.example.reports:org.example.model</literal>.
+ The namespaces are searched in the order they are specified in the xml
+ document, so if two packages in the namespace have a class with the same name,
+ the first one listed will be resolved. For more information see
+ <link linkend="xml.namespaces">Namespaces</link>.
</para>
</callout>
<callout arearefs="resport-dec">
<para>
The <literal><Report></literal> declaration configures an
- instance of our <literal>Report</literal> class as a bean.
+ instance of our <code>Report</code> class as a bean.
</para>
</callout>
- <callout arearefs="specializes">
+ <callout arearefs="modifies">
<para>
- Beans installed using <literal><s:specializes></literal>
+ Beans installed using <literal><s:modifies></literal>
read annotations from the existing class, and merge them with
the annotations defined via xml. In addition if a bean is
- installed with <literal><s:specializes></literal>
- it prevents the original class being installed as a bean.
+ installed with <literal><s:modifies></literal>
+ it prevents the original class being installed as a bean. It
+ is also possible to add new beans and replace beans altogether,
+ for more information see
+ <link linkend="xml.installing-beans">Adding, modifying and
+ replacing beans</link>.
+
</para>
</callout>
<callout arearefs="filename">
<para>
The <literal><r:filename></literal> element sets the
- initial value of the filename field.
+ initial value of the filename field. For more information on how
+ methods and fields are resolved see
+ <link linkend="xml.configuring-methods">Configuring Methods</link>,
+ and
+ <link linkend="xml.configuring-fields">Configuring Fields</link>.
</para>
</callout>
@@ -213,12 +227,12 @@
</calloutlist>
</programlistingco>
-
+ </example>
</section>
<section>
<title>The Princess Rescue Example</title>
<para>
- TODO
+ TODO next release
</para>
</section>
<!--
More information about the seam-commits
mailing list