6 Configuring JMS Application Modules for Deployment

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 Server Administration Console.

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

<weblogic-jms xmlns="http://xmlns.oracle.com/weblogic/weblogic-jms">
  <connection-factory name="ACF">
  </connection-factory>
  <queue name="AppscopeQueue">
  </queue>
</weblogic-jms>

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

Figure 6-1 Relationship Between a JMS Application Module and Descriptors in an EJB Application

Description of "Figure 6-1 Relationship Between a JMS Application Module and Descriptors in an EJB Application"

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

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 to retrieve references to JMS entities, as described in Referencing a Packaged JMS Application Module in Deployment Descriptor Files in Developing JMS Applications for Oracle WebLogic Server. (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 for Oracle WebLogic Server.

A JMS application module can be deployed by itself as a standalone module, in which case the module is available to the server or cluster targeted during the deployment process. JMS modules deployed in this manner can be reconfigured using the weblogic.Deployer utility or the WebLogic Server Administration Console, but are not available through JMX or 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 Java EE applications and modules to WebLogic Server. For information about WebLogic Server deployment, see Understanding WebLogic Server Deployment in Deploying Applications to Oracle WebLogic Server.

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.

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 Server Administration Console.

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

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

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, JMS, and WLDF Application Modules in Deploying Applications to Oracle WebLogic Server.

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.

JMS resources deployed within standalone modules can be reconfigured using the weblogic.Deployer utility or the WebLogic Server 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 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 Java EE applications and modules to WebLogic Server. For information about WebLogic Server deployment, see Understanding WebLogic Server Deployment in Deploying Applications to Oracle WebLogic Server.

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

In the case of JMS modules in a local application, at runtime ${APPNAME} becomes the name or ID of the application. For example:

<jndi-name>${APPNAME}/jms/MyConnectionFactory</jndi-name>

When deployed within an application called MyApp, it would result in a runtime JNDI name of:

MyApp/jms/MyConnectionFactory

In the case of JMS modules in an application library, at runtime ${APPNAME} becomes the name/ID of the application which refers to the library (not the name of the library). For example:

<jndi-name>${APPNAME}/jms/MyConnectionFactory</jndi-name>

When deployed within an application library called MyAppLib, and referenced from an application called MyApp, it would result in a runtime JNDI name of:

MyApp/jms/MyConnectionFactory

In the case of JMS modules deployed as stand-alone modules, at runtime ${APPNAME} becomes the name/ID of the stand-alone module. For example:

<jndi-name>${APPNAME}/jms/MyConnectionFactory</jndi-name>

When deployed within a stand-alone JMS module MyJMSModule, it would result in a runtime JNDI name of:

MyJMSModule/jms/MyConnectionFactory

The ${APPNAME} string can be used anywhere you refer to the JNDI name of a JMS resource. For example, in the:

• jndi-name or local-jndi-name element of connection-factory elements in the JMS module descriptor.

• jndi-name or local-jndi-name element of queue or topic elements in the JMS module descriptor.

• jndi-name element of distributed-queue or distributed-topic elements in the JMS module descriptor.

• jndi-name element of uniform-distributed-queue or uniform-distributed-topic elements in the JMS module descriptor.

• destination-jndi-name element of message-destination-descriptor elements in the weblogic-ejb-jar.xml descriptor.

  Note:

  WebLogic EJB also supports the use of the ${APPNAME} string.

• jndi-name element of weblogic-enterprise-bean elements in the weblogic-ejb-jar.xml descriptor.

In a single-server environment, WebLogic Integration Worklist uses application-scoped JMS resources (For example, queues and connection factories) to support its modular deployment goals. Application-scoped JMS allows WebLogic Integration to have an application library define the EJBs, JMS resources, and so on needed by worklist, and then have users simply include worklist into their application by adding a library-ref to their application. However, this prevents the worklist user from scaling those destinations to the cluster from an application library.

In a clustered environment, users can now substitute the ${APPNAME} string for the queue's JNDI name at runtime to make the global JNDI names for the queues unique. This way, the JMS ${APPNAME} parameter is replaced at runtime with the application name of the host application being merged to the application library.