EJB container system properties

In addition to the specific EJB container settings that are accessible from the administrative console, you can set EJB system properties as Java virtual machine (JVM) custom properties.

You can use the JVM custom properties page to define the following EJB container system properties:

com.ibm.websphere.ejbcontainer.allowEarlyInsert

This property is applicable to container managed persistence (CMP) 1.1 beans only. By default, the EJB container creates the entity bean representation in the database only after the method, ejbPostCreate(...), is called.

Supported configurations: CMP beans are not supported in EJB 3.x modules.

Some applications might rely on method, ejbCreate(...), to have created the entity bean in the database. For such a requirement, setting the JVM property, com.ibm.websphere.ejbcontainer.allowEarlyInsert, to true overrides the default behavior.

com.ibm.websphere.ejbcontainer.blockWorkUntilAppStarted

This property allows the user to specify that incoming EJB requests be blocked until an application is fully started. This behavior is required by the EJB specification for applications with @Startup singleton beans, but for backward compatibility, this behavior is not the default for applications without a @Startup bean.

When this property is set to the value true, all incoming EJB requests, both local calls within the server process as well as remote calls from a client, will be blocked and have to wait until the application is fully started before proceeding. The duration of the block may be adjusted with the related property, com.ibm.websphere.ejbcontainer.blockWorkUntilAppStartedWaitTime. If the application has not started within the duration of the block wait time, then the request will be rejected with ApplicationNotStartedException. The default block duration for this related property is 120 seconds.

The setting of this property is applied to all EJB applications without a @Startup singleton bean in the server process, and the default value is false. Applications with an @Startup singleton bean will always block incoming work before the application is fully started, regardless of this property setting.

com.ibm.websphere.ejbcontainer.blockWorkUntilAppStartedWaitTime

This property allows the user to specify how long external requests should be blocked while an application is starting. If the application does not start in the specified duration, then requests will be rejected with ApplicationNotStartedException. External requests include both local calls within the server process as well as remote calls from a client. Local calls performed as part of application initialization are allowed; for example, calls from the @PostConstruct method of an @Startup singleton bean are allowed.

This property is applicable to all EJB applications containing @Startup singleton beans, and all other applications if the related property, com.ibm.websphere.ejbcontainer.blockWorkUntilAppStarted, is enabled (set to a value of true).

The value is specified for com.ibm.websphere.ejbcontainer.blockWorkUntilAppStartedWaitTime is in seconds. If the value is set to 0, then external requests will be immediately rejected until the application is fully started.

The property value setting can be any non-negative integer value (default 120).

com.ibm.websphere.ejbcontainer.checkEJBApplicationConfiguration

Specifies a server-wide setting that indicates the container should complete additional application configuration validation to ensure the application is consistent with the Java™ Platform, Enterprise Edition (Java EE) specification.

Supported configurations: You can also specify this property as an application custom property.

This property is intended for use during development of an application to assist in identifying improper configurations, which might result in unexpected behavior. For example, applying the javax.ejb.Asynchronous annotation to an interface is not supported by the specification and is typically ignored. When this property is enabled, an error is logged, and an exception occurs when the bean is processed. This failure is useful during development to understand why the methods are not working asynchronously.

Additional configuration validation is completed and might result in multiple configuration warnings and errors being logged when this property is enabled. Typically, this additional validation is for scenarios that incur extra overhead to run, which is unnecessary for stable applications on a production server. For minor deviations from the specification, only warnings are logged. For more significant issues, an error is logged, and the application cannot run until the error is corrected.

Avoid trouble: When the com.ibm.websphere.ejbcontainer.checkEJBApplicationConfiguration property is enabled, some of the issues that were reported as warnings are displayed as errors, which prevents the application from starting.

Supported configurations: The embeddable container and servers configured for development mode perform the additional validation that is associated with this property; however, all identified issues are reported as warnings, rather than errors, unless this property is specifically enabled.

com.ibm.websphere.ejbcontainer.declaredUncheckedAreSystemExceptions

This property enables you to indicate whether exceptions that are declared on the throws clause of an EJB method should are treated as application exceptions or as system runtime exceptions. When this property is set to true, these exceptions are treated like system runtime exceptions, and causes an EJBException to be issued on the client side.

If this property is not specified, or if this property is set to false, exceptions that are declared on the throws clause of an EJB method are treated as application exceptions.

The default value for this property is false.

com.ibm.websphere.ejbcontainer.defaultSessionAccessTimeout

This property enables you to specify the default session concurrency access timeout value for all session beans on a server. The value is specified in milliseconds.

Specify a Long data type value to disable or enable session concurrency:

A 0 value disables session concurrency (no wait).
A positive long value (1, 2, 3, and so on) enables session concurrency and sets the timeout value to the specified milliseconds.

If this property is set, the specified session bean concurrency access timeout is used server wide instead of the default value of -1 (wait forever). This applies to both stateful and singleton session beans. At the individual session bean level, the timeout can be overridden using the @AccessTimeout annotation on the bean class or method or using the access-timeout deployment descriptor element.

com.ibm.websphere.ejbcontainer.defaultStatefulSessionTimeout

Specifies a server-wide timeout for stateful session beans, which indicates how long a stateful session bean is retained by the server.

Supported configurations: The property applies only to EJB 3.1 modules and later.

This is a system property that you can add directly to the server.xml file or as a generic JVM argument using the administrative console.

The property is specified in minutes, the only valid unit. The default value is 10 minutes. A value of zero specifies that the server uses the default value of 10 minutes. A negative value is not valid. Any zero or greater value is valid. If a non-valid value is specified, a warning is issued to SystemOut, and the default value is used.

The stateful session bean timeout duration can be specified on a per-bean basis using annotations or xml. If a timeout duration is explicitly specified for a particular bean, this takes precedence over any server-wide timeout setting.

If no bean-specific timeout duration exists for a particular bean, then the server-wide timeout setting is applied to that bean.

If no bean-specific timeout duration exists for a particular bean, and no server-wide timeout setting exists, then the default timeout setting is applied to that bean.

com.ibm.websphere.ejbcontainer.EE5Compatibility

Specifies a server-wide setting that indicates the EJB container provides default behaviors that are consistent with the Java Enterprise Edition (Java EE) 5.0 specification.

This is a system property that you can add directly to the server.xml file or as a generic JVM argument using the administrative console.

The Java EE specification includes improvements to the EJB programming model that have resulted in minor changes to some default behaviors. In general, these changes provide more intuitive or more reliable behavior. However, if an application has been written to rely on one or more of the Java EE 5.0 behaviors, this system property might be set to revert the EJB container back to the Java EE 5.0 default behaviors.

Setting the property to true overrides the following behaviors:

@ApplicationException annotations are not inherited. Starting with the Java EE 6.0 specification, the default behavior for the @ApplicationException annotation was changed, indicating that the annotation is inherited by subclass exception classes. When this system property is specified, the @ApplicationException annotation is not inherited by subclass exception classes. Alternatively, you can change the @ApplicationException declaration to specify 'inherited=false'.
Concurrent access to stateful session beans is prohibited, and results in the exception, javax.ejb.ConcurrentAccessException. Starting with the Java EE 6.0 specification, the default behavior for stateful session concurrency was changed to allow concurrent access, though each concurrent request is serialized by the container, blocking access to the bean instance indefinitely until the instance lock may be obtained. When this system property is specified, all stateful session beans that do not have an explicit access-timeout value specified assume the default access-timeout value of 0 (the Java EE 5.0 default). Alternatively, you can modify the stateful session bean to define an access-timeout value of 0.
The Java type, Class, and any subclass of Enum are treated as resource environment references instead of simple environment entries. Starting with the Java EE 6.0 specification, the Java type, Class, and any subclass of Enum were added to the set of supported simple environment entry types. In prior versions of Java EE, these types would have been treated as resource environment references and a binding would have been required in the ibm-ejb-jar-bnd.xml file or ibm-web-bnd.xml file. Now that these data types are supported as simple environment entries, a platform-specific binding is no longer required. Instead, you can specify the value directly in the deployment descriptor. When this system property is specified, applications that use the javax.annotation.Resource annotation for the Java type, Class, or any subclass of Enum is treated as resource environment references, and the referenced value will be obtained using the binding file information. Installing the application is not effected by this property, and therefore, binding information is not entered during installation. Instead, you must manually enter the binding information in the binding file.

com.ibm.websphere.ejbcontainer.EE6Compatibility

Specifies a server-wide setting that indicates the EJB container provides default behaviors that are consistent with the Java Enterprise Edition (Java EE) 6.0 specification.

This is a system property that you can add directly to the server.xml file or as a generic JVM argument using the administrative console.

The Java EE specification includes improvements to the EJB programming model that have resulted in minor changes to some default behaviors. In general, these changes provide more intuitive or more reliable behavior. However, if an application has been written to rely on one or more of the Java EE 6.0 behaviors, this system property might be set to revert the EJB container back to the Java EE 6.0 default behaviors.

Setting the property to true prevents the @Local and @Remote annotations from being ignored even if they are specified with an empty value on the bean class and other business interfaces are specified. When the property is not specified and these annotations are specified on the bean class, the annotations cause the interfaces on the implements clause to be considered as local or remote business interfaces, unless:

The <business-local>, <business-remote>, or <local-bean> interfaces are specified in the ejb-jar.xml file.
The @LocalBean annotation is specified on the bean class.
The @Local or @Remote annotations with an empty value are specified on the interface classes on the implements clause.

When the property is specified, a single interface on the implements clause will still be considered as a local or remote business interface even if one of these designations has been used. Instead of setting the property, you can remove the @Local or @Remote annotation with an empty value and use one of the other options instead.

com.ibm.websphere.ejbcontainer.excludeRootExceptionOnRollback

By default, the EJB container will set the root cause of the exception that occurs during transaction rollback. If this property is set to true, the EJB container will not set the root cause. This is useful if your application does not expect to find a cause, or if your application logs exceptions and is now logging significantly more data.

com.ibm.websphere.ejbcontainer.extendSetRollbackOnlyBehaviorToInstanceFor

This property allows the user to specify application names in which they want to have the EJBs in their EJB 3.x modules demonstrate the pre-EJB 3.0 setRollbackOnly behavior.

The pre-EJB 3.0 setRollbackOnly behavior is described in Changing applications to WebSphere version specific setRollbackOnly behavior.

com.ibm.websphere.ejbcontainer.limitSetRollbackOnlyBehaviorToInstanceFor

This property allows the user to specify application names in which they want to have the EJBs in their EJB 3.x modules demonstrate the EJB 3.x setRollbackOnly behavior.

The EJB 3.x setRollbackOnly behavior is described in Changing applications to WebSphere version specific setRollbackOnly behavior.

com.ibm.websphere.ejbcontainer.poolSize

Specifies the size of the pool for the specified bean type. This property applies to stateless, message-driven, and entity beans. If you do not specify a default value, the container default value, 50 and 500, are used.

Set the pool size for a given entity bean as:

beantype=[H]min,[H]max[,timeout][:beantype=[H]min,[H]max...]

The beantype element is the Java EE name of the bean, formed by concatenating the application name, the # character, the module name, the # character, and the name of the bean, that is, the string assigned to the <ejb-name> field in the deployment descriptor of the bean. The min and max elements are the minimum and maximum pool sizes for that bean type. The optional timeout element is the wait time for the next available bean instance to become available when a hard limit is specified for the maximum pool size. Do not specify the brackets shown in the previous prototype; they denote the optional timeout value or optional additional bean types that you can specify after the first bean type. Each bean type specification is delimited by a colon (:).

Use an asterisk (*) as the value of beantype to indicate that all bean types are to use those values unless overridden by an exact bean-type specification somewhere else in the string; for example:

*=30,100

To specify a default value, omit either the min or max value but retain the comma (,) between the two values; for example:

Note: The following example displayed on multiple lines for publication purposes.

SMApp#PerfModule#TunerBean=54,
   :SMApp#SMModule#TypeBean=100,200

You can specify the bean types in any order within the string.

You can designate the maximum configured EJB pool size as a hard limit by inserting the character, H, directly in front of the max value. Without the H character, the maximum value indicates how many EJB instances can be pooled and does not limit the number of EJB instances that can be created or in use. Inserting the H character before the max value indicates a hard limit, and the EJB container blocks creation of more instances when that limit is reached. Further threads must wait until an instance becomes available or until the transaction times out. The default wait time is 300 seconds. After either the wait time expires or the transaction timeout is reached, the EJB container aborts the method call on the bean and returns either a javax.ejb.EJBException or a javax.transaction.TransactionRolledbackException.The wait time may also be configured by including the optional timeout value after the maximum configured hard limit and is specified in seconds.

You can designate the minimum configured EJB pool size as a hard limit by inserting the character, H, directly in front of the min value. Without the H character, the minimum value indicates how many EJB instances are maintained in the pool when the EJB type is not actively in use, but does not preload the pool when the application is started. Typically, the minimum pool size is not reached until the minimum number of EJB instances has been accessed concurrently by the application. Inserting the H character before the min value indicates a hard limit, and the EJB container preloads the pool with the minimum number of EJB instances when the application is started.

For example, if you want to indicate that no more than 200 EJB instances are created, and that additional requests must wait for an instance and might time out while waiting, then enter:

SMApp#SMModule#TypeBean=100,H200

If you want to indicate that the EJB container preloads the pool with a minimum of 100 EJB instances when the application is started, then enter:

SMApp#SMModule#TypeBean=H100,200

If you want to indicate that no more than 150 EJB instances are created, and that additional requests must wait for an instance for only 30 seconds before timing out, then enter:

SMApp#SMModule#TypeBean=50,H150,30

Supported configurations: The hard limit indicator is only available to EJB Version 2.0 or higher stateless session beans.