From seam-commits at lists.jboss.org Thu Oct 14 06:52:01 2010 Content-Type: multipart/mixed; boundary="===============4216331657219485572==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r13854 - modules/xml/trunk/docs/src/main/docbook/en-US. Date: Thu, 14 Oct 2010 06:52:01 -0400 Message-ID: <201010141052.o9EAq17G008520@svn01.web.mwc.hst.phx2.redhat.com> --===============4216331657219485572== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: swd847 Date: 2010-10-14 06:52:01 -0400 (Thu, 14 Oct 2010) New Revision: 13854 Modified: modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml Log: more documentation work Modified: modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml 2010-10-1= 4 10:01:22 UTC (rev 13853) +++ modules/xml/trunk/docs/src/main/docbook/en-US/xml-general.xml 2010-10-1= 4 10:52:01 UTC (rev 13854) @@ -4,61 +4,70 @@ Seam XML Reference = -
- XML Namespaces - The main namespace is urn:java:ee contain= s builtin tags and types from core packages. - The builtin tags are: +
+ XML Namespaces + = + + The main namespace is urn:java:ee contains bui= ltin tags = + and types from core packages. The builtin tags are: + = - - Beans - modifies - replaces - parameters - value - key - entry - e (alias for entry)<= /listitem> - v (alias for value)<= /listitem> - k (alias for key) - array - int - short - long - byte - char - double - float - boolean - + + Beans + modifies + replaces + parameters + value + key + entry + e (alias for entry) + v (alias for value) + k (alias for key) + array + int + short + long + byte + char + double + float + boolean + = - as well as classes from the following packages: = + + as well as classes from the following packages: + = = - - java.lang - java.util - javax.annotation - javax.inject - javax.enterprise.inject - javax.enterprise.context - javax.enterprise.event - javax.decorator - javax.interceptor - org.jboss.weld.extensions.core - org.jboss.weld.extensions.unwraps - org.jboss.weld.extensions.resourceLoa= der - + + java.lang + java.util + javax.annotation + javax.inject + javax.enterprise.inject= + javax.enterprise.context + javax.enterprise.event<= /listitem> + javax.decorator + javax.interceptor + org.jboss.weld.extensions.core= + org.jboss.weld.extensions.unwraps + org.jboss.weld.extensions.resourceLoader= + = - Other namspaces are specified using the following syntax: + + Other namspaces are specified using the following syntax: + + = - - = + = + = - This maps ns to the packages com.my= domain.package1 = - and com.mydomain.package2. These packages ar= e searched in order to = - resolve elements in this namespace. + This maps the namespace my to the packages = + com.mydomain.package1 and = + com.mydomain.package2. These packages are se= arched in = + order to resolve elements in this namespace. = = - + For example, say you had a class com.mydomain.package2= .Report. = To configure a Report bean you would use = <ns:Report>. Methods and fields on the= bean are resolved @@ -70,22 +79,26 @@ =
= -
- Adding, replacing and modifying beans - By configuring a bean via XML creates a new bean, however th= ere = - may be cases where you want to modify an existing bean rather th= an - adding a new one. The <s:replaces> and = - <s:modifies> tags allow you to do this.= - The <s:replaces> tag prevents the= existing bean from being = - installed, and registers a new one with the given configuration.= The = - <s:modifies> tag does the same, except = that it merges - 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 pos= sible to install = - multiple beans that modify the same class. - +
+ Adding, replacing and modifying beans + = + + 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 <s:replaces> and = + <s:modifies> tags allow you to do this. + + = + + The <s:replaces> tag prevents the existi= ng bean from being = + installed, and registers a new one with the given configuration. = The = + <s:modifies> tag does the same, except t= hat it merges + 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 poss= ible to install = + multiple beans that modify the same class. + = - + @@ -93,32 +106,78 @@ -]]> - - The first entry above adds a new bean with an extra qualifie= r, in addition to the qualifiers already present, = - and prevents the existing Report bean from bein= g installed. = - The second prevents the existing bean from being installed, = and registers a new bean with a single qualifier. -
+]]> + + + The first entry above adds a new bean with an extra qualifier, in= addition = + to the qualifiers already present, and prevents the existing = + Report bean from being installed. + = + = + + The second prevents the existing bean from being installed, and r= egisters = + a new bean with a single qualifier. + + = +
+ +
+ Applying annotations using XML + = + + Annotations are resolved in the same way as normal classes. Conce= ptually = + annotations are applied to the object their parent element in the= resolves + to. It is possible to set the value of annotation members using t= he xml + attribute that corresponds to the member name. For example: = + + = + + + + A + = - + + + +]]> + = + + The value member can be set using the inner text of = the node, as seen = + in the first example. Type conversion is performed automatically. + + = + + + It is currently not possible set array annotation members. + + + = +
= + = +
Configuring Fields + = It is possible to both apply qualifiers to and set the initial va= lue of a field. = Fields reside in the same namespace as the declaring bean, and th= e element name = must exactly match the field name. For example if we have the fol= lowing class: = - class RobotFactory { - Robot robot; - } - + class RobotFactory { + Robot robot; +} = The following xml will add the @Produces annotation = to the = robot field: = = - + @@ -126,7 +185,11 @@ =
Initial Field Values - Inital field values can be set three different ways as show= n below: + = + + Inital field values can be set three different ways as shown b= elow: + + = = @@ -138,12 +201,18 @@ Red Hat Inc -]]> - +]]> = - The third form is the only one that also allows you to add = annotations such as qualifiers to the field. + + The third form is the only one that also allows you to add ann= otations such as = + qualifiers to the field. + = - It is possible to set Map,Array= and Collection field values. Some examples: + + It is possible to set Map,Array and = + Collection field values. Some examples: + + = = @@ -207,6 +276,7 @@ them an artificial qualifier. Inline beans may have any scope,= however the default Dependent scope is = recomended. + = @@ -225,10 +295,11 @@ -]]> = +]]> = + =
= - = +
= =
Configuring methods @@ -236,6 +307,7 @@ It is also possible to configure methods in a similar way to conf= iguring fields: + = @@ -291,11 +363,13 @@ In this instance MethodBean has three methods,= all of them rather = imaginatively named doStuff. + = = The first <test:doStuff> = entry in the XML file configures the method that takes no argumen= ts. The = <s:Produces> element makes it into a pro= ducer method. = + = The next entry in the file configures the method that takes a = MethodValueBean as a parameter and the final e= ntry = @@ -303,6 +377,7 @@ as a parameter. For both these methods a qualifier was added to t= he method parameter and they were made into producer methods. + = Method parameters are specified inside the <s:paramet= ers> element. If these parameters have annotation children they are ta= ken to be annotations on = @@ -316,15 +391,15 @@ = @@ -348,7 +423,8 @@ <parameters> element, in which case it is r= esolved as a method. - = + = + =
=
@@ -403,36 +479,9 @@ =
= - = + =
- Annotation Members - - It is possible to set the value of annotation members using attri= butes in xml. For example: - - - - - A - - = - - - -]]> - - = - - The value member can be set using the inner text of the node, as = seen in the first example. - - = -
- = -
- Configuring Meta Annotations + Configuring Meta Annotations = It is possible to make existing annotations into qualifiers, ster= eotypes or interceptor bindings. @@ -491,7 +540,7 @@ 'Version 1.23'. The corresponding java for the= above XML is: = -