21.4. Configuring Session Beans

21.4.1. Session Bean Access Timeout

Stateful and Singleton Session Beans have an access timeout value specified for managing concurrent access. This value is the period of time that a request to a session bean method can be blocked before it will timeout.
The timeout value and the time unit used can be specified using the @javax.ejb.AccessTimeout annotation on the method. It can be specified on the session bean (which applies to all the bean's methods) and on specific methods to override the configuration for the bean.
If they are not specified JBoss EAP 6 supplies a default timeout value of 5000 milliseconds.
Refer to the Javadocs for AccessTimeout at http://docs.oracle.com/javaee/6/api/javax/ejb/AccessTimeout.html

21.4.2. Set Default Session Bean Access Timeout Values

JBoss Administrators can specify the default timeout values for Singleton and Stateful session beans. The default timeout values can be changed using the Management Console or the CLI. The default value is 5000 milliseconds.

Procedure 21.16. Set Default Session Bean Access Timeout Values using the Management Console

  1. Login to the Management Console. See Section 3.3.2, “Log in to the Management Console”.
  2. Click on the Configuration tab at the top of the screen. Expand the Container menu and select EJB 3. Select the Container tab.
  3. Click Edit. The fields in the Details area can now be edited.
  4. Enter the required values in the Stateful Access Timeout and/or Singleton Access Timeout text boxes.
  5. Click Save to finish.

Procedure 21.17. Set Session Bean Access Timeout Values Using the CLI

  1. Launch the CLI tool and connect to your server. Refer to Section 3.4.4, “Connect to a Managed Server Instance Using the Management CLI”.
  2. Use the write-attribute operation with the following syntax.
    /subsystem=ejb3:write-attribute(name="BEANTYPE", value=TIME)
    • Replace BEANTYPE with default-stateful-bean-access-timeout for Stateful Session Beans, or default-singleton-bean-access-timeout for Singleton Session Beans.
    • Replace TIME with the required timeout value.
  3. Use the read-resource operation to confirm the changes.
    /subsystem=ejb3:read-resource

Example 21.12. Setting the Default Stateful Bean Access Timeout value to 9000 with the CLI

[standalone@localhost:9999 /] /subsystem=ejb3:write-attribute(name="default-stateful-bean-access-timeout", value=9000)  
{"outcome" => "success"}

Example 21.13. XML Configuration Sample

<subsystem xmlns="urn:jboss:domain:ejb3:1.2">
   <session-bean>
      <stateless>
         <bean-instance-pool-ref pool-name="slsb-strict-max-pool"/>
      </stateless>
      <stateful default-access-timeout="5000" cache-ref="simple"/>
      <singleton default-access-timeout="5000"/>
   </session-bean>
   
</subsystem>

21.4.3. Session Bean Transaction Timeout

The TransactionTimeout annotation is used to specify the transaction timeout for a given method. The value of the annotation is the timeout used in the given unit element. It must be a positive integer or 0. Whenever 0 is specified, the default domain configured timeout is used.
The unit element specifies the measure of the value.

Note

Specifying a measure lesser than seconds is considered an error, even when the computed value will result in an integral number of seconds. For example: @TransactionTimeout(value = 1000, unit=TimeUnit.MILISECONDS)
Specifying Transaction Timeout in the Deployment Descriptor

The trans-timeout element is used to define the transaction timeout for business, home, component, and message listener interface methods; no interface view methods; web service endpoint methods; and timeout callback methods. The trans-timeout element resides in the urn:trans-timeout namespace and is part of the standard container-transaction element as defined in the jboss namespace.

Example 21.14. trans-timeout XML Configuration Sample

<ejb-name>*</ejb-name>
<tx:trans-timeout>
<tx:timeout>2</tx:timeout>
<tx:unit>Seconds</tx:unit>
</tx:trans-timeout>
ejb-name can be specified to a particular EJB name, or a wildcard (*). Specifying a wildcard (*) for the ejb-name means that this particular transaction timeout will be the default for all EJBs in the application.

21.4.4. Configure Stateful Session Bean Cache

In JBoss EAP 6, stateful EJB cache is configured in the ejb3 subsystem of the server configuration file. The following procedure describes how to configure stateful EJB cache and stateful timeout.

Procedure 21.18. Configure Stateful EJB Cache

  1. Find the <caches> element in the ejb3 subsystem of the server configuration file. Add a <cache> element. The following example creates a cache named "my=cache".
    <cache name="my-cache" passivation-store-ref="my-cache-file" aliases="my-custom-cache"/>
  2. Find the <passivation-stores> element in the ejb3 subsystem of the server configuration file. Create a <file-passivation-store> for the cache defined in the previous step.
    <file-passivation-store name="my-cache-file" idle-timeout="1260" idle-timeout-unit="SECONDS" max-size="200"/>
  3. The ejb3 subsystem configuration should now look like the following example.
    <subsystem xmlns="urn:jboss:domain:ejb3:1.4">
      ...
      <caches>
        <cache name="simple" aliases="NoPassivationCache"/>
        <cache name="passivating" passivation-store-ref="file" aliases="SimpleStatefulCache"/>  
        <cache name="clustered" passivation-store-ref="infinispan" aliases="StatefulTreeCache"/>  
        <cache name="my-cache" passivation-store-ref="my-cache-file" aliases="my-custom-cache"/>               
      </caches>
      <passivation-stores>
        <file-passivation-store name="file" idle-timeout="120" idle-timeout-unit="SECONDS" max-size="500"/>
        <cluster-passivation-store name="infinispan" cache-container="ejb"/>
        <file-passivation-store name="my-cache-file" idle-timeout="1260" idle-timeout-unit="SECONDS" max-size="200"/>
      </passivation-stores>
      ...
    </subsystem>
    The passivating cache, "my-cache", passivates stateful session beans to the file system as configured in the "my-cache-file" passivation store, which has the idle-timeout, idle-timeout-unit and max-size options.
  4. Create a jboss-ejb3.xml file in the EJB JAR META-INF/ directory. The following example configures the EJBs to use the cache defined in the previous steps.
    <jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
          xmlns="http://java.sun.com/xml/ns/javaee"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:c="urn:ejb-cache:1.0"
          xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
          version="3.1"
          impl-version="2.0">
      <assembly-descriptor>
        <c:cache>
          <ejb-name>*</ejb-name>
          <c:cache-ref>my-cache</c:cache-ref>
        </c:cache>
      </assembly-descriptor>
    </jboss:ejb-jar>
  5. To method to configure a timeout value depends on whether you are implementing EJB 2 or EJB 3.
    • EJB 3 introduced annotations, so you can specify the javax.ejb.StatefulTimeout annotation in the EJB code as follows.
      @StatefulTimeout(value = 1320, unit=java.util.concurrent.TimeUnit.SECONDS) 
      @Stateful
      @Remote(MyStatefulEJBRemote.class)
      public class MyStatefulEJB implements MyStatefulEJBRemote {
        ...
      }
      The @StatefulTimeout value can be set to one of the following.
      • A value of 0 means the bean is immediately eligible for removal.
      • A value greater than 0 indicates a timeout value in the units specified by the unit parameter. The default timeout unit is MINUTES. If you are using a passivating cache configuration and the idle-timeout value is less than the StatefulTimeout value, JBoss EAP will passivate the bean when it is idle for the idle-timeout period specified. The bean is then eligible for removal after the StatefulTimeout period specified.
      • A value of -1 means the bean will never be removed due to timeout. If you are using a passivating cache configuration and the bean is idle for idle-timeout, JBoss EAP will passivate the bean instance to the passivation-store.
      • Values less than -1 are not valid.
    • For both EJB 2 and EJB 3, you can configure the stateful timeout in the ejb-jar.xml file.
      <?xml version="1.0" encoding="UTF-8"?>
      <ejb-jar xmlns="http://java.sun.com/xml/ns/javaee"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
               version="3.1">
        <enterprise-beans>
          <session>
            <ejb-name>HelloBean</ejb-name>
              <session-type>Stateful</session-type>
              <stateful-timeout>
                <timeout>1320</timeout>
                <unit>Seconds</unit>
              </stateful-timeout>
          </session>
        </enterprise-beans>
      </ejb-jar>
    • For both EJB 2 and EJB 3, you can configure the stateful timeout in the jboss-ejb3.xml file.
      <jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
            xmlns="http://java.sun.com/xml/ns/javaee"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:c="urn:ejb-cache:1.0"
            xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
            version="3.1"
            impl-version="2.0">
        <enterprise-beans>
          <session>
            <ejb-name>HelloBean</ejb-name>
              <session-type>Stateful</session-type>
              <stateful-timeout>
                <timeout>1320</timeout>
                <unit>Seconds</unit>
              </stateful-timeout>
          </session>
        </enterprise-beans>
        <assembly-descriptor>
          <c:cache>
            <ejb-name>*</ejb-name>
            <c:cache-ref>my-cache</c:cache-ref>
          </c:cache>
        </assembly-descriptor>
      </jboss:ejb-jar>
Additional Information

  • To disable passivation of stateful session beans, do one of the following:
    • If you implement stateful session beans using EJB 3 annotations, you can disable the passivation of the stateful session bean the annotation @org.jboss.ejb3.annotation.Cache("NoPassivationCache")
    • If the stateful session bean is configured in the jboss-ejb3.xml file, set the <c:cache-ref> element value to "simple", which is the equivalent of NoPassivationCache.
      <c:cache-ref>simple</c:cache-ref>
  • EJB cache policy "LRUStatefulContextCachePolicy" has been changed in JBoss EAP 6 so it is impossible to have 1-to-1 configuration mapping in JBoss EAP 6.
  • In JBoss EAP 6, you can set up the following cache properties:
    • Bean life time is configured using the @StatefulTimeout in EJB 3.1.
    • Configure passivation of a bean to disk in the ejb3 subsystem of the server configuration file using the idle-timeout attribute of the <file-passivation-store> element.
    • Configure the maximum size of the passivation store in the ejb3 subsystem of the server configuration file using the max-size attribute of the <file-passivation-store> element.
  • In JBoss EAP 6, you can not configure the following cache properties:
    • The minimum and maximum numbers in memory cache.
    • The minimum numbers in passivation store.
    • The *-period configurations that control the frequency of cache operations.