@ejbgen:message-driven Annotation

This tag defines the class-scope properties of a message-driven bean.

Scope

Class tag on a message-driven bean.

Syntax

@ejbgen:message-driven

destination-jndi-name="JNDIName"

destination-type="javax.jms.Queue/javax.jms.Topic"

ejb-name="NameMessageDrivenBean"

[acknowledge-mode="auto-acknowledge/dups-ok-acknowledge"]

[clients-on-same-server="True/False"]

[create-as-principal-name="PrincipalName"]

[default-transaction="DefaultTransactionOption"]

[durable="True/False"]

[initial-beans-in-free-pool="InitialNumber"]

[max-beans-in-free-pool="MaxNumber"]

[message-selector="JMSSelector"]

[passivate-as-principal-name="PrincipalName"]

[remove-as-principal-name="PrincipalName"]

[run-as="RoleName"]

[run-as-identity-principal="PrincipalName"]

[trans-timeout-seconds="Seconds"]

[transaction-type="Bean/Container"]

[use-caller-identity="True/False"

Attributes

destination-jndi-name

Required. Specifies the JNDI name of the destination from which the message-driven bean receives messages.

destination-type

Required. Specifies the destination type from which the message-driven bean receives messages. Valid values are javax.jms.Queue and javax.jms.Topic.

ejb-name

Required. Specifies the (descriptive) name of the message-driven bean. When you create a new message-driven bean with the file name <name>Bean.ejb or <name>.ejb, the ejb-name will be <name> by default.

acknowledge-mode

Optional. Specifies the acknowledgement mode of the message-driven bean. Valid values are auto-acknowledge and dups-ok-acknowledge. When not specified, the default is auto-acknowledge. The auto-acknowledge setting tells the EJB container that an acknowledgement must be sent to the JMS provider when an instance of this message-driven bean has received the message. The dups-ok-acknowledge setting allows for a delay of acknowledgement. The latter setting should only be used when duplicate messages can be processed correctly.

The acknowledge-mode attribute setting is important when the transaction-type attribute is set to Bean (reflecting bean-managed transactions), or when the the transaction-type is set to Container and the default-transaction attribute is set to NotSupported. In all other cases this setting is ignored.

clients-on-same-server

Optional. Specifies whether all clients are co-located with the session bean on the same server. Valid values are true and false. When this attribute is left unspecified, its defaults to false. If set to True, the server instance will not multicast JNDI announcements for the EJB when it is deployed, that is, it turns off JNDI replication so that the EJB's JNDI name is only bound to the local server, hence reducing the startup time for large clusters.

create-as-principal-name

Optional. Specifies the name of the principal to be used when running the bean's ejbCreate method. For more information, see Role-Based Security.

default-transaction

Optional. Specifies the default transaction attribute to be applied to all methods that do not have a transaction attribute setting. Valid values are NotSupported and Required. When the attribute is left unspecified, it defaults to NotSupported, assuming container-managed transaction. When the transaction-type is set to Bean, the default-transaction attributed is ignored. When set to Required (assuming container-manager transactions), the acknowledge-mode attribute is ignored. For more information on transactions and message-driven beans, see EJBs and Transactions.

durable

Optional. Specifies whether the bean's subscription to a javax.jms.Topic (as specified by the destination-type) is durable, that is, can outlast the EJB container's connection to the JMS provider. Valid values are true and false. When left unspecified, the default is true. This attribute is not relevant for queues.

initial-beans-in-free-pool

Optional. Specifies the initial number of beans in the free pool. If not specified, the default is computed using the formula min(number of threads in the execute queue * .5) + 1, max-beans-in-free-pool). To learn more about execute queues, see the WebLogic Server documentation at http://www.oracle.com/technology/documentation/index.html.

max-beans-in-free-pool

Optional. Specifies the maximum number of beans in the free pool. When left unspecified, the default is 1000. If 0 is specified, there is no maximum.

message-selector

Optional. Specifies a message selector for this message-driven bean to be more selective about the messages it receives. For more information, see the Message-Driven Bean Sample.

passivate-as-principal-name

Optional. Specifies the name of the principal to be used when running the bean's ejbPassivate method.

remove-as-principal-name

Optional. Specifies the name of the principal to be used when running the bean's ejbRemove method.

run-as

Optional. Specifies the EJB-scoped security role this bean should run under. To use this attribute, use-caller-identity must be False. Also make sure that the security role is defined using the @ejbgen:role-mapping Annotation. For more information, see Role-Based Security.

run-as-identity-principal

Optional. Specifies the name of the principal to run as in case the security role specified with the run-as attribute maps to several principals. To specify this attribute you must also specify the run-as attribute. You must specify the run-as-identity-principal attribute when the run-as security role is externally defined. For more information, see Role-Based Security.

trans-timeout-seconds

Optional. Specifies the transaction timeout (in seconds). If not specified, this attribute defaults to 30 seconds.

transaction-type

Optional. Specifies who manages the transactions for this EJB. Default values are Bean and Container. When left unspecified, the default is Container, meaning that the message-driven bean executes within its own transaction context. The setting of this attribute affect the default-transaction and acknowledge-mode attributes. For more information, see above. For more information on transactions and message-driven beans, see EJBs and Transactions.

use-caller-identity

Optional. Specifies whether or not this EJB uses the caller's identity. When not specified, this attribute defaults to True. You must set this attribute to False to use the run-as and run-as-identity-principal attributes. For more information, see Role-Based Security.

Related Topics

Getting Started with Message-Driven Beans

Message-Driven Bean Sample

EJB Tutorial, Part Three: Adding a Message-Driven Bean

Role-Based Security

EJBs and Transactions