Message-Driven EJBs

This section describes how message-driven beans work within the EJB container, and provides design and development guidelines that are specific to message-driven beans. For a description of the overall bean development process, see Implementing Enterprise Java Beans.

It is assumed that the reader is familiar with Java programming and message-driven bean features and capabilities. For an introduction to message-driven bean features and how they are typically used in applications, see Message-Driven Beans Implement Loosely Coupled Business Logic and Message-Driven Beans. To understand the Java Messaging Service API, which message-driven beans use, see Programming WebLogic JMS.

The following sections describes the message-driven bean lifecycle, design considerations, and instructions for key implementation tasks.

 

Pooling for Message-Driven EJBs

By default, no message-driven EJB instances exist in WebLogic Server at startup time. As individual beans are invoked, WebLogic Server initializes new instances of the EJB.

However, in a production environment, WebLogic Server can provide improved performance and throughput for message-driven EJBs by maintaining by using a free pool of unbound message-driven EJBs - instances that are not currently processing a method call. If an unbound instances is available to serve a request, response time improves, because the request does not have to wait for an instance to be created. The free pool improves performance by reusing objects and skipping container callbacks when it can.

Upon startup, WebLogic Server automatically creates and populates the free pool with the quantity of instances you specify in the bean's initial-beans-in-free-pool deployment element in the weblogic-ejb-jar.xml file. By default, initial-beans-in-free-pool is set to 0.

The following figure illustrates the WebLogic Server free pool, and the processes by which stateless EJBs enter and leave the pool. Dotted lines indicate the "state" of the EJB from the perspective of WebLogic Server.

Figure 7-1 WebLogic Server free pool showing message-driven EJB life cycle

When JMS invokes an MDB's onMessage() method, if you have configured the EJB to use the free pool, WebLogic Server will service the request with an instance from the free pool, if one is available. The EJB remains active for the duration of the MDB's onMessage() execution. After the method completes, the EJB instance is returned to the free pool.

If all instances of an MDB are active, and max-beans-in-free-pool has been reached, JMS onMessage() requests will be blocked until an active MDB completes a method call. Note that the maximum size of the free pool is limited by the max-beans-in-free-pool deployment element, available memory, or the number of execute threads.

When an application requests a bean instance from the free pool, there are three possible outcomes:

  • An instance is available in the pool. WebLogic Server makes that instance available and your application proceeds with processing.
  • No instance is available in the pool, but the number of instances in use is less then max-beans-in-free-pool. WebLogic Server allocates a new bean instance and gives it to you.
  • No instances are available in the pool and the number of instances in use is already equal to max-beans-in-free-pool. Your application must wait until either your transaction times out or a bean instance that already exists in the pool becomes available.

 

How WebLogic Server Processes MDBs

When a JMS Queue or Topic receives a message, WebLogic Server calls an associated message-driven bean as follows:

  1. WebLogic Server obtains a new bean instance.
  2. If a bean instance is available in the free pool, WebLogic Server uses that instance. If no bean instance is available in the free pool, because the max-beans-in-free-pool attribute is at its maximum setting, WebLogic Server waits until a bean instance is free.

    If no bean instance is located in the free pool, WebLogic Server creates a new instance by calling the bean's ejbCreate() method and then the bean's setMessageDrivenContext() to associate the instance with a container context. The bean can use elements of this context as described in Using the Message-Driven Bean Context.

  3. WebLogic Server calls the bean's onMessage() method to implement the business logic.

If a WebLogic Server instance cannot find a message-driven bean's JMS destination server during deployment, deployment succeeds, but WebLogic Server prints a message saying the JMS queue or topic was not found. The message-driven bean then periodically tries to connect to its JMS queue until it succeeds. See Reconnecting to a JMS Destination.

 

MDBs Support Concurrent Processing for JMS Destinations

Message-driven beans (MDBs) support concurrent processing for both topics and queues. To ensure concurrency, the container uses threads from the execute queue. The number of concurrent message consumers is a function of the number of threads.

The default setting for the max-beans-in-free-pool element in the weblogic-ejb-jar.xml deployment descriptor file provides the most parallelism. The only reason to change this setting would be to limit the number of parallel consumers.

The maximum number of MDBs configured - via the max-beans-in-free-pool deployment descriptor element - to receive messages at one time cannot exceed 50 percent of the number of execution threads. For example, if max-beans-in-free-pool is set to 50 and 50 is the maximum number of execution threads allowed, only 25 of the MDBs will actually receive messages.

 

Message-Driven Beans Design Decisions

This section discusses issues to consider when designing application architectures that use message-driven beans:

 

Co-Location and JMS Destination Distribution

If you plan to deploy your MDB application in a cluster, there are two key architectural design decisions to consider:

  • Whether to locate the application's MDBs on the same WebLogic Server instance as the JMS destination, also known as "co-location."
  • If you choose co-location, whether to distribute the JMS destination - and, consequently, the MDBs - across multiple servers in the cluster.

 

Co-Location Trade-Offs

For performance reasons, it is often best to co-locate your MDBs with the JMS destination, because in this scenario, all messages are local, which means that message transmission does not require network round-trips.

However, it is not possible to locate MDBs on the same WebLogic Server instance as the JMS destination if you are using a 3rd-party JMS provider, such as MQ Series, as 3rd-party providers cannot run on WebLogic Server.

Figure 7-2 illustrates a cluster architecture in which the JMS destination and the MDBs are deployed on the same WebLogic Server instance.

Figure 7-2 Co-location of MDBs with JMS destination





The architecture in illustrated in Figure 7-2 is the best choice for you if:

  • You are using WebLogic Server JMS and want to minimize message processing latency
  • You are using WebLogic JMS and want to reduce network traffic

Figure 7-3 illustrates a cluster architecture in which the JMS destination and the MDBs are deployed on distinct WebLogic Server instances. The JMS destination and MDBs could also be deployed on distinct clusters.

Figure 7-3 MDBs not co-located with JMS destination



The architecture illustrated in Figure 7-3 is a good choice for you if:

  • Your application uses a 3rd-party JMS provider, such as MQ Series
  • You want to keep the application code (the MDBs) on separate Managed Servers from the JMS infrastructure. You may want to have JMS destinations on certain managed servers, and their MDBs on other Managed Servers. That way, if there is a problem with the application code in the MDBs - for example, it uses up all the memory available to the VM - JMS will continue working.
  • The application code that your MDB calls is very CPU-intensive. You might want to run it on a separate computer so it can get 100 percent of the CPU, leaving other machines for the infrastructure tasks.

 

Co-Location: Distributed Versus Non-Distributed Destinations

WebLogic JMS supports service continuity in the event of a WebLogic Server instance failure within a cluster through the configuration of multiple physical destinations (queues and topics) as members of a single distributed destination set. Once configured, your producers and consumers send and receive messages through what appears to be a single destination.

However, WebLogic JMS actually distributes the messaging load across all the available destination members within the distributed destination. In the event that a member becomes unavailable due to a server failure, traffic is then redirected toward the other available destination members in the set.

When an MDB is deployed to a server in a cluster and the distributed destination is part of the same cluster, WebLogic Server automatically enumerates the distributed destination members and ensures that there's an MDB listening on each member. See Configuring an MDB to Listen on a JMS Distributed Destination.

Figure 7-4 illustrates a cluster architecture in which the JMS destination is distributed across all servers in the cluster. MDBs are deployed to each node in the cluster where a destination instance is deployed. Message processing occurs in parallel; a global destination sends messages to the destination instances distributed to the various servers.

Figure 7-4 Co-location of MDBs with distributed JMS destinations


The distributed architecture illustrated in Figure 7-4 is a good choice for you if:

  • You want high availability; in this architecture, if one server goes down, other nodes in the cluster can continue to process new messages.
  • You want to set up a homogenous cluster - one in which all machines are running identical applications
  • Your application needs to perform massively parallel processing
  • Your application will process a relatively large number of messages
  • Your application does not require that messages be processed in the order in which they were produced
  • The machines in your cluster are similar or equal in terms of processing power, and disk and memory resources

Figure 7-5 illustrates a cluster architecture in which the JMS destination is not distributed across all servers in the cluster; it is only deployed on Server 1. MDBs are co-located with the JMS destination on Server 1.

Figure 7-5 Co-location of MDBs with non-distributed JMS destination





The non-distributed architecture illustrated in Figure 7-5 is a good choice for you if:

  • One machine in your configuration has more processing power, and disk and memory resources than other machines in the configuration.
  • Your application will process a relatively small number of messages
  • Your application must process messages in the order in which they are produced

 

Non-Distributed Queues versus Non-Distributed Topics

For clustered, non-distributed JMS architectures, you should choose between the JMS destination type - queue or topic - based on the characteristics of your application.

 

Queue Architecture: One Message, One MDB Listener

A non-distributed queue architecture is "point-to-point"; a message is picked up by one MDB listener and stays in the queue until processed. If the MDB goes down, the message sits in the queue, waiting for the MDB to come up again. This is a useful architecture for applications in which a single component asynchronously processes each message and the application cannot tolerate loss of messages.

Example: As a department store sells items during the course of a day, it needs to asynchronously update its backend inventory system, via asynchronous messages.

In the case of a non-distributed queue, all the nodes in the cluster queue up, waiting for a message to process. Thus the first message goes to the first available node, the next message to the next available node, and so on, as illustrated in Figure 7-6.

Figure 7-6 Non-distributed queue; nodes are queued up waiting for messages


 

Topic Architecture: All Messages Broadcast to All Subscribed Listeners

A non-distributed topic architecture is a "publish and subscribe" model. A JMS topic broadcasts all messages to all subscribed listeners. If an MDB goes down, the MDB will miss the message, unless the topic is a "durable subscription" topic.

To enable durable subscriptions for an MDB, set the jms-client-id element in weblogic-ejb-jar.xml. See WebLogic-Specific Configurable Behaviors for MDBs.

See Setting Up Durable Subscriptions" in Programming WebLogic JMSjms_durable_subscriber, for more information on the durable subscription feature.

Example: A sports score service broadcasts up-to-the-minute baseball scores to all newspapers, television and radio stations that subscribe to the service.

In a non-distributed topic architecture, nodes do not queue up waiting for messages. Each message goes to all nodes, as illustrated in Figure 7-7.

Figure 7-7 Non-distributed topic; each message goes to every node


For more information on point-to-point and publish-and-subscribe messaging models, see Messaging Models in Programming WebLogic JMS.


 

Ensuring Message Receipt Order

Make sure that the business logic accounts for asynchronous message processing. For example, it cannot be assumed that the MDB receives messages in the order they were sent by the client. To ensure that receipt order matches the order in which the client sent the message, do the following:

  • Set max-beans-in-free-pool to 1 for the MDB. This ensures that the MDB is the sole consumer of the message.
  • If your MDBs are deployed on a cluster, configure your MDB so that it sits on only one node in the cluster, as illustrated in Figure 7-2.

See Sun's documentation on the Interface MessageListener - javax.jms.MessageListener.onMessage() - for more information.

 

Message Receipt, Acknowledgement and Redelivery

This section discusses MDB design considerations related to message receipt, acknowledgement and redelivery.

 

Preventing and Handling Duplicate Messages

A JMS producer expects an MDB to acknowledge message receipt. If the MDB receives the message, but fails to send an acknowledgement, the JMS producer re-sends the same message.

Your MDB design considerations should include preventing and handling duplicate messages. Duplicate messages can be undesirable in certain cases. For example, if an MDB's onMessage() method includes code to debit a bank account, receiving that message twice would result in the account being debited a second time. In addition, re-sending messages consumes more processing resources.

The best way to prevent delivery of duplicate messages is to use container-managed transactions. This means message receipt and acknowledgement happen within a transaction; either both happen or neither happens. However, while this provides more reliability than using bean-managed transactions, performance can be compromised because container-managed transactions use more CPU and disk resources.

If the MDB manages its own transactions, then your onMessage() code must be prepared to handle duplicate messages, as receipt and acknowledgement occur outside of a transaction.

Even if an MDB's onMessage() method completes successfully, the MDB can nonetheless receive duplicate messages if the server crashes between the time OnMessage() completes and the time the container acknowledges message delivery. Figure 7-8 illustrates this scenario.

Figure 7-8 Server crash between completion of onMessage() and container delivery acknowledgement



 

Redelivery and Exceptions Handling

If an MDB is consuming a message and something unexpected happens, the MDB can throw a system exception that, in turn, tells JMS to resend, delay and then resend, or give up, depending on how JMS is configured. The duration of the redelivery delay depends on the task MDB's onMessage() method is performing. Sometimes you want redelivery to be instantaneous, for example f an application posts breaking news to a newswire service. By contrast, if the MDB throws an exception because the database is down, you do not want instantaneous redelivery. You would like JMS to redeliver the message after the database is up again.

For instructions on configuring a redelivery delay, see Setting a Redelivery Delay" in Programming WebLogic JMS.

 

Message-Driven Bean Migratable Service

WebLogic Server supports migratable and recovery services for message-driven beans in clustered architectures.

To provide these migratable and recovery services, WebLogic JMS and MDBs use the migration framework provided by WebLogic Server to respond to migration requests and bring a JMS destination and MDBs back online after a failure. You should design your application so that when a server fails, your application automatically migrates the JMS destination and its associated MDBs from the failed server in the cluster to an available server.

If the message-driven beans associated with a JMS destination do not migrate along with destination, the JMS destination will be flooded with messages. After the MDB migrates to another server, it connects to the migrated JMS destination and continues to receive messages from the JMS destination on behalf the MDB on the failed server.

Note: An MDB can use the migratable service with clustered servers only. Also, at this time, the migratable service cannot span multiple clusters.

 

Strategies for Migrating MDBs

MDBs do not have migratable targets. Instead, an MDB automatically detects the JMS Server migration target during deployment, and uses that as its migratable target. You must ensure that MDB are deployed everywhere that a JMS Server is deployed. You can do this in two ways:

  • For a homogeneous cluster, you can target the MDB to the entire cluster
  • For a non-homogeneous cluster, you can match an MDB's targets to the JMS migratable target list in Server 1's config.xml file. The MDB target server name must match the JMS migratable target list, or MDB migration will fail. For more information on configuring migratable targets, see "Defining Migratable Target Servers in a Cluster"WebLogic Server Clusters

 

Migratable Service Supported for Distributed and Non-Distributed Destinations

In Figure 7-9, Servers 1, 2 and 3 are in the same cluster. The JMS destination is not distributed. To ensure high availability, Server 2 and Server 3 are configured as Server 1's migratable targets. In the event that Server 1 fails, both the JMS destination and the MDBs migrate to the next available server in the migratable target list.

Figure 7-9 Migration: non-distributed destination



In Figure 7-10, Servers 1, 2 and 3 are in the same cluster. The JMS destination is distributed across all servers in the cluster.

To ensure high availability, Server 2 and Server 3 are configured as Server 1's migratable targets. In the event that Server 1 fails, JMS destination instances migrate to other servers, along with the destination instances' associated MDBs.

Figure 7-10 Migration: distributed destination


 

Implementing the Message-Driven Bean Migratable Service

For instructions implementing the migratable service and for background information on WebLogic JMS' migratable and recovery services for clustered architectures, see JMS as a Migratable Service within a Cluster" in Programming WebLogic JMS.

 

Implementing Message-Driven Beans

Follow these steps to implement a message-driven bean:

  1. Create a source file (message-driven bean class) that implements both the javax.ejb.MessageDrivenBean and javax.jms.MessageListener interfaces.

    The message-driven bean class must define the following methods:

    • One ejbCreate() method that the container uses to create an instance of the message-driven bean on the free pool.
    • One onMessage() method that is called by the bean's container when a message is received. This method contains the business logic that handles processing of the message. See Message-Driven Bean Migratable Service.
    • One setMessageDrivenContext{} method that provides information to the bean instance about its environment (certain deployment descriptor values); the Context is also the mechanism the bean class uses to access some services provided by the EJB container. See Using the Message-Driven Bean Context.
    • One ejbRemove() method that removes the message-driven bean instance from the free pool.
  2. Set the message-driven element in the bean's ejb-jar.xml file to declare the bean.

    The following sample shows how to specify a message-driven bean in the ejb-jar.xml file.

    Figure 7-11 Sample XML stanza from an ejb-jar.xml file: 

<enterprise-beans>



 <message-driven>



  <ejb-name>exampleMessageDriven1</ejb-name>



  <ejb-class>examples.ejb20.message.MessageTraderBean</ejb-class>



  <transaction-type>Container</transaction-type>



  <message-driven-destination>



   <destination-type>



    javax.jms.Topic



   </destination-type>



  </message-driven-destination>



  ...



 </message-driven>



 ...



</enterprise-beans>
  1. Set the message-driven-destination element in the bean's ejb-jar.xml file to specify whether the bean is intended for a Topic or Queue.
  2. If your bean will demarcate its own transaction boundaries - see Configuring Transaction Management Strategy for an MDB - set the acknowledge-mode sub-element to specify the JMS acknowledgment semantics to use. This element has two possible values: AUTO_ACKNOWLEDGE (the default) or DUPS_OK_ACKNOWLEDGE.
  3. If the container will manage the transaction boundaries, set the transaction-type element in the bean's ejb-jar.xml file to specify how the container must manage the transaction boundaries when delegating a method invocation to an enterprise bean's method. Configuring Transaction Management Strategy for an MDB
  4. Configure other behavior for the message-driven bean, according to your application's needs. See WebLogic-Specific Configurable Behaviors for MDBs.
  5. Set the message-driven-descriptor element in the bean's weblogic-ejb-jar.xml file to associate the message-driven bean with a JMS destination in WebLogic Server.

    The following sample shows how to specify a message-driven bean in an weblogic-ejb-jar.xml file.

  6. Compile and generate the message-driven bean class using instructions in EJB Development Task Guide.
  7. Deploy the bean on WebLogic Server using the instructions in the section Quickstart Guide to Deploying Modules in Deploying WebLogic Server Applications.

 

Using the Message-Driven Bean Context

WebLogic Server calls setMessageDrivenContext() to associate the message-driven bean instance with a container context.This is not a client context; the client context is not passed along with the JMS message. To access the container context's properties from with the MDB instance, use the following methods from the MessageDrivenContext interface:

  • getCallerPrincipal()) - This method is inherited from the EJBContext interface and should not be called by message-driven bean instances.
  • isCallerInRole()) - This method is inherited from the EJBContext interface and should not be called by message-driven bean instances.
  • setRollbackOnly() - The EJB can use this method only if it uses container-managed transaction demarcation.
  • getRollbackOnly() - The EJB can use this method only if it uses container-managed transaction demarcation.
  • getUserTransaction() - The EJB can use this method only if it uses bean-managed transaction demarcation.

Note: Although getEJBHome() is also inherited as part of the MessageDrivenContext interface, message-driven beans do not have a home interface. Calling getEJBHome() from within a message-driven EJB instance yields an IllegalStateException.

 

Configuring Message-Driven Beans for Foreign (Non-BEA)
JMS Providers

You can configure message-driven beans to work with non-BEA JMS providers such as IBM MQSeries. You can do this for both MDBs supporting container-managed transactions ("transactional MDBs") and MDBs supporting bean-managed transactions ("non-transactional MDBs."). See Configuring Transaction Management Strategy for an MDB for details on transactional versus non-transactional MDBs.

Applications with transactional MDBs can achieve exactly-once semantics with a non-BEA JMS provider for messages processed by an MDB. In addition, WebLogic Server will use XA to automatically enlist the non-BEA JMS provider in a transaction. For applications with non-transactional MDBs, the MDB will provide at-least-once message processing semantics and XA is not required.

If the non-BEA JMS provider does not support XA, then you cannot deploy an MDB that supports container-managed transactions with that provider. Furthermore, if the JMS provider does support XA, ensure that the JMS connection factory that you specify in the weblogic-ejb-jar.xml file supports XA - each JMS provider has a different way to specify this.

Be sure to set destination-jndi-name, initial-context-factory, provider-url, and connection-factory-jndi-name elements in weblogic-ejb-jar.xml appropriately for the non-BEA JMS provider.

Note: For transactional MDBs, the JMS connection factory specified in connection-factory-jndi-name must support the optional XA extensions to JMS - each JMS provider has a different way to specify this.

Also, you can configure an optional security identity for the message-driven bean, as described in Configuring a Security Identity for a Message-Driven Bean.

See the white paper, Using Foreign JMS Providers with WLS Message Driven Beans" (jmsmdb.pdfhttp://dev2dev.bea.com/resourcelibrary/whitepapers/jmsproviders.jsp for an example of how to configure an MDB to use a non-BEA provider.

 

WebLogic-Specific Configurable Behaviors for MDBs

Table 7-1 summarizes the deployment descriptor elements you set to configure the behavior of a message-driven bean and how the bean behaves if you do not configure the element. All of the elements listed are sub-elements of the message-driven-descriptor element in weblogic-ejb-jar.xml.

To control

Set the following weblogic-ejb-jar.xml element(s)

Default behavior

The number of inactive instances of a stateless session bean that exist in WebLogic Server when it is started. See Pooling for Message-Driven EJBs. initial-beans-in-free-pool WebLogic Server creates 0 beans in the free pool.
The maximum size of the free pool of inactive stateless session beans. max-beans-in-free-pool WebLogic Server limits the maximum number of beans in the free pool to 1000.
The JNDI name used to associate a message-driven bean with an actual JMS Queue or Topic deployed in the WebLogic Server JNDI tree. destination-jndi-name

Note: You must configure this element

N/A

The initial contextFactory that the EJB container uses to create its connection factories. initial-context-factory The EJB container uses the default value of weblogic.jndi.WLInitialContextFactory for the context factory.
The URL provider to be used by the InitialContext. Typically, this is the host port. provider-url The default provider URL: t3://localhost:7001
The JNDI name of the JMS ConnectionFactory that the message-driven EJB should look up to create its queues and topics. connection-factory-jndi-name WebLogic Server uses weblogic.jms.MessageDrivenBeanConnectionFactory in the server's config.xml file.
The client id for the a message-driven bean associated with a durable subscriber topic.See Defining the Client ID" in Programming WebLogic JMS.../jms/implement.html/#defining_client_id jms-client-id WebLogic Server uses the value of ejb-name for this setting.
The number of seconds between attempts by the EJB container to reconnect to a JMS destination that has become unavailable.See Reconnecting to a JMS Destination. jms-polling-interval-seconds The EJB container attempts reconnection every 10 seconds

 

Configuring Transaction Management Strategy for an MDB

As described in Understanding Transaction Demarcation Strategies and Performance, an EJB's transaction can be managed by the client, the bean, the EJB container or - in the case of entity beans - the database. In the case of message-driven beans, however, transaction management can only occur at the bean or container level; the client sending the message never sets an MDB's transaction context.

If the container is managing the MDB's transaction, the container is responsible for ensuring that a transaction is started before the onMessage() method is called.

Configure an MDB's transaction management strategy using the trans-attribute and container-transaction elements in the bean's ejb-jar.xml deployment descriptor, as summarized in Table 7-2.

To configure an MDB to manage its own transaction

To configure an MDB to use container-managed transactions

    1. Set the transaction-type element in the message-driven stanza in ejb-jar.xml file to Bean.
    1. Set the transaction-type element in the message-driven stanza in ejb-jar.xml file to Container.
    2. Set the trans-attribute element in the container-transaction stanza in ejb-jar.xml to Required.

Note: If transaction-type is set to Container, and trans-attribute is not set, the default transaction-attribute value (NotSupported for MDBs) is applied. WebLogic Server allows you to deploy the MDB, and, as of SP02, logs a compliance error. However, if you make this configuration error, the MDB will not run transactionally - if a failure occurs mid-transaction, updates that occurred prior to the failure will not be rolled back.

 

Configuring an MDB to Listen on a JMS Distributed Destination

Follow these steps to configure a message-driven bean for a distributed destination:

  1. Configure a JMS distributed destination, as described in Configuring Distributed Destinations.
  2. Set the MDB's destination-jndi-name in weblogic-ejb-jar.xml to the name used to bind the distributed topic or queue into the JNDI namespace.
  3. MDBs do not have migratable targets, so set the target for MDB to be the same as the distributed destination. The MDB need to be deployed wherever that distributed destination exists.
  4. Deploy the MDB.

At deployment time, the MDB detects the member of the distributed destination the exists on that WebLogic Server instance, pin itself to the member, and start processing messages.

 

Reconnecting to a JMS Destination

A message-driven bean listens to an associated JMS destination. If the connection to that destination is lost, because the server goes down, the message-driven bean attempts to reconnect to that destination at periodic intervals. You can specify the number of seconds between attempts to reconnect to the destination by setting the jms-polling-interval-seconds element in the bean's weblogic-ejb-jar.xml file.

 

Configuring a Security Identity for a Message-Driven Bean

When a message-driven bean (MDB) receives messages from a JMS queue or topic, the EJB container uses a Credential Mapping provider and a credential map to obtain the security identity - username and password - to use when establishing the JMS connection. This credential mapping occurs only once, when the MDB is started.

Once the EJB container is connected, the JMS provider uses the established security identity to retrieve all messages. The security identity is especially important when using an MDB to receive messages from a non-BEA JMS provider - either a JMS provider from another vendor or a WebLogic Server JMS provider running in another WebLogic Server domain.

To configure a security identity for an MDB:

  1. Create a WebLogic user for the MDB. For more information, see Users and Groups" in Securing WebLogic Resources. Assign the user the username and password that the non-BEA JMS provider requires to establish a JMS connection.
  2. In the ejb-jar.xml deployment descriptor, define a run-as identity for the MDB:

    <security-identity>
         <run-as>
              <role-name>admin</role-name>
         </run-as>
    </security-identity>

  3. In the weblogic-ejb-jar.xml deployment descriptor, map the run-as identity to the user defined in the previous step, as shown below:

    <security-role-assignment>
         <role-name>admin</role-name>
         <principal-name>username</principal-name>
    </security-role-assignment>

    where username is the username for the user created in step 1.

  4. In the left pane of the WebLogic Server Administration Console, expand Deployments.

    The Deployments node expands to show the types of WebLogic resources that can be deployed.

  5. Expand the Applications folder or the EJB folder to navigate to the application containing the MDB for which you want to create a credential map, right click on it, and choose the Define Policies and Roles for Individual Beans... option.

    The Define Policies and Roles for ... page lists the beans in the selected archive.

  6. Click the [Define Credential Mappers] link for the MDB for which you want to create a credential map.

    The Credential Mappings page is displayed.

  7. Click the Configure a new Credential Mapping link.

    The Create a new Credential Mapping... page is displayed.

  8. Enter the WebLogic Server user name for the WebLogic Server you created in step one, and the username of the remote provider, and click Apply.

    The Credential Mapping Page displays the new credential map. The map associates the WebLogic Server user name with the remote provider user name, which is shown as a hyperlink.

  9. Click the Remote User hyperlink in the Credential Map table.

    The realm-->user page displays the remote provider user name, and fields for entering and confirming the remote password.

  10. Enter the password for the user in the Remote Password and Confirm Remote Password fields, and click Apply to save your changes.

Skip navigation bar  Back to Top Previous Next