Embeddable EJB container configuration properties
Use the following configuration properties for the embeddable EJB container.
EJB container configuration properties. Use the properties
Property Type Default value Description com.ibm.websphere.ejbcontainer.cacheSize java.lang.Long 2 053 Number of buckets for the EJB cache. com.ibm.websphere.ejbcontainer.cacheSweepInterval java.lang.Long 3 000 Time between sweeps of the EJB cache to determine whether to remove entries. com.ibm.websphere.ejbcontainer.inactivePoolCleanupInterval java.lang.Long 30 000 Time in milliseconds for the clean up thread to wait before cleaning the inactive pool. com.ibm.websphere.ejbcontainer.passivationDir java.lang.String <TempDir> Directory to passivate stateful beans in. The user must have read and write access to the specified directory. com.ibm.websphere.embeddable.configFileName java.lang.String <CurrentWorkingDirectory> /embeddable.properties File name of a properties file containing embeddable EJB container properties. When this file is processed, each property is passed to the newly created EJB container as if they were passed in programmatically. Any properties in the configuration file are overridden by properties passed in programmatically. It is also possible to specify this property as a system property on the command line.
The following table contains configuration properties for data sources. Each property is specific to an individual data source which allows us to configure multiple data sources with different settings. Replace <data_source_id> with a unique term identifying data source to be configured. Some properties are listed as required for each data source.
properties for JDBC data sources. Use the embeddable
Property Type Description DataSource.<data_source_id>.name java.lang.String Required. The JNDI string that the container uses to bind this data source in the global namespace of the embeddable container. This string must match the JNDI lookup string used in the application. DataSource<data_source_id>.className java.lang.String Required. The Java class name of the data source class. For testing, Apache Derby can be used if app_server_root/derby/lib/derby.jar is on the Java Virtual Machine classpath. The supported data source classes for Apache Derby are org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource and org.apache.derby.jdbc.EmbeddedXADataSource. DataSource.<data_source_id>.connectionSharing java.lang.String The policy for sharing connections. Valid values are MatchOriginalRequest (default), MatchCurrentState or None. MatchOriginalRequest means that a connection request might share if it matches the originally requested settings of an existing connection. MatchCurrentState means that a connection request might share if it matches the current settings of an existing connection. None means that multiple connection requests do not share the same connection. DataSource.<data_source_id>.databaseName java.lang.String The name of the database that this data source connects to. DataSource.<data_source_id>.isolationLevel java.lang.Integer The transaction isolation level for connections from this data source. If unspecified, the default is provided by the JDBC driver or database. Valid values are 1 for Read Uncommitted, 2 for Read Committed, 4 for Repeatable Read, or 8 for Serializable. These values come from constants in java.sql.Connection and are subject to change.
DataSource.<data_source_id>.maxIdleTime java.lang.Integer The number of seconds after which the connection pool can close an unused connection. DataSource.<data_source_id>.maxPoolSize java.lang.Integer The maximum number of connections created for this data source. After this number of simultaneous connections are in use, future requests to get a connection from this data source are blocked until one or more of the in-use connections have been returned to the pool. DataSource.<data_source_id>.maxStatements java.lang.Integer The maximum number of statements cached by the connection pool. This value is divided by the maxPoolSize value to determine the number of statements that can be cached for each connection in the pool. A value of 0 disables statement caching. DataSource.<data_source_id>.minPoolSize java.lang.Integer The minimum number of connections to keep in the connection pool for this data source. If no connections are in use, the connection pool might discard connections until the pool size reaches this setting. This setting must be non-negative. DataSource.<data_source_id>.password java.lang.String Password for the given user when accessing the database. Like the preceding property, this property can be omitted if the database does not have security enabled or if the user name and password are provided programmatically when creating the connection. DataSource.<data_source_id>.transactional java.lang.Boolean Whether this data source must be enlisted in Java Transaction API (JTA) transactions. Valid values are true (default) or false. DataSource.<data_source_id>.user java.lang.String User name for accessing the database. This property can be omitted if the database does not have security enabled or if the user name and password are provided programmatically when creating the connection. DataSource.<data_source_id>.<vendor_property_name _or_connection_pool_property_name> java.lang.String We can also configure other properties:
- Vendor-specific data source properties, such as serverName and portNumber
- WebSphere Application Server data source properties, such as userDefinedErrorMap and validateNewConnection
- WebSphere Application Server connection pooling properties, such as connectionTimeout and purgePolicy
DataSource.<data_source_id>.xaRecoveryPassword java.lang.String Applies to XA data sources only. Password for XA recovery. DataSource.<data_source_id>.xaRecoveryUser java.lang.String Applies to XA data sources only. Some databases require a user with special privileges for XA recovery. Specify a user name for XA recovery instead of the default user. Use the following properties to configure two data sources.
DataSource.ds1.name=env/jdbc/ds1 DataSource.ds1.className=org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource DataSource.ds1.transactional=true DataSource.ds1.createDatabase=create DataSource.ds1.databaseName=jtest1 DataSource.ds1.user=dbuser1 DataSource.ds1.password=dbpwd1 DataSource.ds1.maxPoolSize=5 DataSource.ds2.name=env/jdbc/ds2 DataSource.ds2.className=org.apache.derby.jdbc.EmbeddedXADataSource DataSource.ds2.connectionSharing=MatchOriginalRequest DataSource.ds2.createDatabase=create DataSource.ds2.databaseName=jtest2 DataSource.ds2.user=dbuser2 DataSource.ds2.password=dbpwd2 DataSource.ds2.maxPoolSize=10 DataSource.ds2.minPoolSize=1 DataSource.ds3.name=env/jdbc/ds3 DataSource.ds3.className=com.ibm.db2.jcc.DB2XADataSource DataSource.ds3.driverType=4 DataSource.ds3.databaseName=DB2COPY1 DataSource.ds3.serverName=mydb2.test.ibm.com DataSource.ds3.portName=50000 DataSource.ds3.user=dbuser1 DataSource.ds3.password=dbpwd1The first data source, ds1, is bound in the namespace under the name, env/jdbc/ds1, and provides connection pooling for up to five connections to an Apache Derby database. The second data source, ds2, is bound in the namespace at env/jdbc/ds2 and provides XA-compliant connection pooling to an Apache Derby database.
The following table contains configuration properties for EJB bindings. For each property, replace:
- <app> with the application name.
The application name is, by default, the empty string. However the application name can be specified using the EJBContainer.APP_NAME property when calling createEJBContainer.
- <module> with the module name.
The module name is either specified in ejb-jar.xml as <module-name>, is the name of the JAR file without the ".jar" suffix, or is the name of the directory containing the module.
- <ejb> with the name of the EJB.
The name of the EJB is specified in ejb-jar.xml as <ejb-name>, or using the name element when using annotations; for example, @Stateless(name="TestBean"). If no name is specified in the EJB annotation, the simple class name is used; for example, TestBean for the class com.ibm.test.TestBean.
- <interceptor> with the name of an interceptor class.
- <ref> with the name of the resource reference, EJB reference, or environment entry.
The reference can be specified in ejb-jar.xml; for example, <res-ref-name>jdbc/mydsref</res-ref-name>, or <ejb-ref-name>java:module/env/myejbref</ejb-ref-name>. Alternatively, the reference can be specified using an annotation; for example @Resource(name="jdbc/mydsref") or @EJB(name="java:module/env/myenvref").
If an application name is not specified when launching the embeddable container, the <app> must be omitted. However, use the # delimiter. For example, Bean.#<module>#<bean>.ResourceRef.BindingName.
EJB container configuration properties for reference bindings. Use the embeddable EJB container configuration properties for
Property Type Description Bean.<app>#<module>#<ejb>.ResourceRef.BindingName.<ref> or Interceptor.<app>#<module>#<interceptor>.ResourceRef.BindingName.<ref> java.lang.String The JNDI string to use when the resource reference is looked up or injected. This must be the JNDI name of a configured data source. Bean.<app>#<module>#<ejb>.EJBRef.BindingName.<ref-name> or Interceptor.<app>#<module>#<interceptor>.EJBRef.BindingName.<ref> java.lang.String The JNDI string to use when the EJB reference is looked up or injected. This must be the java:global, java:app, or java:module JNDI string of an EJB in the embeddable EJB container. Bean.<app>#<module>#<ejb>.EnvEntry.Value.<ref-name> or Interceptor.<app>#<module>#<interceptor>.EnvEntry.Value.<ref> java.lang.String The value to use when the environment entry is looked up or injected. This property overrides the value specified by env-entry-value. The value must be valid for the type of the environment entry. Bean.<app>#<module>#<ejb>.EnvEntry.BindingName.<ref> or Interceptor.<app>#<module>#<interceptor>.EnvEntry.BindingName.<ref> java.lang.String The JNDI string to use when the environment entry is looked up or injected. This must be the java:global, java:app, or java:module JNDI string of another environment entry in the same embeddable EJB container. Bean.<app>#<module>#<ejb>.DataSource.BindingName.<ref> or Interceptor.<app>#<module>#<interceptor>.DataSource.BindingName.<ref> java.lang.String The JNDI string to use when the data source is looked up or injected. This must either be the JNDI name of a configured data source or the java:global, java:app, or java:module JNDI string of another data source in the same embeddable EJB container. Application developers should use resource references rather than looking up a data source directly. If an application is coded to look up data sources directly, we can use this property to override data source definitions included in the application. See the information center for more information about data source definitions. Use the following properties to configure the bindings for an EJB with two references and an interceptor with an environment entry:
Bean.#TestModule#TestBean.ResourceRef.BindingName.jdbc/dsref=env/jdbc/ds1 Bean.#TestModule#TestBean.EJBRef.BindingName.ejb/Cart=java:global/CartModule/CartBean Interceptor.#TestModule#com.ibm.example.LoggerInterceptor.EnvEntry.Value.logFile=/tmp/output.log
Avoid trouble: Use the following properties to override java:module/env/TestDataSource defined in an EJB named TestBean in an EJB module named TestModule, with jdbc/MyDataSource defined in embeddable properties:
Bean.#TestModule#TestBean.DataSource.BindingName.java\:module/env/TestDataSource=jdbc/MyDataSource
gotcha
for security. Use the embeddable EJB container configuration
Property Type Default value Description com.ibm.websphere.securityEnabled java.lang.String false Determines whether security roles are checked. Valid values are false (default) or true. If true, then security roles are checked; if false, then security roles are not checked. role.<role_name> java.lang.String
Maps an EJB role to one or more users. The <role_name> is a role assigned to a method, either through the annotation @RolesAllowed or through the deployment descriptor <method-permission>. The value is a string of comma-delimited user names, for example "bob, mary, john". The users in the list are allowed to run methods that require the <role_name>. role.runAs.<role_name> java.lang.String
Maps one EJB role to one user. The <role_name> is a role assigned to a bean or method, either through the annotation @RunAs or through the deployment descriptor <run-as>. The value is a single user name. The user name is used for any authorization required by the bean while it is running. user.invocation java.lang.String
Defines the user that might be used for authorization when the bean is invoked. The value is a single user name. The container checks that this user is mapped to a role allowed to run any executed method. The following table contains configuration properties for the Local Transaction Containment (LTC) behavior. For an explanation of LTC, read about local transaction containment. Each property is specific to a bean.
If an application name is not specified when launching the embeddable container, the <application_name> must be omitted. However, use the # delimiter. For example, Bean.#<module_name>#<bean_name>LocalTransaction.Resolver.
Transaction Containment. Use the embeddable EJB container
Property Type Default value Description Bean.<application_name>#<module_name>#<bean_name>.LocalTransaction.Resolver java.lang.String Application Determines the entity that is responsible for local transaction resolution. Valid values are Application (default) or ContainerAtBoundary. Bean.<application_name>#<module_name>#<bean_name>.LocalTransaction.UnresolvedAction java.lang.String Rollback Determines the action taken for unresolved local transactions. Valid values are Rollback (default) or Commit. The following table contains configuration properties for XA behavior.
Property Type Default value Description com.ibm.websphere.tx.acceptHeuristicHazard java.lang.String false Whether last participant support is enabled for all modules. The default value is false. com.ibm.websphere.tx.auditRecovery java.lang.String true Whether recovery processing outputs audit messages, which indicate XA resource and XID processing during recovery. When no audit recovery is specified, only a single recovery message is output along with the number of transactions that are recovered, unless an error occurs. com.ibm.websphere.tx.clientInactivityTimeout java.lang.String 0 Maximum duration, in seconds, between transactional requests. Any period of client inactivity that exceeds this timeout value results in the transaction being rolled back. The default setting, 0, means that no limit exists. com.ibm.websphere.tx.enableLoggingForHeuristicReporting java.lang.String false Enable logging for heuristic reporting. If last participant support is enabled, reporting of heuristic outcomes that might occur when the server becomes unavailable requires additional information to be written to the transaction log. If enabled, one additional log write is completed for any transaction that involves both one-phase and two-phase commit resources. No additional records are written for transactions that do not involve a one-phase commit resource. com.ibm.websphere.tx.heuristicRetryLimit java.lang.String 0 Number of times that the transaction service retries a completion signal such as commit or rollback. Retries occur after a transient exception from a resource manager. The default value, 0, indicates no limit to the number of retries. com.ibm.websphere.tx.heuristicRetryWait java.lang.String 0 Number of seconds that the transaction service waits before retrying a completion signal, such as commit or rollback, after a transient exception from a resource manager. com.ibm.websphere.tx.LPSHeuristicCompletion java.lang.String ROLLBACK (case insensitive)
The heuristic completion action to be taken by the transaction service in a transaction with last participant support when the outcome of the one-phase commit resource is unknown. The values ROLLBACK or COMMIT cause the two-phase commit resources to be completed accordingly. The setting, MANUAL, means that the transaction service takes no action and leave the two-phase commit resources in-doubt. The default value is ROLLBACK. com.ibm.websphere.tx.maximumTransactionTimeout java.lang.String 300 Specifies, in seconds, the upper limit of the transaction timeout value. This timeout value constrains the upper limit of all other transaction timeout values. com.ibm.websphere.tx.totalTranLifetimeTimeout java.lang.String 120 Default maximum time, in seconds, allowed for a transaction before the transaction service initiates timeout. Any transaction that does not begin completion processing before this timeout occurs is rolled back. com.ibm.websphere.tx.tranLogDirectory java.lang.String profiles\server name\tranlog Name of a directory for this server where the transaction service stores log files for recovery. com.ibm.websphere.tx.tranLogSize java.lang.String 1024 Size, in kilobytes, of transaction log files. The minimum file size is 64KB. The default value sets the file size to 1MB.
Local transaction containment