6:40 p.m.
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><a4j:poll></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><a4j:poll></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's necessary to set an update interval. The <emphasis>
<property>"interval"</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><a4j:poll></property>
</emphasis> component is a sum of an<emphasis>
<property>"interval"</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>"interval"</property>
- </emphasis> attribute is set to 1000 milliseconds (1 second). See an example
of definition in
+ </emphasis> attribute is set to "1000" milliseconds (1
second). See an example of definition in
the <link linkend="creating">"Creating on a page"
section</link>. </para>
<para>The <emphasis>
<property>"timeout"</property>
@@ -95,7 +95,7 @@
</emphasis> attribute. You can use an EL-expression for <emphasis>
<property>"enabled"</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>"reRender"</property>
</emphasis> attribute for <emphasis role="bold">
<property><a4j:poll></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>"enabled"</property>
</emphasis> attribute.</para>
+
+ <note><title>Note:</title> The form around the <emphasis
role="bold">
+ <property><a4j:poll></property>
+ </emphasis> component is required.</note>
- <!--It's also necessary to define an ID of the <emphasis
role="bold">
- <property><a4j:poll></property>
- </emphasis> componet in its <emphasis>
- <property>"reRender"</property>
- </emphasis> attribute to apply the current value of <emphasis>
- <property>"enabled"</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><a4j:push></property>
+ </emphasis> component is similar to the <emphasis
role="bold">
+ <property><a4j:poll></property>
+ </emphasis>
+ <link linkend="poll_d"> one</link>. The main difference is
that the<emphasis role="bold">
+ <property><a4j:push></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'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>"interval"</property>
+ </emphasis> attribute has value "2000". This attribute
defines an interval
+ in milliseconds beetween the previous response and the next request. Default value
is set to
+ "1000" milliseconds (1 second). It's possible to set
value equal to
+ "0". In this case connection is permanent. </para>
+ <para>The <emphasis>
+ <property>"timeout"</property>
+ </emphasis> attribute defines response wating time in milliseconds. If the
response
+ isn't received during this period a connection is aborted and the next
request is
+ sent. Default value for <emphasis>
+ <property>"timeout"</property>
+ </emphasis> attribute isn't set. Usage of <emphasis>
+ <property>"interval"</property>
+ </emphasis> and <emphasis>
+ <property>"timeout"</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><a4j:push></property></emphasis>and
<emphasis
role="bold"><property><a4j:poll></property></emphasis>
components
is that <emphasis
role="bold"><property><a4j:push></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>
"interval" - 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><a4j:push></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><a4j:push></property>
+ </emphasis> usage and sources for the given example. </para>
+ </section>
+</chapter>