Author: dan.j.allen Date: 2009-11-02 14:16:04 -0500 (Mon, 02 Nov 2009) New Revision: 4549 Added: doc/trunk/reference/en-US/producerfields.xml Modified: doc/trunk/reference/en-US/injection.xml doc/trunk/reference/en-US/intro.xml doc/trunk/reference/en-US/master.xml doc/trunk/reference/en-US/ri-spi.xml doc/trunk/reference/en-US/scopescontexts.xml doc/trunk/reference/en-US/specialization.xml Log: correct mdashes Modified: doc/trunk/reference/en-US/injection.xml =================================================================== --- doc/trunk/reference/en-US/injection.xml 2009-11-02 19:14:34 UTC (rev 4548) +++ doc/trunk/reference/en-US/injection.xml 2009-11-02 19:16:04 UTC (rev 4549) @@ -408,13 +408,13 @@ <para> Clients of an injected bean do not usually hold a direct reference to a bean instance, unless the bean is - dependent-scoped--in that case, the instance belongs to the bean. + dependent-scoped&#8212;in that case, the instance belongs to the bean. </para> <para> Imagine that a bean bound to the application scope held a direct reference to a bean bound to the request scope. The application-scoped bean is shared between many different requests. However, each request should see - a different instance of the request scoped bean--the current one! + a different instance of the request scoped bean&#8212;the current one! </para> <para> @@ -436,7 +436,7 @@ <para> If you recall, Seam also boasted the ability to reference the current instance of a component. However, Seam went about it differently. In Seam, the references are established prior to the method call and cleared - afterword using an interceptor--a process known as bijection. This model was not very friendly to multiple + afterword using an interceptor&#8212;a process known as bijection. This model was not very friendly to multiple threads sharing instances and thefore the client proxy approach was adopted in CDI instead. </para> </note> @@ -581,7 +581,7 @@ <para> The <literal>@Named</literal> annotation, when added to a bean class, producer method or producer field, - gives an alternate way for that bean to be referenced--by a string-based name. + gives an alternate way for that bean to be referenced&#8212;by a string-based name. </para> <programlisting role="JAVA"><![CDATA[public @Named("cart") @SessionScoped class ShoppingCart { Modified: doc/trunk/reference/en-US/intro.xml =================================================================== --- doc/trunk/reference/en-US/intro.xml 2009-11-02 19:14:34 UTC (rev 4548) +++ doc/trunk/reference/en-US/intro.xml 2009-11-02 19:16:04 UTC (rev 4549) @@ -47,7 +47,7 @@ new services defined by the CDI specification. But you'll be able to use every one of them with CDI -- allowing the container to create and destroy instances of your beans and associate them with a designed context (or scope), injecting them into other beans, using them in EL expressions, specializing them with qualifier - annotations, even adding interceptors and decorators to them -- from this point forward without modifying + annotations, even adding interceptors and decorators to them&#8212;from this point forward without modifying your code. At most, you'll have to add some annotations. </para> @@ -134,9 +134,13 @@ <literal>TextTranslator</literal>, translating the text entered by a user: </para> - <programlisting role="JAVA"><![CDATA[@Named @RequestScoped + <programlistingco> + <areaspec> + <area id="injection" coords="3"/> + </areaspec> + <programlisting role="JAVA"><![CDATA[@Named @RequestScoped public class TranslateController { - private @Inject TextTranslator textTranslator; + @Inject TextTranslator textTranslator; private String inputText; private String translation; @@ -158,13 +162,30 @@ return translation; } }]]></programlisting> + <calloutlist> + <callout arearefs="injection"> + <para> + Field injection of <literal>TextTranslator</literal> instance + </para> + </callout> + </calloutlist> + </programlistingco> + <tip> + <para> + Notice the controller bean is request-scoped and named. Since this combination is so common in web + applications, there's a built-in annotation for it in CDI that we could have used as a shorthand. When the + (stereotype) annotation <literal>@Model</literal> is declared on a class, it creates a request-scoped and + named bean. + </para> + </tip> + <para> - Alternatively, we may obtain an instance programatically from <literal>Instance</literal> - interface paramaterized to the bean type: + Alternatively, we may obtain an instance of <literal>TextTranslator</literal> programatically from an injected + instance of <literal>Instance</literal>, paramaterized with the bean type: </para> - <programlisting role="JAVA"><![CDATA[private @Inject Instance<TextTranslator> textTranslatorSource; + <programlisting role="JAVA"><![CDATA[@Inject Instance<TextTranslator> textTranslatorSource; ... public void translate() { textTranslatorSource.get().translate(inputText); @@ -178,8 +199,8 @@ <para> At system initialization time, the container must validate that exactly one bean exists which satisfies each - injection point. In our example, if no implementation of <literal>Translator</literal> is available -- if the - <literal>SentenceTranslator</literal> EJB was not deployed -- the container would throw an + injection point. In our example, if no implementation of <literal>Translator</literal> is available&#8212;if the + <literal>SentenceTranslator</literal> EJB was not deployed&#8212;the container would throw an <literal>UnsatisfiedDependencyException</literal>. If more than one implementation of <literal>Translator</literal> were available, the container would throw an <literal>AmbiguousDependencyException</literal>. The same for the <literal>TextTranslator</literal> injection @@ -263,7 +284,7 @@ <para> Note that not all clients of a bean are beans themselves. Other objects such as Servlets or Message-Driven - Beans -- which are by nature not injectable, contextual objects -- may also obtain references to beans by + Beans&#8212;which are by nature not injectable, contextual objects&#8212;may also obtain references to beans by injection. </para> @@ -628,7 +649,7 @@ </listitem> <listitem> <para> - It has an appropriate constructor -- either: + It has an appropriate constructor&#8212;either: </para> <itemizedlist> <listitem> @@ -855,7 +876,7 @@ <para> If the producer method has method arguments, as in this example, the container will look for matching beans - and pass them into the method automatically -- another form of dependency injection. + and pass them into the method automatically&#8212;another form of dependency injection. </para> <para>Producer methods may also define matching <emphasis>disposal methods</emphasis>:</para> Modified: doc/trunk/reference/en-US/master.xml =================================================================== --- doc/trunk/reference/en-US/master.xml 2009-11-02 19:14:34 UTC (rev 4548) +++ doc/trunk/reference/en-US/master.xml 2009-11-02 19:16:04 UTC (rev 4549) @@ -24,9 +24,9 @@ <para> Note that this reference guide was started while changes were still being made to the specification. We've done - our best to update it for accuracy. However, if there is a conflict between what is written in this guide and - the specification, the specification is the authority--assume it is correct. If you believe you have found an - error in the specification, then report it to the JSR-299 EG. + our best to update it for accuracy. If you discover a conflict between what is written in this guide and the + specification, the specification is the authority&#8212;assume it is correct. If you believe you have found an error + in the specification, please report it to the JSR-299 EG. </para> </preface> Added: doc/trunk/reference/en-US/producerfields.xml =================================================================== --- doc/trunk/reference/en-US/producerfields.xml (rev 0) +++ doc/trunk/reference/en-US/producerfields.xml 2009-11-02 19:16:04 UTC (rev 4549) @@ -0,0 +1,9 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]> +<chapter id="producerfields"> + + <title>Producer fields</title> + + <para>TODO</para> + +</chapter> Modified: doc/trunk/reference/en-US/ri-spi.xml =================================================================== --- doc/trunk/reference/en-US/ri-spi.xml 2009-11-02 19:14:34 UTC (rev 4548) +++ doc/trunk/reference/en-US/ri-spi.xml 2009-11-02 19:16:04 UTC (rev 4549) @@ -65,7 +65,7 @@ </para> <para> - The CDI specification discusses <emphasis>Bean Deployment Archives</emphasis> (BDAs) &mdash; archives which + The CDI specification discusses <emphasis>Bean Deployment Archives</emphasis> (BDAs)&#8212;archives which are marked as containing beans which should be deployed to the CDI container, and made available for injection and resolution. Weld reuses this description of <emphasis>Bean Deployment Archives</emphasis> in its deployment structure SPI. Each deployment exposes the BDAs which it contains; each BDA may also @@ -105,7 +105,7 @@ <para> <literal>BeanDeploymentArchive</literal> provides three methods which allow it's contents to be discovered - by Weld &mdash; <literal>BeanDeploymentArchive.getBeanClasses()</literal> must return all the classes in the + by Weld&#8212;<literal>BeanDeploymentArchive.getBeanClasses()</literal> must return all the classes in the BDA, <literal>BeanDeploymentArchive.getBeansXml()</literal> must return all the deployment descriptors in the archive, and <literal>BeanDeploymentArchive.getEjbs()</literal> must provide an EJB descriptor for every EJB in the BDA, or an empty list if it is not an EJB archive. @@ -216,7 +216,7 @@ <para> <literal>EJBServices</literal> is used to resolve local EJBs used to back session beans, and must always be provided in an EE environment. <literal>EJBServices.resolveEjb(EjbDescriptor ejbDescriptor)</literal> - returns a wrapper &mdash; <literal>SessionObjectReference</literal> &mdash; around the EJB reference. This + returns a wrapper&#8212;<literal>SessionObjectReference</literal>&#8212;around the EJB reference. This wrapper allows Weld to request a reference that implements the given business interface, and, in the case of SFSBs, both request the removal of the EJB from the container and query whether the EJB has been previously removed. Modified: doc/trunk/reference/en-US/scopescontexts.xml =================================================================== --- doc/trunk/reference/en-US/scopescontexts.xml 2009-11-02 19:14:34 UTC (rev 4548) +++ doc/trunk/reference/en-US/scopescontexts.xml 2009-11-02 19:16:04 UTC (rev 4549) @@ -157,7 +157,7 @@ </itemizedlist> <para> - A conversation represents a task--a unit of work from the point of view of the user. The conversation context + A conversation represents a task&#8212;a unit of work from the point of view of the user. The conversation context holds state associated with what the user is currently working on. If the user is doing multiple things at the same time, there are multiple conversations. </para> Modified: doc/trunk/reference/en-US/specialization.xml =================================================================== --- doc/trunk/reference/en-US/specialization.xml 2009-11-02 19:14:34 UTC (rev 4548) +++ doc/trunk/reference/en-US/specialization.xml 2009-11-02 19:16:04 UTC (rev 4549) @@ -79,8 +79,8 @@ <para> By default, <literal>@Alternative</literal> beans are disabled. We need to <emphasis>enable</emphasis> the - alternative--effectively replacing the bean implementation without the <literal>@Alternative</literal> - annotation--in the <literal>beans.xml</literal> descriptor of a bean deployment archive by specifying the bean + alternative&#8212;effectively replacing the bean implementation without the <literal>@Alternative</literal> + annotation&#8212;in the <literal>beans.xml</literal> descriptor of a bean deployment archive by specifying the bean class (or the class that contains the alternative producer method or field). This activation only applies to beans in the same archive. </para>