Introduction

A vitally important function of the WebSphere Application Server from a messaging perspective is its ability to interoperate with WebSphere MQ (hereafter called MQ), IBM’s key messaging product. In WebSphere Application Server Version 6.0 and above, this interoperability relied upon the MQ JAR files that were shipped and installed with WebSphere Application Server or with the MQ client. WebSphere Application Server Version 7.0 has introduced a fully pluggable, Java Enterprise Edition Connector Architecture (hereafter called JCA) compliant MQ resource adapter to replace these JAR files. In addition to standard J2EE resource adapter features, the MQ resource adapter enables more advanced function, such as:

• Client-channel compression
• Client-channel exits
• Client-channel definition tables
• MQ activation specifications for message-driven beans (MDBs) using a Java Messaging Service (hereafter called JMS) application for WebSphere MQ
• More integrated logging and tracing features.

The MQ resource adapter shipped and installed with WebSphere Application Server 7.0 currently works with MQ v6 and above.

One of the additional Qualities of Service available to WebSphere running on the z/OS platform is the ability to exploit the z/OS Workload Manager (hereafter called zWLM). zWLM enables many different workloads with different priorities and requirements to execute on the same hardware. If resources (such as CPU or storage) become constrained, then zWLM will distribute these resources, attempting to ensure that each workload meets its goals.

The new MQ resource adapter on the z/OS platform also lets you use zWLM within WebSphere Application Server. In WebSphere Application Server on z/OS, you can host multiple copies of the EJB container across different servant regions. You can dedicate each servant region to handling certain types of workloads, such as processing certain types or classes of messages instead of just the one servant region handling everything. You can tune the zWLM function to define workload goals for each servant region, and hence assign priority to incoming requests for message processing. For example, for high priority work items you could set a goal of “90% processed within 0.1 second”. The zWLM function will do its best to achieve these goals based on the resources available.

Figure 1 illustrates how messages are consumed by multiple servant regions via zWLM and the MQ resource adapter within WebSphere Application Server. Multiple servant regions host instances of message-driven beans (MDBs) deployed using MQ activation specifications that consume messages appearing on the MQ queue. These messages might be classified for processing priority; for example GOLD, SILVER, and BRONZE. Messages are inspected in the order they arrive on the MQ queue that the MDB’s activation specification requests that it monitors. MQ then assigns work load classifications to the messages based on classification rules known to the control region adjunct (CRA). zWLM then uses these classifications to select a servant region to process the message. The corresponding MDB instance running in that servant region processes the message based on goals set for that class of message.

Back to top

Configuring a JMS application for MQ message classification

The sample JMS client application uses an arbitrary integer property on the message to store the message’s priority. We used JMSXGroupSeq because it is a pre-existing integer property on the message object that is not otherwise used by the application. You could also define a new integer property by the user specifically for classification, but here we used JMSXGroupSeq for convenience and illustrative purposes.

The integer range values correspond to levels as follows:

• BRONZE: Priority = 0 to 3
• SILVER: Priority = 4 to 6
• GOLD: Priority = 7 to 9

In terms of message processing, the GOLD messages should take priority over both SILVER and BRONZE, and SILVER messages take priority over BRONZE.

int count=0;
for (int i = 1; i <= messageCount; i++) {

    // 9 = GOLD, 6 = SILVER, 3 = BRONZE
    if (count==0) priority=3;
    if (count==1) priority=6;
    if (count==2) priority=9;
             

    // jmsMessage is the JMS Message object       
    jmsMessage.setIntProperty("JMSXGroupSeq", priority);

    // queueSender is the JMS QueueSender object
    queueSender.send(jmsMessage);
                    
    ++count;
}

In Listing 1, we assign message priority simply on a round-robin basis. In reality, you would assign priority on an application requirement based on business need. We set the priority after the creation of the JMS messages and before the send occurs.

Back to top

Defining classification rules

Next we’re required to define classification rules, by creating (or amending) a Workload Classification document. These rules associate message priorities with Transaction Classes defined on the zWLM system (see Listing 2) and are defined in an XML document.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Classification SYSTEM "Classification.dtd">
<Classification schema_version="1.0">
	<WMQRAClassification default_transaction_class="TC_3" schema_version="1.0">
  		<wmqra_classification_info transaction_class="TC_1"
                             selector="JMSXGroupSeq&gt;6"
                             description="High priorities 7,8,9 map to TC_1 = GOLD"/>
  		<wmqra_classification_info transaction_class="TC_2"
                             selector="JMSXGroupSeq&gt;3 AND JMSXGroupSeq&lt;7"
                             description="Medium priorities 4,5,6 map to TC_2 = SILVER"/>
	</WMQRAClassification>
</Classification>

With this file defined (called zwlm.xml for example), messages that the MQ resource adapter message selector function browses in the control region adjunct with GOLD priority (in this case JMSXGroupSeq > 7 ) are handled by Transaction Class TC_1 within the zWLM function for consumption by the appropriate servant region(s). SILVER priority messages (JMSXGroupSeq > 3 and < 8) are handled by Transaction Class TC_2 and all other messages (BRONZE in this case) are handled by TC_3.

Listing 3 shows the associated DTD file (called Classification.dtd for example):

<?xml version='1.0' encoding="UTF-8"?>
<!ELEMENT WMQRAClassification (wmqra_classification_info+)>
<!ATTLIST WMQRAClassification default_transaction_class CDATA #REQUIRED>
<!ATTLIST WMQRAClassification schema_version CDATA #REQUIRED>
<!ELEMENT wmqra_classification_info EMPTY>
<!ATTLIST wmqra_classification_info transaction_class CDATA #REQUIRED>
<!ATTLIST wmqra_classification_info selector CDATA #IMPLIED>
<!ATTLIST wmqra_classification_info description CDATA #IMPLIED>

This DTD file can also contain classification information for incoming IIOP, HTTP and MDB (monitoring non-WMQ queues) calls. Both the workload classification file and the DTD file together should be placed in any suitable location on the z/OS system. For this sample we placed them in a directory called /classification in the Application Server profile on the HFS file system.

Back to top

Configuring WebSphere Application Server from the Administrative Console

Next we need to configure the Application Server to utilize the zWLM function and the classification rules defined in the last section. The control region adjunct must be present after WebSphere Application Server starts. This is required for both MQ activation specification MDBs and the MQ resource adapter message selector function for zWLM.

1. In the adminstrative console select: Servers -> Server Types - WebSphere application servers - < server_name > - Messaging - WebSphere MQ CRA settings. Check the Start CRA box.
2. To use the zWLM function, you need to enable multiple servant regions. For this sample we will make three servant regions “startable”, one for each transaction class (and message priority type). However, you could tune these to suit your application requirements, for example with more servant regions if possible. Each transaction class runs in its own servant region. In the administrative console, select Servers -> Server Types - WebSphere application servers - < server_name > - Java and Process Management - Server Instance. Check the Multiple Instances Enabled box.
3. Set the Minimum Number of Instances and Maximum Number of Instances to 3 (as in Figure 2). Setting the minimum number in this way (rather than having a minimum of 1, say) ensures that all the servant regions are available after WebSphere Application Server start up. Otherwise the first request to a Transaction Class could take some time because the servant region would need to be started.
   
   Figure 2. Define the number of servant region instances
   
   
   
4. Set the wlm_classification_file environment variable to reference the workload classification document. You can set this variable at the cell, node, or server level. If you specify the cell or node level, the information contained in it must be accessible and applicable to all servers that inherit the specification from that cell or node. In the administrative console, select: Environment - WebSphere variables - New.
5. Make the Name wlm_classification_file and the Value: /WebSphere/Base/AppServer/profiles/default/classification/zwlm.xml.

Back to top

Configuring WebSphere Application Server and zWLM via TSO

This section shows how to configure zWLM to process the GOLD, SILVER, and BRONZE messages arriving from MQ through the control region adjunct, to be subsequently consumed in an appropriate servant region. Of course you would definite your actual user implementation based on application requirements with suitable goals specified.

Invoke the zWLM configuration interface in the z/OS command interface (TSO) by selecting 6. Command (or whatever number corresponds to ‘Command’) from the primary option menu. Then issue this command: iwmarin0

Defining the service classes

Next we create a service class for each message priority type’s (GOLD, SILVER, BRONZE) transaction class defined in the workload classification XML file. These service classes specify the goals for message processing in the respective servant regions for each type. For example the user might want to specify the target average response time of each transaction, or more usually target average response time with a percentile. The average response time is usually chosen because often, if the goal is unachievable and unrealistic, the zWLM function discards any attempt to achieve it.

For our example, we will create three service classes called MQGOLD, MQSILVER, and MQBRONZE, each with a goal of an average response time with a percentile. The GOLD has the fastest target response time.

1. Select (2) Extract definition from WLM couple data set as in Figure 3:
   
   Figure 3. Extract service definition for defining Service Classes
   
   
   
2. Then select (4) Service Classes as in Figure 4:
   
   Figure 4. Start defining the Service Class
   
   
   
3. Next create a new service class from any existing class by selecting an existing class and entering 1 for the action.
   
   Figure 5. Choose an existing Service Class to define a new one
   
   
   
4. Define the Service Class Name (MQGOLD in this example) with a Workload Name to group the classes together (WEB has been chosen here) and enter I under the action to insert the goal, as Figure 6 shows:
   
   Figure 6. Define the MQGOLD Service Class for GOLD messages
   
   
   
5. Now you choose the type of goal (response time with percentile) and define MQGOLD to be “90% of messages processed within 0.1 seconds”. Select 2 from the goal type menu as shown in Figure 7. On the subsequent goal data entry screen (Figure 8) you enter 90 as the Percentile and 0.1 as the Seconds. You can leave the Importance field as 1.
   
   Figure 7. Start defining the goal for MQGOLD based on response time with percentile
   
   
   
   
   Figure 8. Set goal to be 90% of messages processed within 0.1 second
   
   
   
   
   Figure 9. The Service Class and goal are now defined for GOLD messages
   
   
   

Repeat these steps for MQSILVER and MQBRONZE with suitable goals. Figure 10 shows that the three service classes are now defined:

Defining Component Broker (CB) classification rules

Next we need to create the CB classification rules. These rules essentially link the transaction classes (TC_1, TC_2, TC_3) with the service classes (MQGOLD, MQSILVER, MQBRONZE).

1. From the WLM Policy menu (see Figure 4) select (6) Classification Rules. Choose any existing rule to create the new CB classification rules (see Figure 11):
   
   Figure 11. Select any existing rule to create a new CB classification rule
   
   
   
2. Within the Classification Rule definition screen (Figure 12) define the Subsystem Type as CB. This step requires a default service class, for which messages of unknown priority type can be assigned. Set this class to MQBRONZE for our example. Place an I under Action for each of the three transaction classes to associate each transaction class name with their respective service class. Set the Type to bTC.
   
   Figure 12. Define the three CB classification rules
   
   
   

   Figure 13 shows the new set of CB classification rules.

   
   
   Figure 13. The new set of CB Classification Rules have been defined
   
   
   
3. Exit the zWLM function configuration, and select (2) Install definition on WLM couple data set and continue to install all the changes to the system.

Back to top

Conclusion

We’ve completed configuration of the system for a basic setup to enable priority message processing and workload management using the MQ resource adapter and the zWLM function across multiple servant regions. This configuration included:

• The JMS client application for WebSphere MQ
• The classification rules xml
• Transaction classes
• The Application Server configuration
• Service classes
• CB classification rules

When the JMS client application for MQ sends messages (for example to a MQ queue for consumption by MDBs running in WebSphere Application Server), it initiates three servant regions. Each servant region will have instances of the MDBs running within it and process (consume) messages from the MQ queue based on the messages priority type. So, all GOLD messages will be processed within servant region₁, all SILVER within servant region₂ and BRONZE in servant region₃. In addition, if there is competition for system resources, GOLD messages will take priority over SILVER and BRONZE due to the transaction goal specified in its service class.

Resources

Learn

• Understanding WAS for z/OS
  
  
• WebSphere Application Server for z/OS process model overview
  
  
• Information Center: Classifying z/OS workload
  
  
• Information Center: The WebSphere MQ resource adapter
  
  
• developerworks WebSphere on System z zone
  
  

Get products and technologies

• IBM Enterprise Modernization Sandbox for System z
  
  
• Trial: WebSphere MQ V7.0
  
  
• Trial: Rational™ Developer for System z V7.1
  
  

Discuss

• developerWorks forum: Destination z
  
  
• developerWorks forum: WebSphere MQ
  
  

About the author

Karl Gaffney works in the WebSphere Platform Messaging test team at the Husley Lab in England. He holds a PhD in Artificial Intelligence. Karl has worked at IBM for 9 years, a significant part of which has been testing the JMS messaging functionality of the WebSphere Application Server across a variety of platforms, as well as significant experience testing the interoperability of WebSphere Application Server and WebSphere MQ from a messaging perspective.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Configuring a JMS application for MQ message classification
• Defining classification rules
• Configuring WebSphere Application Server from the Administrative Console
• Configuring WebSphere Application Server and zWLM via TSO
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers