[seam-commits] Seam SVN: r13172 - modules/xml/trunk/docs/src/main/docbook/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Tue Jun 15 20:39:22 EDT 2010
Author: swd847
Date: 2010-06-15 20:39:22 -0400 (Tue, 15 Jun 2010)
New Revision: 13172
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:
update docs
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-06-15 22:31:49 UTC (rev 13171)
+++ modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml 2010-06-16 00:39:22 UTC (rev 13172)
@@ -2,19 +2,10 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="xml">
- <title>Seam XML General</title>
-
- <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.
- </para>
-
+ <title>Seam XML Reference</title>
+
<section>
- <title>Configuration</title>
- <para>No special configuration is required to use seam-xml, all that is required is to include the jar file and the weld extensions jar in your deployment. </para>
- </section>
-
- <section>
- <title>Getting Started</title>
+ <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>
@@ -144,8 +135,9 @@
</section>
<section>
- <title>The main namespace</title>
- <para>The main namesapce is <literal>urn:java:seam:core</literal> can contain the following elements:</para>
+ <title>XML Namespaces</title>
+ <para>The main namesapce is <literal>urn:java:seam:core</literal> contains builtin tags and types from core packages.
+ The builting tags are:</para>
<itemizedlist>
<listitem><para><literal>Beans</literal></para></listitem>
@@ -183,15 +175,17 @@
<listitem><para><literal>javax.interceptor</literal></para></listitem>
</itemizedlist>
- <para>So the <literal><s:Produces></literal> element above actually resolves
- to <literal>java.enterprise.inject.Produces</literal>
- and the <literal><s:Inject></literal> element resolves to <literal>javax.inject.Inject</literal>.</para>
-
+ <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>
</section>
<section>
<title>Overriding and extending beans</title>
- <para>There may be cases where you want to modify an existing bean rather than
+ <para>The default is to add 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:overrides></literal> and
<literal><s:specializes></literal> tags allow you to do this. The
<literal><s:overrides></literal> tag prevents the existing bean from being
@@ -208,8 +202,7 @@
<test:OtherBean>
<s:overrides>
<test:NewQualifier/>
-</test:OtherBean>
- ]]>
+</test:OtherBean>]]>
</programlisting>
<para>The first entry above adds a new qualifier to an existing bean definition. The second prevents the existing bean from being installed, and registers a new bean with a single qualifier.</para>
</section>
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-06-15 22:31:49 UTC (rev 13171)
+++ modules/xml/trunk/docs/src/main/docbook/en-US/xml-introduction.xml 2010-06-16 00:39:22 UTC (rev 13172)
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="introduction">
<title>Seam XML Introduction</title>
@@ -10,7 +10,7 @@
<section>
<title>Getting Started</title>
- <para>No special configuration is required to use seam-xml, all that is required is to include the jar file and the weld extensions jar in your deployment. </para>
+ <para>No special configuration is required, all that is required is to include the jar file and the weld extensions jar in your deployment. </para>
<para>The first thing we need is some xml files, by default these are discovered from the classpath in the following locations:</para>
<itemizedlist>
<listitem><literal>/META-INF/beans.xml</literal></listitem>
@@ -25,122 +25,134 @@
<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. Say we have the following classes:</para>
+ <para>Let's start with a simple example. Say we have the following class that represents a report:</para>
<programlisting role="JAVA">
- <![CDATA[public class Robot
+ <![CDATA[
+public class Report
{
- @Inject RobotArm leftArm;
+ String filename;
- @Inject RobotArm rightArm;
+ @Inject
+ Datasource datasource;
+
+ //getters and setters
}
+]]>
+ </programlisting>
+ <para>And the following support classes:</para>
+ <programlisting role="JAVA">
+ <![CDATA[
+public interface Datasource
+{
+ public Data getData();
+}
-public class RobotArm
+ at SalesQualifier
+public class SalesDatasource implements Datasource
{
- String attachment = "welder";
-
- public void doStuff()
- {
- //do robot things...
- }
+ public Data getData()
+ {
+ //return sales data
+ }
}
- at Retention(RUNTIME)
-public @Interface LeftArm{}
+public class BillingDatasource implements Datasource
+{
+ public Data getData()
+ {
+ //return billing data
+ }
+}
- at Retention(RUNTIME)
-public @Interface RightArm{}
- ]]>
- </programlisting>
- <para>So we have a robot class that injects a left arm and a right arm, with both arms having a welder attachment. At some point in the future we decide that our robot is no longer needed for welding, instead it needs a plasma cutter in it's left hand and a
- vice in its right hand. Rather than modifying the class files, we decide to configure this up with xml:</para>
- <programlistingco>
- <areaspec>
- <area id="namepsace-declaration-seam" coords="5"/>
- <area id="namepsace-declaration-robots" coords="6"/>
- <area id="right-arm-qualifier" coords="9"/>
- <area id="robot-right-arm" coords="16"/>
- <area id="overrrides" coords="17"/>
- <area id="left-arm-applied-qualifier" coords="18"/>
- <area id="left-arm-set-length" coords="19"/>
- <area id="specializes" coords="29"/>
- <area id="left-arm-injected" coords="30"/>
- </areaspec>
+]]>
+ </programlisting>
+
+ <para>Our <literal>Report</literal> bean is fairly simple. It has a filename that tells the report engine where to load the report definition from, and a datasource that provides the data used to
+ fill the report. We are going to configure up multiple <literal>Report</literal> beans via xml.</para>
+ <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="overrides" coords="18"/>
+ <area id="inject" coords="20"/>
+ <area id="datasource-type" coords="21"/>
+ </areaspec>
<programlisting role="XML">
- <![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <![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:seam:core"
- xmlns:r="urn:java:org.example.robots">
-
- <r:RightArm>
- <s:Qualifier/>
- </r:RightArm>
-
- <r:LeftArm>
- <s:Qualifier/>
- </r:LeftArm>
-
- <r:RobotArm>
- <s:overrides/>
- <r:LeftArm/>
- <r:attachment>Plasma Cutter</r:attachment>
- </r:RobotArm>
+ xmlns:r="urn:java:org.example.reports">
+
+ <r:Report>
+ <s:specializes/>
+ <r:filename>sales.jrxml<r:filename>
+ <r:datasource>
+ <r:SalesQualifier/>
+ </r:datasource>
+ </r:Report>
- <r:RobotArm>
+ <r:Report filename="billing.jrxml">
<s:overrides/>
- <r:RightArm/>
- <r:attachment>Vice</r:attachment>
- </r:RobotArm>
-
- <r:Robot>
- <s:specializes/>
- <r:leftArm>
- <r:LeftArm/>
- </r:leftArm>
- <r:rightArm>
- <r:RightArm/>
- </r:rightArm>
- </r:Robot>
-
+ <r:datasource>
+ <s:Inject/>
+ <s:type>
+ <r:BillingDatasource/>
+ </s:type>
+ </r:datasource>
+ </r:Report>
</beans>
]]>
</programlisting>
<calloutlist>
<callout arearefs="namepsace-declaration-seam">
- <para>The namespace <literal>urn:java:seam:core</literal> is seam-xml's root namespace. More on this later</para>
+ <para>The namespace <literal>urn:java:seam:core</literal> is seam-xml's root namespace. This is where the builtin tags and CDI annotations live.</para>
</callout>
- <callout arearefs="namepsace-declaration-robots">
- <para>The namespace <literal>urn:java:org.example.robots</literal> corresponds to the package <literal>org.example.robots</literal>, where our robot classes live.</para>
+ <callout arearefs="namepsace-declaration-reports">
+ <para>The namespace <literal>urn:java:org.example.reports</literal> corresponds to the package <literal>org.example.reports</literal>, where our reporting classes live.</para>
</callout>
- <callout arearefs="right-arm-qualifier">
- <para>This declares the <literal>@RightArm</literal> annotation to be a qualifier. The <literal><r:RightArm></literal> declaration resolves to
- <literal>org.example.robots.RightArm</literal> and the <literal><s:Qualifier></literal> declaration tells seam-xml to register this class as a qualifier.</para>
+ <callout arearefs="resport-dec">
+ <para>The <literal><Report></literal> declaration configures an instance of our <literal>Report</literal> class as a bean.</para>
</callout>
- <callout arearefs="robot-right-arm">
- <para>The <literal><r:RobotArm></literal> declaration configures an instance of our <literal>RobotArm</literal> class.</para>
+ <callout arearefs="specializes">
+ <para>Beans installed using <literal><s:specializes></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.</para>
</callout>
- <callout arearefs="overrrides">
- <para>The <literal><s:overrides></literal> tells CDI that this bean overrides the default bean. The existing <literal>RobotArm</literal> definition will not be
- installed, only <literal>RobotArm</literal> beans that are configured via XML.</para>
+ <callout arearefs="filename">
+ <para>The <literal><r:filename></literal> element sets the initial value of the filename field.</para>
</callout>
- <callout arearefs="left-arm-applied-qualifier">
- <para>The <literal><r:LeftArm></literal> element applies the <literal>@LeftArm</literal> annotation to the enclosing element, in this case out <literal>RobotArm</literal>
- class (remember we declared <literal>@LeftArm</literal> to be a qualifier). In seam-xml an element that resolves to an annotation means 'apply this annotation to the parent element'.</para>
+ <callout arearefs="datasource-qualifier">
+ <para>The <literal><r:SalesQualifier></literal> element applies the <literal>@SalesQualifier</literal> to the <literal>datasource</literal> field.
+ As the field already has an <literal>@Inject</literal> on the class definition this will cause the <literal>SalesDatasource</literal>
+ bean to be injected.</para>
</callout>
- <callout arearefs="left-arm-set-length">
- <para>This sets the arm's attachment field to the string <literal>Plasma Cutter</literal></para>
+ <callout arearefs="filename-short">
+ <para>This is the shorthand syntax for setting a field value.</para>
</callout>
- <callout arearefs="specializes">
- <para>The <literal><s:specializes></literal> is similar to <literal><s:overrides></literal>. The difference is that <literal><s:specializes></literal>
- beans have the annotated from the java class merged with the annotations in XML.</para>
+ <callout arearefs="overrides">
+ <para>Beans installed using <literal><s:overrides></literal> do not read annotations from the existing class. In addition if a bean is installed with
+ <literal><s:overrides></literal> it prevents the original class being installed as a bean.</para>
</callout>
- <callout arearefs="left-arm-injected">
- <para>This configures a qualifier on the injection point. There is no need for an <literal><s:Inject></literal> as it is present on the underlying class.</para>
+ <callout arearefs="inject">
+ <para>The <literal><s:Inject></literal> element is needed this bean was installed with <literal><s:overrides></literal>, so annotations are not read
+ from the class definition.</para>
</callout>
-
+ <callout arearefs="datasource-type">
+ <para>The <literal><s:type></literal> restricts the type of bean that is availible for injection without using qualifiers. In this case
+ <literal>BillingDatasource</literal> will be injected.</para>
+ </callout>
+
</calloutlist>
</programlistingco>
</section>
-
+<!--
+vim:et:ts=3:sw=3:tw=120
+-->
</chapter>
More information about the seam-commits
mailing list