[seam-commits] Seam SVN: r12062 - in modules/xml/trunk/docs: en-US and 1 other directories.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Thu Feb 18 23:02:29 EST 2010
Author: swd847
Date: 2010-02-18 23:02:28 -0500 (Thu, 18 Feb 2010)
New Revision: 12062
Added:
modules/xml/trunk/docs/README.TXT
modules/xml/trunk/docs/en-US/
modules/xml/trunk/docs/en-US/master.xml
modules/xml/trunk/docs/en-US/xml-general.xml
Removed:
modules/xml/trunk/docs/src/main/docbook/
modules/xml/trunk/docs/src/main/en-US/
Modified:
modules/xml/trunk/docs/pom.xml
Log:
Added the start of the seam-xml docs
Added: modules/xml/trunk/docs/README.TXT
===================================================================
--- modules/xml/trunk/docs/README.TXT (rev 0)
+++ modules/xml/trunk/docs/README.TXT 2010-02-19 04:02:28 UTC (rev 12062)
@@ -0,0 +1,3 @@
+To build the Seam XML docs run the following command:
+
+mvn jdocbook:generate
Added: modules/xml/trunk/docs/en-US/master.xml
===================================================================
--- modules/xml/trunk/docs/en-US/master.xml (rev 0)
+++ modules/xml/trunk/docs/en-US/master.xml 2010-02-19 04:02:28 UTC (rev 12062)
@@ -0,0 +1,11 @@
+<?xml version='1.0' encoding="utf-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+<book lang="en">
+
+ <toc/>
+
+ <title>Seam XML Configuration</title>
+ <xi:include href="xml-general.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</book>
\ No newline at end of file
Added: modules/xml/trunk/docs/en-US/xml-general.xml
===================================================================
--- modules/xml/trunk/docs/en-US/xml-general.xml (rev 0)
+++ modules/xml/trunk/docs/en-US/xml-general.xml 2010-02-19 04:02:28 UTC (rev 12062)
@@ -0,0 +1,326 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<chapter id="remoting">
+ <title>Seam XML General</title>
+
+ <para>Seam provides a method for configuring JSR-299 beans using XML. By default the XML configuration defines new beans,
+ it does not change existing beans.
+ </para>
+
+ <section>
+ <title>Configuration</title>
+ <para>No special configuration is required to use seam-xml, all that is required is to include the jar file in your delpoyment. </para>
+ </section>
+
+ <section>
+ <title>Getting Started</title>
+ <para>By default XML files are discovered from the classpath. The extension looks for an XML file named <literal>seam-bean.xml</literal> in the following locations: </para>
+ <itemizedlist>
+ <listitem><para>The root of an archive</para></listitem>
+ <listitem><para><literal>WEB-INF</literal></para></listitem>
+ <listitem><para><literal>META-INF</literal></para></listitem>
+ </itemizedlist>
+
+ <para>Lets start with a simple example</para>
+ <programlisting>
+ <![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<Beans xmlns="urn:seam:core"
+ xmlns:test="urn:java:org.jboss.seam.xml.test.injection">
+
+ <test:ProducerQualifier>
+ <Qualifier/>
+ </test:ProducerQualifier>
+
+ <test:ProducerBean>
+ <test:value>
+ <Produces/>
+ <test:ProducerQualifier/>
+ <value>hello world</value>
+ </test:value>
+ </test:ProducerBean>
+
+ <test:RecieverBean>
+ <test:value>
+ <test:ProducerQualifier/>
+ <Inject/>
+ </test:value>
+ </test:RecieverBean>
+
+</Beans>
+ ]]>
+ </programlisting>
+ <para>From the top:</para>
+
+
+ <para>The root element of the file has to be <literal><Beans/></literal>, and the root namespace should be <literal>urn:seam:core</literal>.
+ You will also notice that there is a second namespace defined, <literal>urn:java:org.jboss.seam.xml.test.injection</literal>, this namespace is used
+ to resolve classes in the java package <literal>org.jboss.seam.xml.test.injection</literal>.</para>
+ <programlisting>
+ <![CDATA[
+<test:ProducerQualifier>
+ <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>
+ <![CDATA[
+<test:ProducerBean>
+ <test:value>
+ <Produces/>
+ <test:ProducerQualifier/>
+ <value>hello world</value>
+ </test:value>
+</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 ProducerBean, instead it installs a new bean. In
+ this instance there will be two ProducerBean CDI beans.</para>
+
+ <para>This bean has a field called 'value', 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><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><value></literal> element defines an initial value for the field.</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>
+ <![CDATA[
+public class ProducerBean
+{
+ @Produces
+ @ProducerQualifier
+ public String value = "hello world";
+}
+ ]]>
+ </programlisting>
+ <programlisting>
+ <![CDATA[
+<test:RecieverBean>
+ <test:value>
+ <test:ProducerQualifier/>
+ <Inject/>
+ </test:value>
+</test:RecieverBean>
+ ]]>
+ </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>
+ <title>The root namespace</title>
+ <para>The root namesapce can contain the following elements:</para>
+
+ <itemizedlist>
+ <listitem><para><literal>Beans</literal></para></listitem>
+ <listitem><para><literal>veto</literal></para></listitem>
+ <listitem><para><literal>value</literal></para></listitem>
+ <listitem><para><literal>key</literal></para></listitem>
+ <listitem><para><literal>entry</literal></para></listitem>
+ <listitem><para><literal>array</literal></para></listitem>
+ <listitem><para><literal>e</literal> (alias for entry)</para></listitem>
+ <listitem><para><literal>v</literal> (alias for value)</para></listitem>
+ <listitem><para><literal>k</literal> (alias for key)</para></listitem>
+ </itemizedlist>
+
+ <para>as well as classes from the following packages:</para>
+
+ <itemizedlist>
+ <listitem><para><literal>java.lang</literal></para></listitem>
+ <listitem><para><literal>java.util</literal></para></listitem>
+ <listitem><para><literal>javax.annotation</literal></para></listitem>
+ <listitem><para><literal>javax.inject</literal></para></listitem>
+ <listitem><para><literal>javax.enterprise.inject</literal></para></listitem>
+ <listitem><para><literal>javax.enterprise.context</literal></para></listitem>
+ <listitem><para><literal>javax.enterprise.event</literal></para></listitem>
+ <listitem><para><literal>javax.decorator</literal></para></listitem>
+ <listitem><para><literal>javax.interceptor</literal></para></listitem>
+ <listitem><para><literal>javax.persistence</literal></para></listitem>
+ <listitem><para><literal>javax.xml.ws</literal></para></listitem>
+ <listitem><para><literal>javax.jms</literal></para></listitem>
+ <listitem><para><literal>javax.sql</literal></para></listitem>
+ </itemizedlist>
+
+ <para>So the <literal><Produces></literal> element above actually resolved to <literal>java.enterprise.inject.Produces</literal>
+ and the <literal><Inject></literal> element resolved to <literal>javax.inject.Inject</literal>.</para>
+
+ </section>
+
+ <section>
+ <title>Replacing existing bean declarations</title>
+ <para>It is possible to prevent an existing bean being installed using the <literal><veto/></literal> tag:</para>
+ <programlisting>
+ <![CDATA[
+<veto>
+ <test:ProducerBean/>
+ <test:RecieverBean/>
+</veto>
+ ]]>
+ </programlisting>
+ <para>The code above would prevent the <literal>ProducerBean</literal> and <literal>RecieverBean</literal> that was discovered in the bean discovery phase from being installed.
+ Using the veto tag it is possible to replace beans instead of just installing new ones. </para>
+ </section>
+
+ <section>
+ <title>Initial Field Values</title>
+ <para>Inital field values can be set in two different ways, in addition to the <literal><value></literal> element shown above it can be set as follows:</para>
+ <programlisting>
+ <![CDATA[
+<test:someField>hello world</test:someField>
+ ]]>
+ </programlisting>
+
+ <para>Using this method prevents you from adding any annotations 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>
+ <![CDATA[
+<test:ArrayFieldValue>
+ <test:iarray>
+ <value>1</value>
+ <value>2</value>
+ </test:iarray>
+ <test:carray>
+ <value>java.lang.Integer</value>
+ <value>java.lang.Long</value>
+ </test:carray>
+ <test:sarray>
+ <value>hello</value>
+ <value>world</value>
+ </test:sarray>
+</test:ArrayFieldValue>
+
+<test:MapFieldValue>
+ <test:map1>
+ <entry><key>1</key><value>hello</value></entry>
+ <entry><key>2</key><value>world</value></entry>
+ </test:map1>
+ <test:map2>
+ <e><k>1</k><v>java.lang.Integer</v></e>
+ <e><k>2</k><v>java.lang.Long</v></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>
+
+ </section>
+ <section>
+ <title>Configuring methods</title>
+
+ <para>It is also possible to configure methods in a similar way to configuring fields:</para>
+ <programlisting>
+ <![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<Beans xmlns="urn:seam:core"
+ xmlns:test="urn:java:org.jboss.seam.xml.test.method">
+ <test:MethodBean>
+ <test:method>
+ <Produces/>
+ </test:method>
+ <test:method>
+ <Produces/>
+ <test:Qualifier1/>
+ <test:MethodValueBean>
+ <test:Qualifier2/>
+ </test:MethodValueBean>
+ </test:method>
+ </test:MethodBean>
+</Beans>
+
+public class MethodBean
+{
+
+ public int method()
+ {
+ return 1;
+ }
+
+ public int method(MethodValueBean bean)
+ {
+ return bean.value + 1;
+ }
+
+}
+
+ ]]>
+ </programlisting>
+
+ <para>In this instance <literal>MethodBean</literal> has two methods, both of them rather imaginatively named <literal>method</literal>.
+ The first <literal><test:method></literal> entry in the XML file configures the method that takes no arguments.
+ The <literal><Produces></literal> element makes it into a producer method. The next entry in the file configures
+ the method that takes a <literal>MethodValueBean</literal> as a parameter.When configuring methods non-annotation classes are
+ considered to represent method paramters. If these parameters have annotation children they are taken to be annotations
+ on the parameter.</para>
+
+ <para>In this instance the corresponding java declaration would be:</para>
+ <programlisting>
+ <![CDATA[
+ at Produces
+ at Qualifier1
+public int method(@Qualifier2 MethodValueBean param) {//method body}
+ ]]>
+ </programlisting>
+ <para>Array parameters can be represented using the <literal><array></literal> element, with a child element to
+ represent the type of the array. E.g.</para>
+ <programlisting>
+int method(MethodValueBean[] param);
+ </programlisting>
+ <para>could be configured via xml using the following:</para>
+ <programlisting>
+ <![CDATA[
+<test:method>
+ <array>
+ <test:MethodValueBean/>
+ </array>
+</test:method>
+ ]]>
+ </programlisting>
+ </section>
+
+ <section>
+ <title>Annotation Members</title>
+ <para>It is also possible to set the value of annotation members by. For example:</para>
+ <programlisting>
+ <![CDATA[
+public @interface OtherQualifier
+{
+ String value1();
+
+ int value2();
+
+ QualifierEnum value();
+}
+
+
+<test:QualifiedBean1>
+ <test:OtherQualifier value1="AA" value2="1">A</test:OtherQualifier>
+</test:QualifiedBean1>
+
+<test:QualifiedBean2>
+ <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>
+ </section>
+
+ <section>
+ <title>More Information</title>
+ <para>For further information look at the units tests in the seam-xml distribution, also the JSR-299
+ public review draft section on XML Configuration was the base for this extension,
+ so it may also be worthwhile reading.</para>
+ </section>
+
+</chapter>
Property changes on: modules/xml/trunk/docs/en-US/xml-general.xml
___________________________________________________________________
Name: svn:executable
+ *
Modified: modules/xml/trunk/docs/pom.xml
===================================================================
--- modules/xml/trunk/docs/pom.xml 2010-02-18 13:45:25 UTC (rev 12061)
+++ modules/xml/trunk/docs/pom.xml 2010-02-19 04:02:28 UTC (rev 12062)
@@ -1,14 +1,19 @@
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.jboss.weld</groupId>
+ <artifactId>weld-parent</artifactId>
+ <version>8</version>
+ </parent>
- <groupId>org.jboss.seam</groupId>
- <artifactId>xml-reference-guide</artifactId>
- <version>1.0.0-SNAPSHOT</version>
+ <groupId>org.jboss.seam.xml</groupId>
+ <artifactId>seam-xml-reference-guide</artifactId>
+ <version>3.0.0-SNAPSHOT</version>
<packaging>jdocbook</packaging>
+ <name>Seam XML Reference Guide</name>
- <name>Seam XML Reference Guide</name>
-
<pluginRepositories>
<pluginRepository>
<id>repository.jboss.org</id>
@@ -24,31 +29,100 @@
</repository>
</repositories>
+ <properties>
+ <pdf.name>xml-reference.pdf</pdf.name>
+ <weld.docbook.version>1.1.1-Beta5</weld.docbook.version>
+ </properties>
+
<build>
+ <defaultGoal>process-classes</defaultGoal>
<plugins>
<plugin>
<groupId>org.jboss.maven.plugins</groupId>
<artifactId>maven-jdocbook-plugin</artifactId>
-
- <configuration>
- <sourceDocumentName>master.xml</sourceDocumentName>
- <masterTranslation>en-US</masterTranslation>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <finalName>remoting-reference.pdf</finalName>
- </format>
- <format>
- <formatName>html</formatName>
- <finalName>index.html</finalName>
- </format>
- </formats>
- <options>
- <xincludeSupported>false</xincludeSupported>
- </options>
- </configuration>
</plugin>
+ <plugin>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <execution>
+ <phase>process-classes</phase>
+ <configuration>
+ <tasks>
+ <copy file="${basedir}/target/docbook/publish/en-US/pdf/${pdf.name}" todir="${basedir}" />
+ </tasks>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>build-helper-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>attach-zip</id>
+ <phase>package</phase>
+ <goals>
+ <goal>attach-artifact</goal>
+ </goals>
+ <configuration>
+ <artifacts>
+ <artifact>
+ <file>${project.build.outputDirectory}/${project.artifactId}-${project.version}.war</file>
+ <type>war</type>
+ </artifact>
+ </artifacts>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
</plugins>
</build>
-
-</project>
\ No newline at end of file
+
+ <profiles>
+
+ <profile>
+ <id>translations</id>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+
+ <executions>
+ <execution>
+ <phase>process-resources</phase>
+ <goals>
+ <goal>translate</goal>
+ </goals>
+ </execution>
+ </executions>
+
+ <configuration>
+ <translations>
+ <!--translation>it-IT</translation>
+ <translation>zh-CN</translation>
+ <translation>zh-TW</translation>
+ <translation>es-ES</translation>
+ <translation>ko-KR</translation>
+
+ <translation>de-DE</translation>
+ <translation>pt-BR</translation-->
+ </translations>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+
+ </profiles>
+
+
+ <scm>
+ <connection>scm:svn:http://anonsvn.jboss.org/repos/seam/modules/xml/trunk/docs</connection>
+ <developerConnection>scm:svn:https://svn.jboss.org/repos/seam/modules/xml/trunk/docs</developerConnection>
+ <url>http://fisheye.jboss.org/browse/seam/modules/xml/docs</url>
+ </scm>
+</project>
More information about the seam-commits
mailing list