<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" xml:lang="en" xml:id="ejb.entity.tuning"><info><title>Tuning EJB 2.1 entity beans</title></info>
  

    <para>
      JOnAS must make a compromise between scalability and performance. For that reason, several tags in the JOnAS-specific deployment descriptor have been introduced. For most applications, there is no need to change the default values for all these tags. See 
      <code>
      $JONAS_ROOT/xml/jonas-ejb-jar_4_7.xsd
      </code>
      for a complete description of the JOnAS-specific deployment descriptor.  
	</para>
    <para>
      Note that if several of these elements are used, they should appear in the following order within the &lt;jonas-entity&gt; element:
    <orderedlist>
      <listitem><para>
        is-modified-method-name
      </para></listitem>
      <listitem><para>
        passivation-timeout
      </para></listitem>
      <listitem><para>
        read-timeout
      </para></listitem>
      <listitem><para>
        max-wait-time
      </para></listitem>
      <listitem><para>
        inactivity-timeout
      </para></listitem>
      <listitem><para>
        deadlock-timeout
      </para></listitem>
      <listitem><para>
        shared
      </para></listitem>
      <listitem><para>
        prefetch
      </para></listitem>
      <listitem><para>
        hard-limit
      </para></listitem>
      <listitem><para>
        max-cache-size
      </para></listitem>
      <listitem><para>
        min-pool-size
      </para></listitem>
      <listitem><para>
        cleanup
      </para></listitem>
      <listitem><para>
        lock-policy
      </para></listitem>
    </orderedlist>
    </para>
    <section><info><title>lock-policy</title></info>
      <para>
       The JOnAS ejb container is able to manage seven different lock-policies: </para>
      <variablelist>
        <varlistentry><term>
          container-serialized (default)
        </term>
        <listitem><para>
          The container ensures the     transaction serialization. This policy is suitable for entity beans     having non transacted methods that can modify the bean state.     It works only if the bean is accessed from 1 jonas server (shared =     false).
        </para></listitem></varlistentry>
        <varlistentry><term>
          container-serialized-transacted
        </term>
        <listitem><para>
          The container ensures the     transaction serialization. This policy is suitable for most entity beans.
        </para></listitem></varlistentry>
        <varlistentry><term>
          container-read-committed
        </term>
        <listitem><para>
          This policy is similar to     container-serialized-transacted, except that accesses outside transaction do not     interfere with transactional accesses. This can help to avoid deadlocks in     certain cases, when accessing a bean concurrently with and without a     transactional context. The only drawback of this policy is that it     consumes more memory (2 instances instead of 1).
        </para></listitem></varlistentry>
        <varlistentry><term>
          container-read-uncommitted (deprecated)
        </term>
        <listitem><para>
          All methods share the same     instance (like container-serialized), but there is no synchronization.     For example, this policy is of interest for read-only entity beans, or if     the bean instances are very rarely modified. It will fail if two or more     threads try to modify the same instance concurrently.     This policy is deprecated because it can be replaced by 
          <literal>
            container-read-write
          </literal>
          .
        </para></listitem></varlistentry>
        <varlistentry><term>
          database
        </term>
        <listitem><para>
          Allow the database to handle the transaction isolation.     With this policy, it is possible to choose the transaction isolation in a     database. This may be of interest for applications that heavily use     transactional read-only operations, or when the flag shared is needed. It     does not work with all databases and is not memory efficient.
        </para></listitem></varlistentry>
        <varlistentry><term>
          read-only
        </term>
        <listitem><para>
          The bean state is never written to the database.   If the bean is 
          <literal>
            shared
          </literal>
          , the bean state is read from the database regularly.   Use the 
          <literal>
            read-timeout
          </literal>
           tag to specify the timeout value.
        </para></listitem></varlistentry>
        <varlistentry><term>
          container-read-write
        </term>
        <listitem><para>
          All methods share the same     instance (like container-serialized). A synchronization is done only when     the instance is modified. No lock is taken while the instance is read only.     This policy does not work if the bean is 
          <literal>
            shared
          </literal>
          , nor does it work for CMP 1.x beans.
        </para></listitem></varlistentry>
      </variablelist>
      <para>
        Important: If CMP1 beans are deployed, only the following policies should be used: 
        <itemizedlist>
          <listitem><para>
            container-serialized
          </para></listitem>
          <listitem><para>
            container-serialized-transacted
          </para></listitem>
          <listitem><para>
            read-only
          </para></listitem>
          <listitem><para>
            container-read-committed
          </para></listitem>
          <listitem><para>
            database, but only with shared=true.
          </para></listitem>
        </itemizedlist>
      </para>
    </section>
    <section><info><title>shared</title></info>
      <para>
       This flag will be defined as 
      <literal>
        true
      </literal>
       if the bean persistent state can be accessed outside the JOnAS Server. When this flag is 
      <literal>
        false
      </literal>
      , the JOnAS Server can do some optimization, such as not re-reading the bean state before starting a new transaction. The default value depends on the lock-policy: </para>
      <itemizedlist>
        <listitem><para>
          <literal>
            false
          </literal>
           for 
          <literal>
            container-serialized
          </literal>
          , 
          <literal>
            container-read-uncommitted
          </literal>
           or 
          <literal>
            container-read-write
          </literal>
          . For these 3 policies, shared=false is mandatory.
        </para></listitem>
        <listitem><para>
          <literal>
            true
          </literal>
           in the other cases.
        </para></listitem>
      </itemizedlist>
       <para>
       Lock policy 
      <literal>
        database
      </literal>
       works only if shared=true.   </para>
    </section>
    <section><info><title>prefetch</title></info>
      <para>
       This is a CMP2-specific option. The default is false. This can be set to true if it is desirable to have a cache managed after finder methods execution, in order to optimize further accesses inside the same transaction. </para> 
      <para>
        Important note:
      </para>
      <itemizedlist>
        <listitem><para>
          The prefetch will not be used for methods that have no transactional     context.
        </para></listitem>
        <listitem><para>
          It is impossible to set the prefetch option if the lock policy is     container-read-uncommitted.
        </para></listitem>
      </itemizedlist>
    </section>
    <section><info><title>max-cache-size / hard-limit / max-wait-time</title></info>
      <para>
       This optional integer value represents the maximum number of instances in memory. The purpose of this value is to keep JOnAS scalable. The default value is "no limit". To save memory, this value should be set very low if it is known that instances will not be reused. Depending on whether 
      <literal>
        hard-limit
      </literal>
       value is 
      <literal>
        true
      </literal>
       or 
      <literal>
        false
      </literal>
      , this 
      <literal>
        max-cache-size
      </literal>
       value will be overtaken or not: In the case of 
      <literal>
        hard-limit
      </literal>
       = 
      <literal>
        true
      </literal>
      , the container will never allocate more instances than the 
      <literal>
        max-cache-size
      </literal>
       value. When the limit is reached, the thread will be set to waiting until instances are released. It is possible to specify the maximum time to wait for an instance with the tag 
      <literal>
        max-wait-time
      </literal>
      . The default is 0, which means "no wait".  </para>
    </section>
    <section><info><title>min-pool-size</title></info>
      <para>
       This optional integer value represents the number of instances that will be created in the pool when the bean is loaded. This will improve bean instance create time, at least for the first instances. The default value is 0. When passivation occurs, for example if there are too many instances in memory, instances are released and placed in the pool only if min-pool-size is not reached. The intent is to try to keep at least min-pool-size instances in the pool of available instances.  </para>
    </section>
    <section><info><title>is-modified-method-name</title></info>
      <para>
       To improve performance of CMP 1.1 entity beans, JOnAS implements the isModified extension. Before performing an update, the container calls a method of the bean whose name is identified in the 
      <literal>
        is-modified-method-name
      </literal>
       element of the JOnAS-specific deployment descriptor. This method is responsible for determining if the state of the bean has been changed. By doing this, the container determines if it must store data in the database or not.</para>  
      <note><para>
        This is useless with CMP2 entity beans, since this will be done automatically by the container.
      </para></note>
      <section><info><title>Example</title></info>
        
        <para>
          The bean implementation manages a boolean 
          <literal>
            isDirty
          </literal>
           and implements a method that returns the value of this boolean: 
          <literal>
            isModified
          </literal>
        </para>
        <screen>
    private transient boolean isDirty;
    public boolean isModified() {
        return isDirty;
    }
            </screen>
        <para>
          The JOnAS-specific deployment descriptor directs the bean to implement an 
          <literal>
            isModified
          </literal>
           method:
        </para>
        <screen>

    &lt;jonas-entity&gt;
      &lt;ejb-name&gt;Item&lt;/ejb-name&gt;
      &lt;is-modified-method-name&gt;isModified&lt;/is-modified-method-name&gt;
      .....
    &lt;/jonas-entity&gt;
            </screen>
        <para>
          Methods that modify the value of the bean must set the flag 
          <literal>
            isDirty
          </literal>
           to 
          <literal>
            true
          </literal>
          . 
           Methods that restore the value of the bean from the database must reset the flag 
          <literal>
            isDirty
          </literal>
           to 
          <literal>
            false
          </literal>
          . Therefore, the flag must be set to 
          <literal>
            false
          </literal>
           in the 
          <literal>
            ejbLoad()
          </literal>
           and 
          <literal>
            ejbStore()
          </literal>
           methods.
        </para>
      </section>
    </section>
    <section><info><title>passivation-timeout</title></info>
      <para>
       This flag is used only when lock-policy = container-serialized. When instances are accessed outside of any transaction, their state is kept in memory to improve performance. However, a passivation will occur in three situations:</para> 
      <orderedlist>
        <listitem><para>
          When the bean is unloaded from the server, at least when the server     is stopped.
        </para></listitem>
        <listitem><para>
          When a transaction is started on this instance.
        </para></listitem>
        <listitem><para>
          After a configurable timeout: passivation-timeout. If the bean is always accessed with no     transaction, it may be prudent to periodically store the bean state on     disk.
        </para></listitem>
      </orderedlist>
       <para>
       This passivation timeout can be configured in the JOnAS-specific deployment descriptor, with the non-mandatory tag &lt;passivation-timeout&gt;. </para>
      <para>Example: </para>
      <screen>
    &lt;jonas-entity&gt;
      &lt;ejb-name&gt;Item&lt;/ejb-name&gt;
      &lt;passivation-timeout&gt;5&lt;/passivation-timeout&gt;
      .....
    &lt;/jonas-entity&gt;
          </screen>
       <para>
       This entity bean will be passivated every five second, if not accessed within transactions.   
       </para>
    </section>
    <section><info><title>read-timeout</title></info>
      <para>
       This flag is used only when lock-policy = read-only. In case shared=true has been set, it is important to synchronize the bean state by reading it periodically from the storage. This is configurable with the read-timeout flag. Value is in seconds.  </para>
    </section>
    <section><info><title>inactivity-timeout</title></info>
      <para>
       Bean passivation sends the state of the bean to persistent storage and removes from memory only the bean instance objects that are holding this state. All container objects handling bean access (remote object, interceptors, ...) are kept in memory so that future access will work, requiring only a reload operation (getting the state). It may be advantageous to conserve more memory and completely remove the bean instance from memory; this can be achieved through the &lt;inactivity-timeout&gt; element. This element is used to save memory when a bean has not been used for a long period of time. If the bean has not been used after the specified time (in seconds), all its container objects are removed from the server. If a client has kept a reference on a remote object and tries to use it, then the client will receive an exception.  </para>
    </section>
  </section>