[seam-commits] Seam SVN: r13853 - modules/xml/trunk/docs/src/main/docbook/en-US.

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>&lt;test:ProducerBean&gt;</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>&lt;test:value/&gt;</literal> declaration has several child elements. The <literal>&lt;s:Produces/&gt;</literal> - element tells the container that this is a producer field. <literal>&lt;test:ProducerQualifier/&gt;</literal> element defines a qualifier for the producer - field. The <literal>&lt;s:value&gt;</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>&lt;ns:Report&gt;</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>&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 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>&lt;s:replaces&gt;</literal> and @@ -198,8 +79,10 @@ <para>The <literal>&lt;s:replaces&gt;</literal> tag prevents the existing 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 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>&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 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>&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 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>&lt;test:doStuff&gt;</literal> - entry in the XML file configures the method that takes no arguments. The - <literal>&lt;s:Produces&gt;</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>&lt;s:parameters&gt;</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>&lt;test:doStuff&gt;</literal> + entry in the XML file configures the method that takes no arguments. The + <literal>&lt;s:Produces&gt;</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>&lt;s:parameters&gt;</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>&lt;s:array&gt;</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>&lt;s:array&gt;</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>&lt;parameters&gt;</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>&lt;Produces&gt;</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>&lt;Produces&gt;</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>&lt;Report&gt;</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>&lt;s:specializes&gt;</literal> + Beans installed using <literal>&lt;s:modifies&gt;</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>&lt;s:specializes&gt;</literal> - it prevents the original class being installed as a bean. + installed with <literal>&lt;s:modifies&gt;</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>&lt;r:filename&gt;</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> <!--