<?xml version="1.0" encoding="UTF-8"?>
<chapter>
          <chapterinfo>
                    <keywordset>
                              <keyword>a4j:keepAlive</keyword>
                    </keywordset>
          </chapterinfo>
          <table>
                    <title>Tag 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.components.KeepAlive</entry>
                                        </row>
                                        <row>
                                                  <entry>component-family</entry>
                                                  <entry>org.ajax4jsf.components.AjaxKeepAlive</entry>
                                        </row>
                                        <row>
                                                  <entry>component-class</entry>
                                                  <entry>org.ajax4jsf.components.AjaxKeepAlive</entry>
                                        </row>
                              </tbody>
                    </tgroup>
          </table>

          <section id="a4jkalpagetag" role="updated">
                    <title>Using the tag on a Page</title>

                    <para>To create the simplest variant on a page use the following syntax:</para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[<a4j:keepAlive beanName = "testBean"/>]]></programlisting>
                    <para>
                          Note, that to be put into the request scope the pointed bean should be registered inside <code>faces-config.xml</code> file and marked with <code>org.ajax4jsf.model.KeepAlive</code> annotation. 
                          A bean instance in the request scope could also be saved directly through the declaration of <code>@KeepAlive</code> annotation inside the bean.
                    </para>
                    <para>
                              
                    </para>
          </section>

          <!--  There's no AjaxKeepAlive component nor AjaxKeepAlive class and it cannot be created programmatically and there's no need for that.          
                    
                    <section>
                    <title>Creating the Component Dynamically Using Java</title>
                   <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.ajax.AjaxKeepAlive;
...
AjaxKeepAlive myKeepAlive = new AjaxKeepAlive();
...]]></programlisting>
          </section>
          -->

          <section>
                    <title>Details of usage</title>
                    <para>
                          If a managed bean is declared with <property>request</property> scope in the configuration file with the help of <emphasis role="bold"><property>&lt;managed-bean-scope&gt;</property></emphasis> tag then the life-time of this bean instance is valid only for the current request. Any attempts to make a reference to the bean instance after the request end will throw in Illegal Argument Exception by the server. 
                          To avoid these kinds of Exceptions component <emphasis role="bold"><property>&lt;a4j:keepAlive&gt;</property></emphasis> is used to maintain the state of the whole bean object among subsequent request.
                    </para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>

                    <programlisting role="XML"><![CDATA[<a4j:keepAlive beanName = "#{myClass.testBean}"/>]]></programlisting>

                    <para> The <emphasis><property>&quot;beanName&quot;</property></emphasis> attribute defines the request scope bean name you&apos;d like to re-use. Note that this attribute must point to a legal JSF EL expression which resolves to a managed mean instance.
                              For example for the above code the class definition may look like this one:
                    </para>
                <programlisting role="JAVA"><![CDATA[class MyClass{
	...
	private TestBean testBean;
	// Getters and Setters for testBean.
	...
}
]]></programlisting>
                    
                <para>
                      The <emphasis><property>&quot;ajaxOnly&quot;</property></emphasis> attribute declares whether the value of the bean should be available during a non-Ajax request. 
                      If the value of this attribute is &quot;true&quot; a request scope bean keeps the same value during Ajax requests from the given page. 
                      If a non-Ajax request is sent from this page the bean is re-created as a regular request scope bean.
                </para>
          </section>
      
          <section>
                    <title>Relevant resources links</title>
                <para>
                      Vizit <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/keepAlive.jsf?c=keepAlive">KeepAlive page</ulink> at RichFaces Livedemo for examples of component usage and their sources.
                </para>
                
                <para>
                      Search the <ulink url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&amp;f=261">RichFaces Users forum</ulink> for some additional information about usage of component.
                </para>
          </section>
</chapter>
