[seam-commits] Seam SVN: r12062 - in modules/xml/trunk/docs: en-US and 1 other directories.

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>&lt;Beans/&gt;</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>&lt;test:value/&gt;</literal> declaration has several child elements. The <literal>&lt;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;value&gt;</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>&lt;Produces&gt;</literal> element above actually resolved to <literal>java.enterprise.inject.Produces</literal> + and the <literal>&lt;Inject&gt;</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>&lt;veto/&gt;</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>&lt;value&gt;</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>&lt;test:method&gt;</literal> entry in the XML file configures the method that takes no arguments. + The <literal>&lt;Produces&gt;</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[ +@Produces +@Qualifier1 +public int method(@Qualifier2 MethodValueBean param) {//method body} + ]]> + </programlisting> + <para>Array parameters can be represented using the <literal>&lt;array&gt;</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/tru... + <developerConnection>scm:svn:https://svn.jboss.org/repos/seam/modules/x... + <url>http://fisheye.jboss.org/browse/seam/modules/xml/docs</url> + </scm> +</project>