<?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>

  <section>
    <title>Creating on a page</title>
    <programlisting role="XML"><![CDATA[<a4j:push reRender="msg" eventProducer="#{messageBean.addListener}" interval="3000"/>]]></programlisting>
  </section>

  <section>
    <title>Dynamical creation of a component from Java code</title>
    <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> implements reverse Ajax technique. The component makes requests 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. <emphasis role="bold">
      <property>&lt;a4j:push&gt;</property>
      </emphasis> registers <property>EventListener</property> in the bean,
      which receives messages about an event presence.</para>

    <para>The bean, for example, could be subscribed to Java Messaging Service (<ulink
        url="http://java.sun.com/products/jms/">JMS</ulink>) topic or it could be implemented as
      Message Driven Bean (MDB) in order to send a message to the <emphasis role="bold">
        <property>&lt;a4j:push&gt;</property>
      </emphasis> component about an event presence. In the presence of the event some action
      occurs.</para>

    <para>Thus, a work paradigm with the <emphasis role="bold">
        <property>&lt;a4j:push&gt;</property>
      </emphasis> component corresponds to an anisochronous model, but not to pools as for <emphasis
        role="bold">
        <property>&lt;a4j:poll&gt;</property>
      </emphasis> component. See the simplest example below:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="JAVA"><![CDATA[...
class MyPushEventListener implements PushEventListener {
    public void onEvent(EventObject evt) {
        System.out.println(evt.getSource());
            //Some action
    }
...
]]></programlisting>

    <para>Code for <property>EventListener</property> registration in the 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>A page code for this example is placed below.</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <a4j:status startText="in progress" stopText="done"/>
     <a4j:form>
        <a4j:region>
            <a4j:push reRender="msg" eventProducer="#{pushBean.addListener}" interval="2000"/>
        </a4j:region>
        <a4j:outputPanel id="msg" >
            <h:outputText value="#{pushBean.date}">
                <f:convertDateTime type="time"/>
            </h:outputText>
        </a4j:outputPanel>
        <a4j:commandButton value="Push!!" action="#{pushBean.push}" ajaxSingle="true"/>
    </a4j:form>
... 
]]></programlisting>

    <para>The example shows how date is updated on a page in compliance with data taken from a
      server. In the example <emphasis>
        <property>&quot;interval&quot;</property>
      </emphasis> attribute has value &quot;2000&quot;. This attribute defines an interval
      in milliseconds between 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 waiting time in milliseconds. If a 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.</para>

    <note><title>Note:</title> The form around the <emphasis role="bold">
        <property>&lt;a4j:push&gt;</property>
      </emphasis> component is required.</note>
  </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. 
	If a message exists, a complete request will be performed.
	The component doesn't poll registered beans but registers EventListener which receives messages about events.
	</para>	
<para>
	There are some attributes which allows to customize of the component behaviour:
</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'.>
</para>
<para>
Code for registration of listener:
</para>
    <programlisting role="JAVA"><![CDATA[
public void addListener(EventListener listener) {
synchronized (listener) {
	if (this.listener != listener) {
	this.listener = (PushEventListener) listener;
}
]]></programlisting>
   
<para>   
Component can get message using current code:
</para>
    <programlisting role="JAVA"><![CDATA[
System.out.println("event occurs");
synchronized (listener) {
	listener.onEvent(new EventObject(this));
}
]]></programlisting>
<para>
Thus, component 'push' uses asynchronous model instead of polls.
</para>
  </section-->

  <section>
    <title>Relevant resources links</title>
    <para>
      <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/push.jsf?c=push">Here </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>
