Author: vkorluzhenko Date: 2007-11-29 12:40:01 -0500 (Thu, 29 Nov 2007) New Revision: 4358 Modified: trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml trunk/docs/userguide/en/src/main/docbook/included/poll.xml trunk/docs/userguide/en/src/main/docbook/included/push.xml Log: http://jira.jboss.com/jira/browse/RF-657 - improved description Modified: trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml 2007-11-29 17:39:25 UTC (rev 4357) +++ trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml 2007-11-29 17:40:01 UTC (rev 4358) @@ -1,6 +1,6 @@ <?xml version='1.0' encoding='UTF-8'?> <root> - <section> + <section id="poll_d"> <title>Description</title> <para>The <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> Modified: trunk/docs/userguide/en/src/main/docbook/included/poll.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/poll.xml 2007-11-29 17:39:25 UTC (rev 4357) +++ trunk/docs/userguide/en/src/main/docbook/included/poll.xml 2007-11-29 17:40:01 UTC (rev 4358) @@ -63,18 +63,18 @@ <title>Key attributes and ways of usage</title> <para id="attributes">The <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> - </emphasis> componet is used for periodical polling of a server. In order to use the component + </emphasis> componet is used for periodical polling of server data. In order to use the component it&apos;s necessary to set an update interval. The <emphasis> <property>&quot;interval&quot;</property> - </emphasis> attribute defines a polling interval in milliseconds beetween the previous + </emphasis> attribute defines an interval in milliseconds beetween the previous response and the next request. The total period beetween two requests generated by the <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> </emphasis> component is a sum of an<emphasis> <property>&quot;interval&quot;</property> - </emphasis> attribute value and a server response time. Default value for <emphasis> + </emphasis> attribute value and server response time. Default value for <emphasis> <property>&quot;interval&quot;</property> - </emphasis> attribute is set to 1000 milliseconds (1 second). See an example of definition in + </emphasis> attribute is set to &quot;1000&quot; milliseconds (1 second). See an example of definition in the <link linkend="creating">&quot;Creating on a page&quot; section</link>. </para> <para>The <emphasis> <property>&quot;timeout&quot;</property> @@ -95,7 +95,7 @@ </emphasis> attribute. You can use an EL-expression for <emphasis> <property>&quot;enabled&quot;</property> </emphasis> attribute to point to a bean property. An example of usage of <link - linkend="attributes">all mentioned above attributes</link> is placed below:</para> + linkend="attributes">mentioned above attributes</link> is placed below:</para> <para> <emphasis role="bold">Example:</emphasis> @@ -132,20 +132,16 @@ <property>&quot;reRender&quot;</property> </emphasis> attribute for <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> - </emphasis> contains value of own Id. Hence, it renders itself for applying the current value + </emphasis> contains value of its own Id. Hence, it renders itself for applying the current value of <emphasis> <property>&quot;enabled&quot;</property> </emphasis> attribute.</para> + + <note><title>Note:</title> The form around the <emphasis role="bold"> + <property>&lt;a4j:poll&gt;</property> + </emphasis> component is required.</note> - <!--It&apos;s also necessary to define an ID of the <emphasis role="bold"> - <property>&lt;a4j:poll&gt;</property> - </emphasis> componet in its <emphasis> - <property>&quot;reRender&quot;</property> - </emphasis> attribute to apply the current value of <emphasis> - <property>&quot;enabled&quot;</property> - </emphasis> attribute. </para> - - <para>The component decodes all necessary JavaScript for time count and on the expiry of some + <!--para>The component decodes all necessary JavaScript for time count and on the expiry of some interval for calling of a RichFaces utility method for Ajax request sending (A4J.AJAX.Submit (Some request parameters)). </para> <para> The timer could be stopped or started in any time. The current state is controlled on the Modified: trunk/docs/userguide/en/src/main/docbook/included/push.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/push.xml 2007-11-29 17:39:25 UTC (rev 4357) +++ trunk/docs/userguide/en/src/main/docbook/included/push.xml 2007-11-29 17:40:01 UTC (rev 4358) @@ -1,52 +1,106 @@ <?xml version='1.0' encoding='UTF-8'?> <chapter> - - <table> - <title>Component identification parameters </title> - <tgroup cols="2"> - <thead> - <row> - <entry>Name</entry> - <entry>Value</entry> - </row> - </thead> - <tbody> - <row> - <entry>component-type</entry> - <entry>org.ajax4jsf.Push</entry> - </row> - <row> - <entry>component-family</entry> - <entry>org.ajax4jsf.components.AjaxPush</entry> - </row> - <row> - <entry>component-class</entry> - <entry>org.ajax4jsf.component.html.AjaxPush</entry> - </row> - <row> - <entry>renderer-type</entry> - <entry>org.ajax4jsf.components.AjaxPushRenderer</entry> - </row> - </tbody> - </tgroup> - </table> - + + <table> + <title>Component identification parameters </title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>component-type</entry> + <entry>org.ajax4jsf.Push</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.components.AjaxPush</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.component.html.AjaxPush</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.AjaxPushRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + <section> <title>Creating on a page</title> - <programlisting role="XML"><![CDATA[ -<a4j:push reRender="msg" eventProducer="#{messageBean.addListener}" interval="3000"/>]]></programlisting> + <programlisting role="XML"><![CDATA[<a4j:push reRender="msg" eventProducer="#{messageBean.addListener}" interval="3000"/>]]></programlisting> </section> - - <section> + + <section> <title>Dynamical creation of a component from Java code</title> - <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.AjaxPush; + <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.AjaxPush; ... AjaxPush myPush = new AjaxPush(); ...]]></programlisting> </section> - + + <section> <title>Key attributes and ways of usage</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:push&gt;</property> + </emphasis> component is similar to the <emphasis role="bold"> + <property>&lt;a4j:poll&gt;</property> + </emphasis> + <link linkend="poll_d"> one</link>. The main difference is that the<emphasis role="bold"> + <property>&lt;a4j:push&gt;</property> + </emphasis> makes request to minimal code (not to JSF tree) in order to check presence of + messages in a queue. If a message exists, a complete request is performed. The component + doesn&apos;t poll registered bean. It registers <property>EventListener</property>, which + receives messages about event presence. See an example below:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<a4j:push reRender="msg" eventProducer="#{pushBean.addListener}" interval="2000"/> +]]></programlisting> + <para>In the example <emphasis> + <property>&quot;interval&quot;</property> + </emphasis> attribute has value &quot;2000&quot;. This attribute defines an interval + in milliseconds beetween the previous response and the next request. Default value is set to + &quot;1000&quot; milliseconds (1 second). It&apos;s possible to set value equal to + &quot;0&quot;. In this case connection is permanent. </para> + <para>The <emphasis> + <property>&quot;timeout&quot;</property> + </emphasis> attribute defines response wating time in milliseconds. If the response + isn&apos;t received during this period a connection is aborted and the next request is + sent. Default value for <emphasis> + <property>&quot;timeout&quot;</property> + </emphasis> attribute isn&apos;t set. Usage of <emphasis> + <property>&quot;interval&quot;</property> + </emphasis> and <emphasis> + <property>&quot;timeout&quot;</property> + </emphasis> attributes gives an opportunity to set short polls of queue state or long + connections or permanent connection generally.</para> + <para>Code for <property>EventListener</property> registration in a bean is placed below:</para> + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="JAVA"><![CDATA[... +public void addListener(EventListener listener) { +synchronized (listener) { + if (this.listener != listener) { + this.listener = (PushEventListener) listener; +} +... +]]></programlisting> + +<para></para> + + </section> + + <!--section> + <title>Key attributes and ways of usage</title> <para>The main difference between <emphasis role="bold"><property>&lt;a4j:push&gt;</property></emphasis>and <emphasis role="bold"><property>&lt;a4j:poll&gt;</property></emphasis> components is that <emphasis role="bold"><property>&lt;a4j:push&gt;</property></emphasis> makes request to minimal code only (not to JSF tree) in order to check the presence of messages in the queue. @@ -58,7 +112,7 @@ </para> <para> &quot;interval&quot; - Interval (in ms) for call push requests. Default value 1000 (1 sec). -<!-- If "0" a connection is permanent. Also you can set different value for parameter 'timeout'. --> +< If "0" a connection is permanent. Also you can set different value for parameter 'timeout'.> </para> <para> Code for registration of listener: @@ -83,14 +137,14 @@ <para> Thus, component 'push' uses asynchronous model instead of polls. </para> - </section> - + </section--> + <section> <title>Relevant resources links</title> - <para> - <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/push.jsf?c=... - </ulink> you can see the example of <emphasis role="bold" - ><property>&lt;a4j:push&gt;</property></emphasis> usage and sources for the given example. - </para> - </section> -</chapter> \ No newline at end of file + <para> + <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/push.jsf?c=... </ulink> + you can see the example of <emphasis role="bold"> + <property>&lt;a4j:push&gt;</property> + </emphasis> usage and sources for the given example. </para> + </section> +</chapter>