Skip navigation.

Configuring and Managing WebLogic JMS

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

Configuring JMS Application Modules for Deployment

JMS resources can be configured and managed as deployable application modules, similar to standard J2EE modules. Deployed JMS application modules are owned by the developer who created and packaged the module, rather than the administrator who deploys the module; therefore, the administrator has more limited control over deployed resources.

For example, administrators can only modify (override) certain properties of the resources specified in the module using the deployment plan (JSR-88) at the time of deployment, but they cannot dynamically add or delete resources. As with other J2EE modules, configuration changes for an application module are stored in a deployment plan for the module, leaving the original module untouched.

These sections explain how to configure JMS application modules for deployment, including globally available standalone modules and modules packaged with a J2EE application.

 


JMS Schema

In support of the new modular deployment model for JMS resources in WebLogic Server 9.0, BEA now provides a schema for defining WebLogic JMS resources: weblogic-jmsmd.xsd. When you create JMS modules (descriptors), the modules must conform to this schema. IDEs and other tools can validate JMS modules based on the schema.

The weblogic-jmsmd.xsd schema is available online at http://www.bea.com/ns/weblogic/90/weblogic-jmsmd.xsd.

For an explanation of the JMS resource definitions in the schema, see the corresponding system module beans in the "System Module MBeans" folder of the WebLogic Server MBean Reference. The root bean in the JMS module that represents an entire JMS module is named JMSBean.

 


Deploying JMS Modules That Are Packaged In an Enterprise Application

JMS application modules can be packaged as part of an Enterprise Application, as a packaged resource. Packaged modules are bundled with an EAR or exploded EAR directory, and are referenced in the weblogic-application.xml descriptor.

The packaged JMS module is deployed along with the Enterprise Application, and the resources defined in this module can optionally be made available only to the enclosing application (i.e., as an application-scoped resource). Such modules are particularly useful when packaged with EJBs (especially MDBs) or Web Applications that use JMS resources. Using packaged modules ensures that an application always has required resources and simplifies the process of moving the application into new environments.

Creating Packaged JMS Modules

You create packaged JMS modules using an enterprise-level IDE or another development tool that supports editing of XML descriptor files. You then deploy and manage standalone modules using JSR 88-based tools, such as the weblogic.Deployer utility or the WebLogic Administration Console.

Note: You can create a packaged JMS module using the Administration Console, then copy the resulting XML file to another directory and rename it, using "-jms.xml" as the file suffix.

JMS Packaged Module Requirements

Inside the EAR file, a JMS module must meet the following criteria:

Main Steps for Creating Packaged JMS Modules

Follow these steps to configure a packaged JMS module:

  1. If necessary, create a JMS server to target the JMS module to, as explained in "Configure JMS Servers" in the Administration Console Online Help.
  2. Create a JMS system module and configure the necessary resources, such as queues or topics, as described in "Configure JMS system modules and add JMS resources" in the Administration Console Online Help.
  3. The system module is saved in config\jms subdirectory of the domain directory, with a "-jms.xml" suffix.
  4. Copy the system module to a new location, and then:
    1. Give the module a unique name within the domain namespace.
    2. Delete the JNDI-Name attribute to make the module application-scoped to only the application.
  5. Add references to the JMS resources in the module to all applicable J2EE application component's descriptor files, as described in Referencing a Packaged JMS Module In Deployment Descriptor Files.
  6. Package all application modules in an EAR, as described in Packaging an Enterprise Application With a JMS Module.
  7. Deploy the EAR, as described in Deploying a Packaged JMS Module.

Referencing a Packaged JMS Module In Deployment Descriptor Files

When you package a JMS module with an enterprise application, you must reference the JMS resources within the module in all applicable descriptor files of the J2EE application components, including:

Referencing JMS Modules In a weblogic-application.xml Descriptor

When including JMS modules in an enterprise application, you must list each JMS module as a module element of type JMS in the weblogic-application.xml descriptor file packaged with the application, and a path that is relative to the root of the J2EE application. Here's an example of a reference to a JMS module name Workflows:

<module>
<name>Workflows</name>
<type>JMS</type>
<path>jms/Workflows-jms.xml</path>
</module>

Referencing JMS Resources In a WebLogic Application

Within any weblogic-foo descriptor file, such as EJB (weblogic-ejb-jar.xml) or WebApp (weblogic.xml), the name of the JMS module is followed by a pound (#) separator character, which is followed by the name of the resource inside the module. For example, a JMS module named Workflows containing a queue named OrderQueue, would have a name of Workflows#OrderQueue.

<resource-env-description>
<resource-env-ref-name>jms/OrderQueue</resource-env-ref-name>
<resource-link>Workflows#OrderQueue</resource-link>
</resource-env-description>

Note that the <resource-link> element is unique to WebLogic Server, and is how the resources that are defined in a JMS Module are referenced (linked) from the various other J2EE Application components.

Referencing JMS Resources In a J2EE Application

The name element of a JMS Connection Factory resource specified in the JMS module must match the res-ref-name element defined in the referring EJB or WebApp application descriptor file. The res-ref-name element maps the resource name (used by java:comp/env) to a module referenced by an EJB.

For Queue or Topic destination resources specified in the JMS module, the name element must match the res-env-ref field defined in the referring module descriptor file.

That name is how the link is made between the resource referenced in the EJB or Web Application module and the resource defined in the JMS module. For example:

<resource-ref>
<res-ref-name>jms/OrderQueueFactory</res-ref-name>
<res-type>javax.jms.ConnectionFactory</res-type>
</resource-ref>
<resource-env-ref>
<res-env-ref-name>jms/OrderQueue</res-env-ref-name>
<res-env-ref-type>javax.jms.Queue</res-env-ref-type>
</resource-env-ref>

Sample of a Packaged JMS Module In an EJB Application

The following code snippet is an example of the packaged JMS module, appscopedejbs-jms.xml, referenced by the descriptor files in Figure 5-1 below.

<weblogic-jms xmlns="http://www.bea.com/ns/weblogic/90">
<connection-factory name="ACF">
</connection-factory>
<queue name="AppscopeQueue">
</queue>
</weblogic-jms>

Figure 5-1 illustrates how a JMS connection factory and queue resources in a packaged JMS module are referenced in an EJB EAR file.

Figure 5-1 Relationship Between a JMS Module and Descriptors In an EJB Application

Relationship Between a JMS Module and Descriptors In an EJB Application


 

Packaged JMS Module References In weblogic-application.xml

When including JMS modules in an enterprise application, you must list each JMS module as a module element of type JMS in the weblogic-application.xml descriptor file packaged with the application, and a path that is relative to the root of the application. For example:

<module>
<name>AppScopedEJBs</name>
<type>JMS</type>
<path>jms/appscopedejbs-jms.xml</path>
</module>

Packaged JMS Module References In ejb-jar.xml

If EJBs in your application use connection factories through a JMS module packaged with the application, you must list the JMS module as a res-ref element and include the res-ref-name and res-type parameters in the ejb-jar.xml descriptor file packaged with the EJB. This way, the EJB can lookup the JMS Connection Factory in the application's local context. For example:

<resource-ref>
<res-ref-name>jms/QueueFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
</resource-ref>

The res-ref-name element maps the resource name (used by java:comp/env) to a module referenced by an EJB. The res-type element specifies the module type, which in this case, is javax.jms.QueueConnectionFactory.

If EJBs in your application use Queues or Topics through a JMS module packaged with the application, you must list the JMS module as a resource-env-ref element and include the resource-env-ref-name and resource-env-ref-type parameters in the ejb-jar.xml descriptor file packaged with the EJB. This way, the EJB can lookup the JMS Queue or Topic in the application's the local context. For example:

<resource-env-ref>
<resource-env-ref-name>jms/Queue</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>

The resource-env-ref-name element maps the destination name to a module referenced by an EJB. The res-type element specifies the name of the Queue, which in this case, is javax.jms.Queue.

Packaged JMS Module References In weblogic-ejb-jar.xml

You must list the referenced JMS module as a res-ref-name element and include the resource-link parameter in the weblogic-ejb-jar.xml descriptor file packaged with the EJB.

<resource-description>
<res-ref-name>jms/QueueFactory</res-ref-name>
<resource-link>AppScopedEJBs#ACF</resource-link>
</resource-description>

The res-ref-name element maps the connection factory name to a module referenced by an EJB. In the resource-link element, the JMS module name is followed by a pound (#) separator character, which is followed by the name of the resource inside the module. So for this example, the JMS module AppScopedEJBs containing the connection factory ACF, would have a name AppScopedEJBs#ACF.

Continuing the example above, the res-ref-name element also maps the Queue name to a module referenced by an EJB. And in the resource-link element, the queue AppScopedQueue, would have a name AppScopedEJBs#AppScopedQueue, as follows:

<resource-env-description>
<resource-env-ref-name>jms/Queue</resource-env-ref-name>
<resource-link>AppScopedEJBs#AppScopedQueue</resource-link>
</resource-env-description>

Packaging an Enterprise Application With a JMS Module

You package an application with a JDBC module as you would any other enterprise application. See "Packaging Applications Using wlpackage" in Developing Applications with WebLogic Server.

Deploying a Packaged JMS Module

The deployment of packaged JMS modules follows the same model as all other components of an application: individual modules can be deployed to a single server, a cluster, or individual members of a cluster.

A recommended best practice for other application components is to use the java:comp/env JNDI environment in order to retrieve references to JMS entities, as described in Referencing JMS Resources In a J2EE Application. (However, this practice is not required.)

By definition, packaged JMS modules are included in an enterprise application, and therefore are deployed when you deploy the enterprise application. For more information about deploying applications with packaged JMS modules, see "Deploying Applications Using wldeploy" in Developing Applications with WebLogic Server.

 


Deploying Standalone JMS Modules

A JMS application module can be deployed as a standalone resource using the weblogic.Deployer utility or the Administration Console, in which case the module is typically available to the server or cluster targeted during the deployment process. JMS modules deployed in this manner are called standalone modules. Depending on how they are targeted, the resources inside standalone JMS modules are globally available in a cluster or locally on a server instance.

Standalone JMS modules promote sharing and portability of JMS resources. You can create a JMS module and distribute it to other developers. Standalone JMS modules can also be used to move JMS information between domains, such as between the development domain and the production domain, without extensive manual JMS reconfiguration.

Creating Standalone JMS Modules

You can create JMS standalone modules using an enterprise-level IDE or another development tool that supports editing XML descriptor files. You then deploy and manage standalone modules using WebLogic Server tools, such as the weblogic.Deployer utility or the WebLogic Administration Console.

Note: You can create a JMS application module using the Administration Console, then copy the module as a template for use in your applications, using "-jms.xml" as the file suffix. You must also change the Name and JNDI-Name elements of the module before deploying it with your application to avoid a naming conflict in the namespace.

JMS Standalone Module Requirements

A standalone JMS module must meet the following criteria:

Main Steps for Creating Standalone JMS Modules

Follow these steps to configure a standalone JMS module:

  1. If necessary, create a JMS server to target the JMS module to, as explained in "Configure JMS Servers" in the Administration Console Online Help.
  2. Create a JMS system module and configure the necessary resources, such as queues or topics, as described in "Configure JMS system modules and add JMS resources" in the Administration Console Online Help.
  3. The system module is saved in config\jms subdirectory of the domain directory, with a "-jms.xml" suffix.
  4. Copy the system module to a new location and then:
    1. Give the module a unique name within the domain namespace.
    2. To make the module globally available, uniquely rename the JNDI-Name attributes of the resources in the module.
    3. If necessary, modify any other tunable values, such as destination thresholds or connection factory flow control parameters.
  5. Deploy the module, as described in Deploying Standalone JMS Modules.

Sample of a Simple Standalone JMS Module

The following code snippet is an example of simple standalone JMS module.

<weblogic-jms xmlns="http://www.bea.com/ns/weblogic/90">
<connection-factory name="exampleStandAloneCF">
<jndi-name>exampleStandAloneCF</jndi-name>
</connection-factory>
<queue name="ExampleStandAloneQueue">
<jndi-name>exampleStandAloneQueue</jndi-name>
</queue>
</weblogic-jms>

Deploying Standalone JMS Modules

The command-line for using the weblogic.Deployer utility to deploy a standalone JMS module (using the example above) would be:

java weblogic.Deployer -adminurl http://localhost:7001 -user weblogic
-password weblogic \
-name ExampleStandAloneJMS \
-targets examplesServer \
-submoduletargets ExampleStandaloneQueue@examplesJMSServer,ExampleStandaloneCF@examplesServer \
-deploy ExampleStandAloneJMSModule-jms.xml

For information about deploying standalone JMS modules, see "Deploying JDBC and JMS Application Modules."

When you deploy a standalone JMS module, an app-deployment entry is added to the config.xml file for the domain. For example:

<app-deployment>
<name>standalone-examples-jms</name>
<target>MedRecServer</target>
<module-type>jms</module-type>
<source-path>C:\modules\standalone-examples-jms.xml</source-path>
<sub-deployment>
...
</sub-deployment>
<sub-deployment>
...
</sub-deployment>
</app-deployment>

Note that the source-path for the module can be an absolute path or it can be a relative path from the domain directory. This differs from the descriptor-file-name path for a system resource module, which is relative to the domain\config directory.

Tuning Standalone JMS Modules

JMS resources deployed within standalone modules can be reconfigured using the using the weblogic.Deployer utility or the Administration Console, as long as the resources are considered bindable (such as JNDI names), or tunable (such as destination thresholds). However, standalone resources are not available through WebLogic JMX APIs or the WebLogic Scripting Tool (WLST).

However, standalone JMS modules are available using the basic JSR-88 deployment tool provided with WebLogic Server plug-ins (without using WebLogic Server extensions to the API) to configure, deploy, and redeploy J2EE applications and modules to WebLogic Server. For information about WebLogic Server deployment, see "Understanding WebLogic Server Deployment."

Additionally, standalone resources cannot be dynamically added or deleted with any WebLogic Server utility and must be redeployed.

 

Skip navigation bar  Back to Top Previous Next