Author: atsebro Date: 2009-06-26 11:43:13 -0400 (Fri, 26 Jun 2009) New Revision: 14734 Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.desc.xml branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.xml Log: RF-7423: a4j:queue component description review Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.desc.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.desc.xml 2009-06-26 14:27:53 UTC (rev 14733) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.desc.xml 2009-06-26 15:43:13 UTC (rev 14734) @@ -7,7 +7,10 @@ </keywordset> </sectioninfo> <title>Description</title> - <para>The <emphasis role="bold"><property>&lt;a4j:queue&gt;</property></emphasis> component creates a queue of the Ajax requests. The Ajax4JSF or RichFaces components with built-in Ajax can reference the queue to optimize Ajax requests.</para> - <para>You can find more information about the <emphasis role="bold"><property>&lt;a4j:queue&gt;</property></emphasis> in the &quot;<link linkend="QueuePrinciples">Queue Principles</link>&quot; section.</para> + <para> + The <emphasis role="bold"><property>&lt;a4j:queue&gt;</property></emphasis> component enqueues set of Ajax requests sent from client. + The <emphasis role="bold"><property>&lt;a4j&gt;</property></emphasis> or <emphasis role="bold"><property>&lt;rich&gt;</property></emphasis> components with built-in Ajax can reference the queue to optimize Ajax requests. + </para> + </section> </chapter> \ No newline at end of file Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.xml 2009-06-26 14:27:53 UTC (rev 14733) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.xml 2009-06-26 15:43:13 UTC (rev 14734) @@ -35,24 +35,23 @@ </tgroup> </table> <section> - <title>Creating on a page</title> - - - <para> - This is how you can create a form based queue. All other types of the queue are described in the &quot;<link linkend="QueuePrinciples">Queue Principles</link>&quot; section. - </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[<h:form> - <a4j:queue /> - <h:inputText value="#{bean.a}"> - <a4j:support event="onkeyup" /> - </h:inputText> -</h:form> -]]></programlisting> + <title>Creating the Component with a Page Tag</title> + <para> + To create the simplest variant of the Form Based queue use the following syntax. + </para> + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<h:form id="form"> + <a4j:queue /> + <h:inputText value="#{bean.a}"> + <a4j:support event="onkeyup" /> + </h:inputText> +</h:form>]]></programlisting> + </section> - <section> + + <section> <title>Creating the Component Dynamically Using Java</title> <para> <emphasis role="bold"> Example: </emphasis> @@ -62,46 +61,49 @@ HtmlQueue myQueue = new HtmlQueue(); ]]></programlisting> </section> - <section> - <title>Key attributes and ways of usage</title> - <para>As it was said earlier the queue implemented in Richfaces has 4 types. - In this section we will take a closer look at the form based queue. All other types of queue are similar is usage(except for the &quot;global queue&quot;) but different is their scope.</para> - + + <section> + <title>Details of usage</title> + + <para> + The RichFaces Queue has four different types: global default, view scoped default, view scoped named and form-based default queue (general Queue principles are good documented in the &quot;<link linkend="QueuePrinciples">Queue Principles</link>&quot; section). + The current section will take closer to the form based queue. The usage of other types is similar. + </para> - <para>In order to disable or enable the <emphasis role="bold"><property - >&lt;a4j:queue&gt;</property></emphasis> component on the page you can use the - <emphasis><property>&quot;disabled&quot;</property></emphasis> attribute.</para> - - <para> The <emphasis><property>&quot;requestDelay&quot;</property></emphasis> attribute - defines delay time for all the requests fired by the action components. </para> <para> + In order to disable or enable the <emphasis role="bold"><property>&lt;a4j:queue&gt;</property></emphasis> component on the page you can use the <emphasis><property>&quot;disabled&quot;</property></emphasis> attribute. + </para> - The <emphasis><property>&quot;size&quot;</property></emphasis> attribute specifies the number of request that can be stored in the queue at a time. - The attribute can help you prevent overloading of a sever with requests. You can also determine the type of behaviour when the size of the queue is exceeded. - </para> - <para>You should use the <emphasis><property>&quot;sizeExceededBehavior&quot;</property></emphasis> for the purpose.</para> - <para> The <emphasis><property>&quot;sizeExceededBehavior&quot;</property></emphasis> - attribute can set 4 the strategies of the queue&apos;s behavior if the number of the - requests waiting in the queue is exceeded: </para> - <itemizedlist> - <listitem> - <para>&quot;dropNext&quot; drops next request that should be fired</para> - </listitem> - <listitem> - <para>&quot;dropNew&quot; drops the incoming request</para> - </listitem> - <listitem> - <para>&quot;fireNext&quot; immediately fires the next request in line to be fired</para> - </listitem> - <listitem> - <para>&quot;fireNew&quot; immediately fires the incoming request.</para> - </listitem> - </itemizedlist> + <para> + The <emphasis><property>&quot;requestDelay&quot;</property></emphasis> attribute defines delay time for all the requests fired by the action components. + </para> + + <para> + The <emphasis><property>&quot;size&quot;</property></emphasis> attribute specifies the number of requests that can be stored in the queue at a time. + The attribute helps to prevent server overloading. + It is also possible to determine queue&apos;s behaviour when it&apos;s size is exceeded. + Use the <emphasis><property>&quot;sizeExceededBehavior&quot;</property></emphasis> for this purpose. + There are four possible strategies of exceeded queue&apos;s behavior: + </para> + <itemizedlist> + <listitem> + <para>&quot;dropNext&quot; drops next request that should be fired</para> + </listitem> + <listitem> + <para>&quot;dropNew&quot; drops the incoming request</para> + </listitem> + <listitem> + <para>&quot;fireNext&quot; immediately fires the next request in line to be fired</para> + </listitem> + <listitem> + <para>&quot;fireNew&quot; immediately fires the incoming request.</para> + </listitem> + </itemizedlist> + <para> <emphasis role="bold"> Example: </emphasis> </para> - <programlisting role="XML"><![CDATA[... -<h:form> + <programlisting role="XML"><![CDATA[<h:form> <a4j:queue size="2" requestDelay="500" sizeExceededBehavior="dropNext" onsizeexceeded="alert('The size of the queue is exceeded')" /> <h:inputText value="#{bean.a}"> <a4j:support event="onkeyup" /> @@ -112,10 +114,9 @@ <h:selectBooleanCheckbox value="#{bean.check}" id="checkboxID"> <a4j:support id="checkboxSupport" event="onchange" /> </h:selectBooleanCheckbox> -</h:form> -...]]></programlisting> +</h:form>]]></programlisting> <para> - In this example if the queue has more than 2 requests waiting to be processed the next event will be dropped and a message (the <emphasis><property>&quot;onsizeexceeded&quot;</property></emphasis> attribute fires a JavaScript function ) saying that the queues is exceeded will be displayed. + In this example if the queue has more than 2 requests waiting to be processed the next event will be dropped and a message (the <emphasis><property>&quot;onsizeexceeded&quot;</property></emphasis> attribute fires a JavaScript function) saying that the queues is exceeded will be displayed. </para> <para> @@ -127,35 +128,32 @@ <para> <emphasis role="bold"> Example: </emphasis> </para> - <programlisting role="XML"><![CDATA[... -<h:form> - <a4j:queue requestDelay="500" ignoreDupResponses="true" /> - <h:inputText value="#{bean.a}"> - <a4j:support event="onkeyup" /> - </h:inputText> -</h:form> -...]]></programlisting> + <programlisting role="XML"><![CDATA[<h:form> + <a4j:queue requestDelay="500" ignoreDupResponses="true" /> + <h:inputText value="#{bean.a}"> + <a4j:support event="onkeyup" /> + </h:inputText> +</h:form>]]></programlisting> <para>In this example, the requests are glued together and only the last one is submitted.</para> - <para>Another key attribute that easies server load is <emphasis><property - >&quot;timeout&quot;</property></emphasis>. - The attribute specifies the amount of time an item can be in the queue before the sent event is be aborted and dropped from the queue. - </para> - <para>If the request is sent and response is not returned within the - time frame defined in this attribute - the request is aborted, and the next one is sent. + <para> + Another key attribute that easies server load is <emphasis><property>&quot;timeout&quot;</property></emphasis>. + The attribute specifies the amount of time an item can be in the queue before the sent event is be aborted and dropped from the queue. </para> + + <para> + If the request is sent and response is not returned within the time frame defined in this attribute - the request is aborted, and the next one is sent. + </para> <para> <emphasis role="bold"> Example: </emphasis> </para> - <programlisting role="XML"><![CDATA[... -<h:form> - <a4j:queue timeout="1000" /> - <h:inputText value="#{bean.a}" > - <a4j:support event="onkeyup" /> - </h:inputText> -</h:form> -...]]></programlisting> + <programlisting role="XML"><![CDATA[<h:form> + <a4j:queue timeout="1000" /> + <h:inputText value="#{bean.a}"> + <a4j:support event="onkeyup" /> + </h:inputText> +</h:form>]]></programlisting> <para> In this case if the sever doesn&apos;t respond within a second the request will be aborted. @@ -164,28 +162,24 @@ <para> As you can see the implementation of the queue provides some custom event handlers that you may use to call JavaScript functions.</para> <para> - The <emphasis><property>&quot;oncomplete&quot;</property></emphasis>is fired after request completed. + The <emphasis><property>&quot;oncomplete&quot;</property></emphasis>is fired after request completed. + In this event handler request object is be passed as a parameter. + Thus queue is be accessible using <code>request.queue</code>. + And the element which was a source of the request is available using <code>this</code>. </para> + <para> - In this event handler request object is be passed as a parameter. - Thus queue is be accessible using <code>request.queue</code>. - And the element which was a source of the request is available using <code>this</code>. - - </para> - <para> <emphasis role="bold"> Example: </emphasis> </para> - <programlisting role="XML"><![CDATA[... -<h:form> - <a4j:queue oncomplete="alert(request.queue.getSize())" requestDelay="1000" /> - <h:inputText value="#{bean.a}"> - <a4j:support event="onkeyup" /> - </h:inputText> - <h:selectBooleanCheckbox value="#{bean.check}"> - <a4j:support event="onchange"/> - </h:selectBooleanCheckbox> -</h:form> -...]]></programlisting> + <programlisting role="XML"><![CDATA[<h:form> + <a4j:queue oncomplete="alert(request.queue.getSize())" requestDelay="1000" /> + <h:inputText value="#{bean.a}"> + <a4j:support event="onkeyup" /> + </h:inputText> + <h:selectBooleanCheckbox value="#{bean.check}"> + <a4j:support event="onchange"/> + </h:selectBooleanCheckbox> +</h:form>]]></programlisting> <para>In this example you can see how the number of requests waiting in the queue change. You will get a message with the number of the requests in the queue.</para> @@ -229,10 +223,12 @@ <section> <title>Relevant resources links</title> <para> - <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/queue.jsf?c... - >On the component LiveDemo page</ulink> you can see the example of <emphasis role="bold"> - <property>&lt;a4j:queue&gt;</property> - </emphasis> usage and sources for the given example. </para> - <para>General queue principals are documented in the &quot;<link linkend="QueuePrinciples">Queue Principles</link>&quot; section.</para> + Vizit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/queue.jsf?c... Page</ulink> at the RichFaces LiveDemo for examples of component usage and their sources. + </para> + + <para> + Useful articles: + </para> + <para>&quot;<link linkend="QueuePrinciples">Queue Principles</link>&quot; section of the RichFaces developer guide describes general Queue principles.</para> </section> </chapter>