Create message-driven beans

Creating message-driven beans

You can use the Create an Enterprise Bean wizard to create EJB 2.0 or EJB 2.1 message-driven beans.
To create a message-drive bean, first have an EJB 2.0 or EJB 2.1 project defined. Message-driven beans are only supported for EJB 2.x projects.

Message-driven beans were introduced in EJB 2.0 to support the processing of asynchronous messages from a Java Message Service (JMS). The EJB 2.1 specification expands the definition of the message-driven bean so that it can support any messaging system, not just JMS. Accordingly, the deployment descriptor elements used to define message-driven beans changed in the EJB 2.1 specification. The wizard for creating an EJB 2.1 message-driven bean also includes additional pages for optionally defining your non-JMS messaging system and its activation configuration elements.

The following code examples illustrate the differences between the EJB 2.0 and EJB 2.1 deployment descriptor elements that are used to define message-driven beans.

This code sample shows an EJB 2.0 message-driven bean description in the deployment descriptor:
<message-driven id="Mdb20">
  <ejb-name>Mdb</ejb-name>
  <ejb-class>ejbs.MdbBean</ejb-class>
  <transaction-type>Bean</transaction-type>
  <message-selector>mdbMessage</message-selector>
  <acknowledge-mode>Auto-acknowledge</acknowledge-mode>
  <message-driven-destination>
    <destination-type>javax.jms.Topic</destination-type>
    <subscription-durability>Durable</subscription-durability>
  </message-driven-destination>
</message-driven>
This code sample shows an EJB 2.1 message-driven bean description in the deployment descriptor:
<message-driven id="Mdb21">
  <ejb-name>Foo</ejb-name>
  <ejb-class>ejbs.FooBean</ejb-class>
  <messaging-type>javax.jms.MessageListener</messaging-type>
  <transaction-type>Bean/transaction-type>
  <message-destination-type>javax.jms.Topic</message-destination-type>
  <activation-config>
    <activation-config-property>
      <activation-config-property-name>destinationType</activation-config-property-name>
      <activation-config-property-value>javax.jms.Topic</activation-config-property-value>
    </activation-config-property>
    <activation-config-property>
      <activation-config-property-name>subscriptionDurability</activation-config-property-name>
      <activation-config-property-value>Durable</activation-config-property-value>
    </activation-config-property>
    <activation-config-property>
      <activation-config-property-name>acknowledgeMode</activation-config-property-name>
      <activation-config-property-value>AutoAcknowledge</activation-config-property-value>
    </activation-config-property>
    <activation-config-property>
      <activation-config-property-name>messageSelector</activation-config-property-name>
      <activation-config-property-value>fooSelector</activation-config-property-value>
    </activation-config-property>
  </activation-config>
  </transaction-type>
</ejb-name>
</message-driven>
In EJB 2.1, the specification defines an <activation-config-property> element to be used for defining properties such as the acknowledge mode, message selector, subscription durability, and destination type. When you use a non-JMS messaging type, the wizard allows you to define the <activation-config-property> name and value pairs that you need to use for your bean. For a JMS messaging system, the wizard provides the default configuration properties required by JMS, such as subscriptionDurability and acknowledgeMode.

To create an EJB 2.0 or EJB 2.1 message-driven bean:

In the J2EE perspective, click File > New > Enterprise Bean. The Create an Enterprise Bean wizard appears.
Select the Message-driven bean radio button.
Select the EJB project that you want to add the bean to. You can choose EJB 2.0 or EJB 2.1 projects.
In the Bean name field, type the name that you want to assign to the enterprise bean. By convention, bean names should begin with an uppercase letter.
Note: You can use Unicode characters for the bean name, but Unicode characters are not supported for enterprise bean packages and classes associated with enterprise beans.
In the Source folder field, select the source folder for the new bean.
In the Default package field, enter the package name for the new bean.
Optional: For EJB 2.x beans, you can select Generated an annotated bean class. If you select this option, the wizard generates annotations at the beginning of the Java code for the bean class. The annotations define the bean's implementation as you specify in the wizard. The annotations are then used by the EJB tools to generate the necessary bean classes, and to provide values that are inserted in the EJB deployment descriptor (ejb-jar.xml). Select this option if you are familiar with annotations and want to use the annotations to update the bean rather than using the deployment descriptor.
For more information, see Annotation-based programming overview.

Click Next.
For EJB 2.1 beans, specify the messaging service to use for the message-driven bean, then click Next.
JMS type: Select this option if you want to use a JMS message service, using the javax.jms.MessageListener class as the listener type.
Other type: Select this option if you want to use a non-JMS or custom messaging service. In the Listener type field, enter the fully-qualified name of the listener class.

Specify the details for the message-driven bean. If you are creating an EJB 2.1 message-driven bean that uses a non-JMS messaging system, some options are not available but can be defined manually as activation configuration name-value pairs:
Transaction type: You can specify that either the container or the bean manages the bean's transactions.
Destination Type: You can specify queue or topic as the message destination for the message-driven bean.
Activation config: For an EJB 2.1 message-driven bean using a non-JMS messaging type, use this table to configure additional properties. Each name-value pair that you define is added to the deployment descriptor as <activation-config-property> elements.
Acknowledge mode: For a bean using JMS-type messaging and bean-managed transactions, you can specify how the session acknowledges any messages it receives.
Durability: For a bean using JMS-type messaging and having a message destination type of topic, you can specify whether a topic subscription is durable or non-durable:
Durable: A subscriber registers a durable subscription with a unique identity that is retained by JMS. Subsequent subscriber objects with the same identity resume the subscription in the state it was left in by the earlier subscriber. If there is no active subscriber for a durable subscription, JMS retains the subscription's messages until they are received by the subscription or until they expire.
NonDurable: The subscriptions last for the lifetime of their subscriber object. This means that a client sees the messages published on a topic only while its subscriber is active. If the subscriber is not active, the client is missing messages published on its topic.

Bean supertype: If you want the new bean to inherit from an existing bean of the same type in the same EJB project, select a bean in the drop-down list.
Bean class: Enter the desired package and class name for the bean class. By default, the wizard suggests a bean class based on the bean name and default package that you defined. A bean class can be a new class that the wizard generates, or it can be an existing class in the project class path. Click the Class button to open a dialog that lists the classes in the project that correspond to the bean type. The name of the bean class appears blue for existing classes with source. The name of the bean class appears red for existing binary classes.
Message selector: For beans using JMS-type messaging, the JMS message selector is used to determine which messages the message bean receives.

Optional: Click Next and in the Bean superclass field, type or select the desired class. This field is disabled if a bean supertype was specified.
Click Finish. The new bean is generated and defined in the deployment descriptor.

You can use the Bean page of the EJB Deployment Descriptor editor to review the bean and change or add any additional settings or extensions and bindings.

Parent topic
Creating enterprise beans