Author: bleathem Date: 2011-11-22 14:28:59 -0500 (Tue, 22 Nov 2011) New Revision: 22974 Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Actions.xml Log: Grammar cleanup of the push component documentation Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Actions.xml =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Actions.xml 2011-11-22 15:00:50 UTC (rev 22973) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Actions.xml 2011-11-22 19:28:59 UTC (rev 22974) @@ -558,7 +558,7 @@ <itemizedlist> <listitem> <para> - <emphasis>JMS</emphasis> - RichFaces Push consumes messages from enterprise messaging system and exposes them to client (tightly couples with JMS runtime) + <emphasis>JMS</emphasis> - RichFaces Push consumes messages from enterprise messaging system and exposes them to client (tightly coupled with JMS runtime) </para> </listitem> <listitem> @@ -568,12 +568,12 @@ </listitem> <listitem> <para> - <emphasis>Push CDI</emphasis> - uses CDI Events mechanism to access TopicsContext + <emphasis>Push CDI</emphasis> - uses the CDI Event mechanism to access TopicsContext </para> </listitem> </itemizedlist> <para> - On the client side, push notification may be processed by following ways: + On the client side, push notifications may be processed in the following ways: </para> <itemizedlist> <listitem> @@ -583,7 +583,7 @@ </listitem> <listitem> <para> - Attaching behavior to <code>dataavailable</code> event - any behavior may be attached (<sgmltag>&lt;a4j:ajax&gt;</sgmltag>, <sgmltag>&lt;rich:componentControl&gt;</sgmltag>, etc.) + Attaching a behavior to the <code>dataavailable</code> event - any behavior may be attached (<sgmltag>&lt;a4j:ajax&gt;</sgmltag>, <sgmltag>&lt;rich:componentControl&gt;</sgmltag>, etc.) </para> </listitem> </itemizedlist> @@ -592,42 +592,42 @@ <section id="sect-Component_Reference-a4jpush-Push_Topics"> <title>Push Topics</title> <para> - No matter which type way of producing messages is chosen, message is delivered to the client based on the topic name (with optional subtopic). + No matter which method of producing messages is chosen, the message is delivered to the client based on the topic name (with optional subtopic). </para> <para> Examples of topic names might be <code>someTopic</code> or <code>subtopic@anotherTopic</code>. </para> <note> - Push topic name format is very close to JMS topic names and thus enables seamless transport of JMS messages to RichFaces message queue. + The format for the name of the push topic is very close to that of the JMS topic name and thus enables seamless transport of JMS messages to the RichFaces message queue. </note> </section> <section id="sect-Component_Reference-a4jpush-Handling_a_push_notification"> <title>Handling a push notification</title> <para> - A push notification from server sent to the <sgmltag>&lt;a4j:push&gt;</sgmltag> component on client will cause it to trigger any event handlers defined using the <varname>dataavailable</varname> event handler. + A push notification sent from the server to the <sgmltag>&lt;a4j:push&gt;</sgmltag> component on the client will cause it to trigger any event handlers defined using the <varname>dataavailable</varname> event handler. </para> <para> - The <sgmltag>&lt;a4j:push&gt;</sgmltag> component should also include the <varname>error</varname> event handler to inform the user when an error has occurred with the push notifications. + The <sgmltag>&lt;a4j:push&gt;</sgmltag> component should also include the <varname>onerror</varname> event handler to inform the user when an error has occurred with the push notifications. </para> <para> - Topic name may be determined dynamically in runtime, using Expression Language expressions. + The topic name may be determined dynamically at runtime, using Expression Language expressions. </para> <example id="exam-Component_Reference-a4jpush-Handling_a_push_notification"> <title>Handling a push notification</title> <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-a4jpush-Handling_a_push_notification.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - The example uses the <varname>dataavailable</varname> event attribute with JavaScript to update messages in a chat room. The <parameter>event.rf.data</parameter> parameter contains JMS message data serialized to JavaScript. + This example uses the <varname>dataavailable</varname> event attribute with some JavaScript to update messages in a chat room. The <parameter>event.rf.data</parameter> parameter contains JMS message data serialized to JavaScript. </para> </example> <para> - <sgmltag>&lt;a4j:push&gt;</sgmltag> can be used for both, immediate processing of message (like in example above) or it can trigger partial page update. + <sgmltag>&lt;a4j:push&gt;</sgmltag> can be used for either immediate processing of messages (like in the previous example) or it can trigger partial page update (see the following example). </para> <example id="exam-Component_Reference-a4jpush-Updating_DOM_for_each_push_notification"> <title>Updating DOM for each push notification</title> <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-a4jpush-Updating_DOM_for_each_push_notification.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - The example uses the <varname>dataavailable</varname> event handler to trigger AJAX request and partial page update. + This example uses the <varname>dataavailable</varname> event handler to trigger an AJAX request and partial page update. </para> </example> </section> @@ -714,7 +714,7 @@ <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-a4jpush-Basic_usage.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <programlisting language="Java" role="JAVA"><xi:include parse="text" href="extras/exam-Component_Reference-a4jpush-Basic_usage.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - The example demonstrates a simple use of the <sgmltag>&lt;a4j:push&gt;</sgmltag> causing immediate update of page content. + This example demonstrates a simple use of the <sgmltag>&lt;a4j:push&gt;</sgmltag> causing immediate update of page content. </para> </example> </section> @@ -722,30 +722,30 @@ <section id="sect-Component_Reference-a4jpush-Using_Push_without_JMS"> <title>Using Push without JMS</title> <para> - Since JMS coupling may be unwanted in certain cases, RichFaces provides switch which turns off JMS integration: + Since JMS coupling may be unwanted in certain cases, RichFaces provides a switch to turn off the JMS integration: </para> <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-a4jpush-Using_Push_without_JMS.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - This switch is important in situations when you want to use alternative situations of sending push notifications: <emphasis>Push CDI</emphasis> or <code>TopicsContext</code> programmatic interface. + This switch is necessary when you want to make use of the alternative methods for sending push notifications: <emphasis>Push CDI</emphasis> or the <code>TopicsContext</code> programmatic interface. </para> </section> <section id="sect-Component_Reference-a4jpush-Using_TopicsContext_to_publish_message"> <title>Using TopicsContext to publish message</title> <para> - Alternative way of producing messages is using <code>TopicsContext</code> interface directly as in following sample: + Alternative way of producing messages is using the <code>TopicsContext</code> interface directly as in the following sample: </para> <programlisting language="Java" role="JAVA"><xi:include parse="text" href="extras/exam-Component_Reference-a4jpush-Using_TopicsContext_to_publish_message.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - Sending message using <code>TopicsContext</code> involves creating <code>TopicKey</code> instance (denominator of given message topic) and looking up for <code>TopicsContext</code> used for topic registration and message publishing. + Sending a message using the <code>TopicsContext</code> involves creating a <code>TopicKey</code> instance (denominator of given message topic) and looking up the <code>TopicsContext</code> used for topic registration and message publishing. </para> <important id="important-Component_Reference-a4jpush-Limitations_for_using_TopicsContext_interface"> - <title>Limitations for using <code>TopicsContext</code> interface</title> + <title>Limitations for using the <code>TopicsContext</code> interface</title> <para> - For using <code>TopicsContext</code> is it necessary having <code>FacesContext</code> instance available in current thread. + Using the <code>TopicsContext</code> requires the <code>FacesContext</code> instance to be available in the current thread. </para> <para> - The method <code>TopicsContext.lookup()</code> can be called only in context of web application class loader (<code>ServiceTracker</code> needs to be accessible for given application). + The method <code>TopicsContext.lookup()</code> can be called only in the context of a web application class loader (<code>ServiceTracker</code> needs to be accessible for given application). </para> </important> </section> @@ -753,20 +753,20 @@ <section id="sect-Component_Reference-a4jpush-Push_CDI_Integration"> <title>Integrating Push with CDI events</title> <para> - Second alternative way of producing messages is using CDI Events mechanism. + A second alternative way of producing messages is to use the CDI Event mechanism. </para> <para> - Push notifications can be produced by annotating CDI event with <code>@Push</code> annotation, which specifies end-point (topic name). + Push notifications can be produced by annotating a CDI event injection point with the <code>@Push</code> annotation, which specifies an end-point (topic name). </para> <para> - Payload of the message is the serialized object sent using CDI event interface (<code>Event.fire(T object)</code>). + The payload of the message is the serialized object sent using the CDI event interface (<code>Event.fire(T object)</code>). </para> <programlisting language="Java" role="JAVA"><xi:include parse="text" href="extras/exam-Component_Reference-a4jpush-Integrating_Push_with_CDI_events.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <important> - For using CDI events for producing push notifications, same <link linkend="important-Component_Reference-a4jpush-Limitations_for_using_TopicsContext_interface">limitations</link> applies as for using <code>TopicsContext</code> interface. + When using CDI events for producing push notifications, the same <link linkend="important-Component_Reference-a4jpush-Limitations_for_using_TopicsContext_interface">limitations</link> apply as for using the <code>TopicsContext</code> interface. </important> <note> - Associations for CDI events and their handlers are constructed in application deployment. Therefore topics can't be dynamically associated using <code>Event.select(Annotation...)</code> and <code>@Push</code> CDI qualifier. + Associations for CDI events and their handlers are constructed during application deployment. Therefore topics can't be dynamically associated using <code>Event.select(Annotation...)</code> and the <code>@Push</code> CDI qualifier. </note> </section>