The workload classification document is a common XML file
that classifies inbound HTTP, IIOP, message-driven bean (MDB), and
mediation work for the z/OS® workload
manager.
Required elements
- <?xml version="1.0" encoding="UTF-8"?>
- Indicates that the workload classification document must be saved
in ASCII to be processed by the application server. This statement
is required.
- <!DOCTYPE Classification SYSTEM "Classifications">
- Provides the XML parser with the name of the DTD document that
is provided with the product, and that is used to validate the workload
classification document. The workload classification document that
you write must follow the rules that are described in this DTD. You
must add this statement to the workload classification document.
- Classification
- <Classification schema_version="1.0">
Indicates
the root of the workload classification document. Every workload classification
document must begin and end with this element. The schema_version
attribute is required. The only supported schema_version is 1.0. The
Classification element contains one or more InboundClassification
elements. For inbound service integration work, the Classification
element can also contain up to two SibClassification elements. If
classifying inbound messages for delivery to message-driven beans
using WebSphere® MQ messaging
provider activation specifications, the Classification element can
contain one or more WMQRAClassification elements.
- InboundClassification
- <InboundClassification type="iiop | http | mdb" schema_version="1.0"
default_transaction_class="value">
Use the following
rules when using the InboundClassification element:
- The type attribute is required. The value must be internal, iiop, http, mdb,
or sip. Only one occurrence of an InboundClassification
element can occur in the document for each type. There can be up to
five InboundClassification elements in a document. The types do not
have to be specified in a certain order in your classification document.
- The schema_version attribute is required. The value must
be set to 1.0.
- The default_transaction_class attribute must be specified,
and defines the default transaction class for work flows of the specified
type. The string value must be a valid WLM transaction class, a null
string (such as "") or a string that contains eight or fewer blanks
(such as " ").
- The InboundClassification elements cannot be nested. Each InboundClassification
element must end before the next InboundClassification element or
SibClassification element can begin.
- SibClassification
- <SibClassification type="jmsra | destinationmediation"
schema_version="1.0" default_transaction_class="value">
Use
the following rules when using the SibClassification element:
- The type attribute is required. The value must be jmsra
or destinationmediation. There can be at most one SibClassification
element in the document for each type. The types do not have to be
specified in a certain order in your classification document.
- The schema_version attribute is required. The value must
be set to 1.0.
- The default_transaction_class attribute must be specified,
and defines the default transaction class for work flows of the specified
type. The string value must be a valid WLM transaction class, a null
string (such as "") or a string that contains eight or fewer blanks
(such as " ").
- The SibClassification elements cannot be nested. Each SibClassification
element must end before the next InboundClassification element or
SibClassification element can begin.
- WMQRAClassification
- <WMQRAClassification schema_version=”1.0” default_transaction_class=”value”>
The
following rules apply to the WMQRAClassification element:
- The schema_version attribute is required. The value must
be set to 1.0.
- The default_transaction_class attribute must be specified,
and defines the default transaction class for work flows of the specified
type. The string value must be a valid WLM transaction class.
- The WMQRAClassification elements cannot be nested. Each WMQRAClassification
element must end before any other classification elements can begin.
The rules and XML statements for classifying different
types of work are very similar, but there is slightly different syntax
for each type. For more information about the syntax for each type
of work, see the following sections:
- InboundClassification
-
- SibClassification
-
- WMQRAClassification
-
Internal Classification
The
InboundClassification element with the attribute type="internal" defines
the section of the document that is applicable to internal work,
such as requests that are dispatched in a servant, that originate
in the owning controller. An example of this element follows:
<InboundClassification type="internal" schema_version="1.0"
default_transaction_class="value1">
If
an InboundClassification element with the type="internal" attribute
is not specified, internal work is classified using the rules that
are specified for IIOP work.
IIOP Classification
The InboundClassification
element with the attribute type="iiop" defines the section of the
document that is applicable to IIOP classification. An example of
this element follows:
<InboundClassification type="iiop" schema_version="1.0"
default_transaction_class="value1">
You
can classify IIOP work based on the following Java Platform, Enterprise Edition (Java EE) application artifacts:
- Application name
The name of the application that contains the
enterprise beans. It is the display name of the application, which
might not be the name of the .ear file that contains
all of the artifacts.
- Module name
The name of the EJB .jar file
that contains one or more enterprise beans. There can be multiple
EJB .jar files in an .ear file.
- Component name
The name of the EJB that is contained in a module
(or EJB .jar file). There can be one or more
enterprise beans contained in a .jar file.
- Method name
The name of a remote method on an EJB.
Classify IIOP work in various applications at any of these
levels by using the iiop_classification_info element.
- iiop_classification_info
<iiop_classification_info transaction_class="value1"
[application_name="value2"]
[module_name="value3"]
[component_name="value4"]
[method_name="value5"]
[description="value6"] >
With
the iiop_classification_info element, you can build filters based
on the application, module, component, and method names to assign
TCLASS values to inbound requests. Use the following rules when using
the iiop_classification_info element:
- The transaction_class attribute must be specified. The string
value must be a valid WLM transaction class, a null string (such as
"") or a string that contains eight or fewer blanks (such as " ").
By specifying a null or blank string, you can override a default TCLASS
setting, or a TCLASS setting that was assigned by a higher level filter.
Specifying a null or blank string means that you do not have a TCLASS
value for the request.
- The attributes application_name, module_name, component_name,
and method_name can be used as you need them. These attributes act
as selectors or filters that either assign a transaction class or
allow a nested iiop_classification_info element to assign the transaction
class. You can specify the values of these attributes in the following
ways:
- The exact name of the application, module, component, or method.
- A wild carded value. You can place an asterisk (*)
anywhere in a string to indicate that any string that starts with
the string preceding the asterisk and ends with the string that follows
the asterisk is considered a match. If the asterisk is at the end
of the string, any string that starts with the string preceding the
asterisk is considered a match.
Examples:
- The string Mar*61, matches Mar61, March61,
and Mar20early61, but does not match March81 or MAR61.
- The string MAR* matches MARCH, MAR61,
and MARS, but does not match Mar61 or MAY61.
Avoid trouble: The value comparisons
that are performed are case-sensitive.
gotcha
You can use any combination of these attributes to make a
classification filter. But you should only use the granularity that
is required. For example, if there is only one application on the
application server, the classification rules do not need to specify
the application_name attribute.
- The iiop_classification_info elements can be nested in a hierarchical
manner. By nesting the elements, you can create classification filters
that are based on the attribute values. The following filter classifies
requests on the EJB1 and EJB2 enterprise beans in the MyAPP1 application:
<iiop_classification_info transaction_class="FAST"
application_name="MyAPP1"
component_name="EJB1" />
<iiop_classification_info transaction_class="SLOW"
application_name="MyAPP1"
component_name="EJB2" />
The
following filter also classifies requests on EJB1 and EJB2 in the
MyAPP1 application, but also classifies requests on any other EJB
in the application:
<iiop_classification_info transaction_class="MEDIUM"
application_name="MyAPP1">
<iiop_classification_info transaction_class="FAST"
component_name="EJB1" />
<iiop_classification_info transaction_class="SLOW"
component_name="EJB2" />
</iiop_classification_info>
- If you specify an attribute value that conflicts with the parent
element's attribute value, the lower level filter is negated. An example
of a child value that conflicts with the parent element's attribute
value follows:
<iiop_classification_info transaction_class="FAST"
application_name="MyAPP1">
<iiop_classification_info transaction_class="SLOW"
application_name="MyAPP2" />
</iiop_classification_info>
In this example, EJB
Requests in MyAPP2 would never be assigned to transaction class "SLOW"
because the higher level filter only allows IIOP requests for application_name="MyAPP1"
to be passed through to the lower level filter.
- The first filter at a specific level that matches the attributes
of the request is used, not the best or most restrictive filter. Therefore,
the order that you specify filters is important.
<iiop_classification_info transaction_class="FAST"
application_name="MyAPP" />
<iiop_classification_info transaction_class="SLOW"
component_name="*" />
<iiop_classification_info transaction_class="MEDIUM"
component_name="MySSB" />
</iiop_classification_info>
In the preceding
example, all the IIOP requests that are processed by enterprise beans
in the MyAPP application are assigned a TCLASS value of SLOW. This
is true for any requests to the MySSB enterprise as well. Even though
MySSB is assigned a transaction class, the filter is not applied because
the first filter was applied and was assigned a TCLASS value of SLOW.
The remaining list of filters at the same level is ignored.
- The description field is optional. However, you should use a description
on all iiop_classification_info elements. The description string prints
as part of the operator command support so you can identify the classification
rules that are being used. Keep your descriptions reasonably short
because they are displayed in the MVS console.
HTTP classification
The InboundClassification
element with the attribute type="http" defines the section of the
document that is applicable to HTTP classification. An example of
this element follows:
<InboundClassification type="http"
schema_version="1.0"
default_transaction_class="value1">
HTTP
work can be classified based on the following J2EE artifacts:
- Virtual host name
Specifies the host name in the HTTP header
to which the inbound request is being sent.
- Port number
Specifies the port on which the HTTP catcher is
listening.
- URI (Uniform Resource Identifier)
The string that identifies
the Web application.
You can classify HTTP work in various applications at
any of these levels by using the http_classification_info element.
<http_classification_info transaction_class="value1"
[host="value2"]
[port="value3"]
[uri="value4"]
[description="value5"] >
With
the http_classification_info element, you can build filters based
on the host, port, and URI to assign TCLASS values to inbound requests.
Use the following rules when you use the http_classification_info
element:
- The transaction_class attribute must be specified. The string
value must be a valid WLM transaction class, a null string (such as
"") or a string that contains eight or fewer blanks (such as " ").
By specifying a null or blank string, you can override a default TCLASS
setting, or a TCLASS setting that was assigned by a higher level filter.
Specifying a null or blank string means that you do not have a TCLASS
value for the request.
- The attributes host, port, and uri can be used as you need them.
These attributes act as selectors or filters that either assign a
transaction class or allow a nested http_classification_info element
to assign the transaction class. You can specify the values of these
attributes in the following ways:
- The exact name of the host, port, or uri.
- Any value. To specify a match to any value, use the asterisk (*)
symbol.
- A wild carded value. You can place an asterisk (*)
anywhere in a string to indicate that any string that starts with
the string preceding the asterisk and ends with the string that follows
the asterisk is considered a match. If the asterisk is at the end
of the string, any string that starts with the string preceding the
asterisk is considered a match.
Examples:
- The string Mar*61, matches Mar61, March61,
and Mar20early61, but does not match March81.
- The string MAR* matches MARCH, MAR61,
and MARS, but does not match Mar61 or MAY61.
Avoid trouble: The value comparisons
that are performed are case-sensitive.
gotcha
Use any or all of these attributes to make a classification
filter. Only use the granularity that is required. For example, if
there is only one application on the application server, the classification
rules do not need to specify the uri attribute.
- You can nest the http_classification_info elements in a hierarchical
manner. You can construct filters based on attribute names. Consider
the two following filters:
<http_classification_info transaction_class="FAST"
host="MyVHost1.com"
uri="/MyWebApp1/*" />
<http_classification_info transaction_class="SLOW"
host="MyVHost2.com"
uri="/MyWebApp2/*" />
<http_classification_info transaction_class="MEDIUM"
host="MyVHost1.com">
<http_classification_info transaction_class="FAST"
uri="/MyWebApp1/*" />
<http_classification_info transaction_class="SLOW"
uri="/MyWebApp2/*" />
</http_classification_info>
Both filters classify
requests to Web applications that are identified by context roots
/MyWebApp1 and /MyWebApp2 in the application server that is hosting
web applications for virtual host MyVHost1.com. However, the second
filter also classifies requests on any other context root in the application
server.
- Specifying an attribute name that is different from the parent
element's attribute value effectively negates the lower level filter.
For example:
<http_classification_info transaction_class="FAST"
uri="/MyWebApp1/*">
<http_classification_info transaction_class="SLOW"
uri="/MyWebApp2">
</http_classification_info>
</http_classification_info>
This example would
never result in Web applications with a context root of /MyWebApp2
being assigned to the transaction class SLOW. The high level filter
only allows HTTP requests with a context root of /MyWebApp1/* to be
passed to a lower level filter.
- The first filter that is at a specific level is used, not the
best or most restrictive filter. Therefore, the order of the filters
at each level is important. For example:
<http_classification_info transaction_class="FAST"
host="MyVHost.com" />
<http_classification_info transaction_class="SLOW"
uri="*" />
<http_classification_info transaction_class="MEDIUM"
uri="/MyWebAppX/*" />
</http_classification_info>
In this example, HTTP
requests processed by the application server by the virtual host "MyVHost.com"
are assigned a TCLASS value of SLOW. Even requests to the Web application
with context root /MyWebAppX are assigned a TCLASS value of SLOW because
the filter was not applied. The first filter that matches is used
for the TCLASS assignment, and the remainder of the filters at the
same level is ignored.
- The description field is optional, however, you should use it
on all the http_classification_info elements. The description is displayed
when you monitor the transaction classes in the MVS console.
MDB classification
The InboundClassification
element with the attribute type="mdb" defines the section of the document
that applies to work for EJB 2.0 message-driven beans (MDBs) deployed
with listener ports. An example of this element follows:
<InboundClassification type="mdb"
schema_version="1.0"
default_transaction_class="qrs">
Each
InboundClassification element can contain one or more endpoint elements
with a messagelistenerport type defined. Define one endpoint element
for each listener port that is defined in the server that you want
to associate transaction classes with the message-driven bean. An
example of the endpoint element follows:
<endpoint type="messagelistenerport"
name="IPVListenerPort"
defaultclassification="MDBX"
description="ABC">
Use the following
rules when defining your endpoint elements:
- The type attribute must always equal messagelistenerport.
- The name attribute corresponds to the listener for your endpoint
element. The value of the name attribute must be the name of the listener
port that is specified in the administration console for the server.
- The defaultclassification element is the default transaction class
that is associated with the message-driven beans. The value of this
attribute overrides the default transaction classification value.
- The description field is optional, however, you should use it
on all the endpoint elements. The description is displayed when you
monitor the transaction classes in the MVS console.
Each endpoint element can have zero, one, or more classificationentry
elements. An example of a classification entry element follows:
<classificationentry
selector="Location='East'"
classification="MDB2"
description="XYZ" />
Use the selector attribute of the classificationentry
element to assign a transaction class to a message-driven bean that
has a selector clause in its deployment descriptor. Use the following
rules when defining your classificationentry elements:
- The value of the selector attribute must match exactly to the
selector clause in the MDB deployment descriptor.
- The value of the selector attribute must have the correct syntax
for an XML document. You must replace the < and > symbols
with the entity references < and >,
respectively. Similarly, if you use an apostrophe or quotation mark,
use the ' and " entity
references.
SIP Classification
The InboundClassification
element with the attribute type="sip" defines the section of the document
that sets the default transaction class for Session Initiation Protocol
(SIP) requests. An example of this element follows:
<InboundClassification type="sip" schema_version="1.0"
default_transaction_class="value1">
JMS RA classification
The SibClassification
element with the attribute type="jmsra" defines the section of the
document that applies to work for message-driven beans (MDBs) deployed
against JCA 1.5-compliant resources for use with the JCA resource
adapter (RA) of the default messaging provider. An example of this
element follows:
<SibClassification type="jmsra"
schema_version="1.0"
default_transaction_class="a">
Each
SibClassification element can contain one or more sib_classification_info
elements. An example of a classification entry element follows:
<sib_classification_info selector="'East'"
transaction_class="sibb"
selector="user.Location='East'"
bus="bigrred"
destination="abusqueue"
description="Some words" />
- selector
- Use the selector attribute of the sib_classification_info element
to assign a transaction class to a message-driven bean that has a
selector clause in its deployment descriptor. Use the following rules
when defining your sib_classification_info elements:
- The value of the selector attribute is an SQL expression that
selects a message according to the values of the message properties.
The syntax is that of a message selector in the JMS 1.1 specification,
but it can operate on SIMessage messages (more than JMS messages).
The syntax can select on system properties (including JMS headers,
JMSX properties, and JMS_IBM_properties) and user properties (which
must be prefixed by ".user" - for example, for the user property "Location",
the selector would specify "user.Location" as shown in the preceding
example). For more information, see the topic on working with message
properties.
- The value of the selector attribute must have the correct syntax
for an XML document. You must replace the < and > symbols
with the entity references < and >,
respectively. Similarly, if you use an apostrophe or quotation mark,
use the ' and " entity
references.
- bus
- The name of the service integration bus on which the target destination
is assigned. The classification applies to the bus named by this property,
or to any bus if you do not specify this property. The destinations
to which the classification applies depend on your use of the destination
property.
- destination
- The name of the target bus destination to which the message has
been delivered. This is the name of a queue or topic space. The classification
applies to the destination named by this property, or any destination
if you do not specify this property. The service integration buses
to which the classification applies depend on your use of the bus
property.
- discriminator
- The property applies only when the destination property names
a topic space. This discriminator value is then an XPath expression
that selects one or more topics within the topic space.
- description
- Although the description field is optional, you should use it
on all the sib_classification_info elements. The description is displayed
when you monitor the transaction classes in the MVS console.
Each sib_classification_info element can contain
one or more of these properties as needed to classify the work for
a message. A sib_classification_info element cannot contain more than
one instance of each property.
If a message matches several
sib_classification_info elements, the element that appears first is
used. For example, consider the following specifications:
<sib_classification_info bus="MyBus" transaction_class="a" />
<sib_classification_info destination="MyDest" transaction_class="b" />
A
message that arrives at destination MyDest from the service integration
bus MyBus is assigned the classification "a". A message that
arrives at MyDest from another bus is assigned the classification "b".
If
a message does not match any sib_classification_info element in an
enclosing SibClassification element, the message is assigned the default
classification from the SibClassification element.
If a message
does not match any sib_classification_info element in any SibClassification
element, or if no SibClassification elements are defined, all work
receives a built-in default classification with the value "SIBUS".
You must perform z/OS Workload
Manager actions that are required to use the TCLASS value "SIBUS",
as described in Classifying z/OS workload.
WebSphere MQ
messaging provider classification
The WMQRAClassification
element defines the section of the document that applies to work for
message-driven beans (MDBs) deployed against WebSphere MQ messaging provider activation
specifications. An example of this element follows:
<WMQRAClassification default_transaction_class="TC99" schema_version="1.0">
A
WMQRAClassification element can contain one or more wmqra_classification_info
elements. Two examples of wmqra_classification_info elements follow:
<wmqra_classification_info transaction_class="TC_3"
selector="JMSPriority>3 AND JMSPriority<8"
destination="queue://QMGR1/Q1"
queue_manager="QMGR1"
description="medium priorities with a queue manager name of QMGR1 and
a queue name of Q1 map to TC_3"/>
<wmqra_classification_info transaction_class="TC_4"
destination="topic://a/b/*"
description="Any topics starting with a/b/ map to TC_4"/>
- selector
- Use the selector attribute of the wmqra_classification_info element
to assign a transaction class to a message based on its properties.
This attribute can also be used to assign a transaction class to a
message-driven bean that has a selector clause in its deployment descriptor:
- The value of the selector attribute is an SQL expression that
selects a message according to the values of the message properties.
The syntax is that of a message selector in the JMS 1.1 specification.
- The value of the selector attribute must have the correct syntax
for an XML document. You must replace the < and > symbols
with the entity references < and >,
respectively. Similarly, if you use an apostrophe or quotation mark,
use the ' and " entity
references.
- destination
- A URI representing the WebSphere MQ destination to which the message
has been delivered. The classification applies to the destination
named by this property, or to any destination if you do not specify
this property. If the URI represents a queue type destination it can
optionally include a queue manager name, but that name is ignored
and is not be used for classification. If the URI represents a topic
type destination, it can make use of wildcards. For more information
on wildcard support with WebSphere MQ
see the WebSphere MQ information
center.
- queue_manager
- The name of the WebSphere MQ
queue manager to which the message has been delivered. The classification
applies to the queue manager named by this property, or to any queue
manager if you do not specify this property. The queue manager name
must conform to WebSphere MQ
naming conventions.
- Note that this field must not be set to the name of a WebSphere MQ queue sharing
group. Instead, you must either create a wmqra_classification_info
element for every queue manager in the queue sharing group, or base
the classification on something else such as the destination attribute.
- description
- Although the description field is optional, you must use it on
all the wmqra_classification_info elements.
Each wmqra_classification_info element can contain
one or more of these properties as needed to classify the work for
a message. A wmqra_classification_info element cannot contain more
than one instance of each property.
If a message matches several
wmqra_classification_info elements, the element that appears first
is used. For example, consider the following specifications:
<wmqra_classification_info queue_manager="QMGR1" transaction_class="TC_1" />
<wmqra_classification_info destination="queue:///Q1" transaction_class="TC_2" />
A message that arrives at destination Q1 on queue
manager QMGR1 is assigned the classification "TC_1". A message
that arrives at Q1 from another queue manager is assigned the classification "TC_2".
If
a message does not match any wmqra_classification_info element in
an enclosing WMQRAClassification element, the message is assigned
the default classification from the WMQRAClassification element.
If there are multiple WMQRAClassification elements, the default transaction
class from the first WMQRAClassification element is used.
If
no WMQRAClassification elements are defined, all work receives the
default classification "WMQRA". You must perform z/OS Workload Manager actions that are required
to use the TCLASS value "WMQRA", as described in Classifying z/OS workload.