A graphical interface for monitoring and maintenance of Sun SeeBeyond JMS IQ Manager (Message Server), JMS Destinations, and messages is integrated into the Enterprise Manager Web User Interface. Figure 10-13 calls out components of that interface. Various aspects of the Enterprise Manager are exhibited in examples throughout both parts of the book. Specific aspects of the Enterprise Manager that can be used to manage and monitor the IQ Manager are discussed in this chapter to review and summarize available facilities.

Figure 10-13. Components of the JMS queue and message management interface in the Enterprise Manager

The illustration in Figure 10-13 shows some aspects of JMS monitoring available through the Enterprise Manager. The connectivity map of each deployed enterprise application is shown in the explorer-like tree at the left. Expanding the tree from the Servers node down to the connectivity map and clicking on the connectivity map name will present the connectivity map graphic at the right. Any JMS Destinations present in the connectivity map are active components. Clicking one of the JMS Destinations in the connectivity map graphic will break the right pane into two sections, with the bottom section displaying the JMS Destination summary for the destination and the list of messages, if any, currently queued in that destination.

Content of messages in the destination can be viewed if the payload type supports display of message content. Typically, text, bytes, and map messages can be viewed. Stream messages cannot be viewed. Figure 10-14 illustrates viewing the content of a text message.

Figure 10-14. Content of a JMS text message

Regardless of message type, message header properties can be viewed, including user-defined JMS header properties, if any, as shown in Figure 10-15.

Figure 10-15. JMS message properties

Message content, for messages of suitable type, can be altered in place (text messages only), as illustrated in Figure 10-16.

Figure 10-16. Modifying the content of a JMS text message using the Enterprise Manager

Messages of suitable type can be injected directly into the JMS Destination (text and bytes messages only), as shown in Figure 10-17.

Figure 10-17. Injecting messages into JMS Destinations using the Enterprise Manager

Messages in the destination can be selected, individually or as a group, and deleted, as illustrated in Figure 10-18.

Figure 10-18. Tools for deleting JMS messages through the Enterprise Manager

If JMS journaling is enabled, messages consumed by components can be seen, modified, and resubmitted from the Journaled Messages view, as seen in Figures 10-19 and 10-20.

Figure 10-19. Switching between Live and Journaled Messages view

Figure 10-20. Viewing journaled messages

In addition to accessing JMS Destinations through their connectivity map representation, you can interact with JMS Destinations and subscribers through the Sun_SeeBeyond_JMS_IQ_Manager node in the explorer tree, as shown in Figure 10-21.

Figure 10-21. Selecting the Sun SeeBeyond JMS IQ Manager to manage the JMS Message Server and its queues, topics, messages, and so on

All queues and all topics as well as logging and alerts for the JMS Message Server can be seen and manipulated.

In Queues or Topics view, messages in a selected queue or topic can be manipulated much the same way as in the Connectivity Map view, as shown in Figure 10-22. In this view, queues and topic can also be created and deleted.

Figure 10-22. Sun SeeBeyond IQ Manager Queues interface in the Enterprise Manager

In Topics view, subscriptions to the topic can be deleted and durable subscriptions can be created, as shown in Figure 10-23.

Figure 10-23. Sun SeeBeyond JMS IQ Manager Topics interface in the Enterprise Manager

In addition to the Web-based User Interface, Sun SeeBeyond JMS implementation provides a command-line utility, stcmsctrlutil, which can be used to manage and monitor the Sun SeeBeyond Message Server. The invocation syntax and options depend on the functionality that is required. Some sample commands and their output are reproduced in Listings 10-1 through 10-11. See [JMSREF] for additional details of this interface.

c:>cd c:JCAPS512logicalhostisstcmsin

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil -?
Usage: stcmsctrlutil
         [-username user name] [-userpassword user password]
         [--version] [-msversion] [-shutdown] [-status]
         [-topiclist] [-sublistall] [-sublistfortopic topic]
         [-topicstat topic] [-queuelist]
         [-recvlistforqueue queue] [-recvlistall]
         [-queuestat queue] [-host host-name]
         [-port port-number] [-offset port-offset]
         [-createtopic topic] [-deletetopic topic]
         [-createqueue queue] [-deletequeue queue]
         [-createsub topic sub client]
         [-deletesub topic sub client]
         [-qmsglist queue seqNo nmsgs]
         [-tmsglist topic seqNo nmsgs] [-qmessage queue seqNo]
         [-tmessage topic seqNo] [-deltmsg topic seqNo]
         [-delqmsg queue seqNo] [-changetmsg topic seqNo]
         [-changeqmsg queue seqNo] [-msgtype type]
         [-locktopic topic] [-unlocktopic topic]
         [-lockqueue queue] [-unlockqueue queue]
         [-tmimport topic seqNo nmsgs]
         [-qmimport queue seqNo nmsgs] [-journaler]
         [-archiver dir command] [-backup file date]
         [-timeout seconds] [-locale Unicode|locale-name]
         [-txlist] [-isjournalenabled] [--help]

Listing 10-2 demonstrates the command used to show the Sun SeeBeyond JMS IQ Manage status and the output of this command.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
    -username Administrator -userpassword STC ^
    -port 20007 -status
Up since: Thu Jan 25 05:40:35 2007
Memory used by data messages: 369.440 K(Bytes)
Total messages passed through: 1776
Total messages retained: 907
Number of message queue(s): 16
Number of connection(s): 36
Port number: 20007
Process ID: 3976
Server state: Ready and running...

Listing 10-3 shows the command used to list all JMS queues and its output.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
        -username Administrator ^
        -userpassword STC -port 20007 -queuelist
Number Of Queue(s): 9
Queue List:
        qB
        qD
        qZ
        qA
        qFeeder
        qC
        STCMS.Alert
        qSource
        qDestination

Listing 10-4 shows the command used to list all receivers that receive from a particular queue and its output.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
        -username Administrator -userpassword STC ^
        -port 20007 -recvlistforqueue qSource
Number Of Receiver(s): 3
Receiver ID: 10543568
Receiver ServerID: 1432937827,374 (no name)
        Queue name: qSource
        Session ID: 1169664042339
        Committed messages: 1
        Uncommitted messages: 0
        Message selector:
Receiver ID: 10541648
Receiver ServerID: 1432937828,375 (no name)
        Queue name: qSource
        Session ID: 1169664042340
        Committed messages: 0
        Uncommitted messages: 0
        Message selector:
Receiver ID: 17186424
Receiver ServerID: 1432937829,376 (no name)
        Queue name: qSource
        Session ID: 1169664042341
        Committed messages: 0
        Uncommitted messages: 0
        Message selector:

Listing 10-5 shows the command used to obtain statistics for a particular queue and its output.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
        -username Administrator -userpassword STC ^
        -port 20007 -queuestat qSource
Queue Name: qSource
First enqueue time: 01252007:10:18:22
Last enqueue time: 01252007:10:18:22
Number of current receivers: 3
Message count: 0
Messages sent and committed: 5
Min sequence Number: 5
Max sequence Number: 5
Suspended: No

Listing 10-6 shows the command used to obtain a detailed list of all messages in a particular queue and its output.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
        -username Administrator -userpassword STC ^
        -port 20007 -qmsglist qDestination 0 100
Number Of Messages(s): 2
Message[1]:
Message.SeqNo=3
Message.Size=367
Message.PayloadSize=20
Message.BodySize=1
Message.EnqueueTime=01242007:23:11:55
Message.JMSProperty.CI=Sun-SeeBeyond
Message.JMSProperty.DM=2
Message.JMSProperty.DN=qDestination
Message.JMSProperty.EX=0
Message.JMSProperty.MI=ID:e8ebf:1105568e526:f88:c0a83e87:11056613422:335a9fa
81105568b08778c1
Message.JMSProperty.PR=4
Message.JMSProperty.RD=False
Message.JMSProperty.TS=01242007:23:11:55
Message.JMSProperty.TY=Text

Message[2]:
Message.SeqNo=4
Message.Size=367
Message.PayloadSize=20
Message.BodySize=1
Message.EnqueueTime=01242007:23:18:25
Message.JMSProperty.CI=Sun-SeeBeyond
Message.JMSProperty.DM=2
Message.JMSProperty.DN=qDestination
Message.JMSProperty.EX=0
Message.JMSProperty.MI=ID:1a3d3:1105568e582:f88:c0a83e87:1105667290f:335a9fa
81105568b0877823
Message.JMSProperty.PR=4
Message.JMSProperty.RD=False
Message.JMSProperty.TS=01242007:23:18:25
Message.JMSProperty.TY=Text

Listing 10-7 gives an example of a command that shows content of the message with a specific sequence number in a specific queue and its output.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
        -username Administrator -userpassword STC -port 20007 ^
        -qmessage qDestination 3
test message 4

Listing 10-8 provides an example of a command that deletes a message with a specific sequence number from a specific queue and its output.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
        -username Administrator -userpassword STC ^
        -port 20007 -delqmsg qDestination 3
Message: 3 has been deleted

Listing 10-9 shows an example command that can be used to determine if message journaling is enabled on the server and its output.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
        -username Administrator -userpassword STC ^
        -port 20007 -isjournalenabled
Journal server is enabled

Most commands can be supplemented with the “–journaler” flag to display information about the message journal if journaling is enabled. For example, the command in Listing 10-10 displays queue statistics for the journaled queue.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
        -username Administrator -userpassword STC ^
        -port 20007 -journaler -queuestat qSource
Queue Name: qSource
First enqueue time: 01252007:08:52:24
Last enqueue time: 01252007:10:18:22
Number of current receivers: 0
Message count: 0
Messages sent and committed: 0
Min sequence Number: 4
Max sequence Number: 4

Listing 10-11 shows a command used to list journaled queues and its output.

C:JCAPS512logicalhostisstcmsin>stcmsctrlutil ^
        -username Administrator -userpassword STC ^
        -port 20007 -journaler -queuelist
Number Of Queue(s): 7
Queue List:
        qChildOut
        qChildrenIn
        qSource
        qFeeder
        qA
        qC
        qEater

In addition to obtaining information about JMS Destinations and messages, creating and removing JMS Destinations and messages, modifying queued messages, and operating on journaled information, the utility allows backing up of live and journaled messages and browsing backup archives.

[JMSREF] discusses the use of the stcmsctrlutil utility with additional examples.

Sun SeeBeyond JMS Message Server can also be monitored and managed using the JMS interface, discussed later in this chapter. The following JMX MBean, under the com.sun.appserv domain, provides access to much the same functionality as the Enterprise Manager User Interface and the stcmsctrlutil:

type=messaging-server-admin-mbean,jmsservertype=stcms,name=Sun_SeeBeyond_JMS_IQ_Manager

Which method of monitoring and managing the Sun SeeBeyond IQ Manager is the most appropriate will depend on the circumstances. The Enterprise Manager is easy to use and eminently visual. The stcmsctrlutils can be used in command scripts. The JMX interface can be used in Java-based applications or JMX-capable enterprise monitoring and management tools.

When installed, Alert Agent is configured through the AlertAgent node of the Java CAPS Enterprise Manager, as shown in Figure 10-24.

Figure 10-24. AlertAgent in the Enterprise Manager

Alert Agent receives all alerts as they occur. Alert Agent configuration determines what it does with alerts, if anything.

The Alert Agent Channel is the mechanism through which alerts are delivered to a destination.

Note

Unless at least one channel is defined, no notifications can be defined and therefore no alerts will be delivered.

Three types of channels can be configured: SMTP (electronic mail), JMS, and SNMP (network management).

An SNMP Channel always delivers to the SNMP Agent; therefore, there is little point in defining more than one channel of this type. This channel has no additional configuration; see Figure 10-25.

Figure 10-25. AlertAgent SNMP Channel configuration

Configuring an SNMP Channel allows Java CAPS Alerts to be delivered to a third-party enterprise-monitoring system that supports SNMP v2 Traps. Note that exactly one recipient that uses the SNMP Channel must be configured, and exactly one destination and one or more notifications must be configured, before alerts are delivered to the SNMP Agent. This is discussed later.

Any number of SMTP Channels can be defined. Each such channel would typically be configured to use a different mail server account. Only one SMTP Channel per mail server account is required. Any number of mail recipients can be configured as alert recipients using one mail server account. This configuration is performed using the Recipients tab, discussed later.

Each “e-mail” channel requires additional configuration. The SMTP Server’s host, port, account, and password, as well as whether or not to use Secure Sockets Layer (SSL) for the transport, must be configured as necessary; see Figure 10-26. Some SMTP Servers do not require login for sending mail and therefore do not require the account to be configured.

Figure 10-26. AlertAgent SMTP Channel configuration

By default, the sender of alerts is preconfigured to be JavaCAPSAlertAgent @sun.com. Sites may wish to change this to something more appropriate for them. The property senderEmailAddress is configured in the properties file:

<EMInstallRoot>/emanager/server/monitor/config/alertagent.properties

Configuring one or more SMTP Channels allows Java CAPS Alerts to be delivered to electronic mail recipients. Note that one or more recipients that use the SMTP Channel must be configured, and at least one destination and notification must be configured to use the recipient, before alerts are delivered to the SMTP Server. This is discussed later.

The JMS Channel defines an association between the Alert Agent JMS Channel and the JMS Message Server to which to deliver alerts using JMS. One JMS Channel would be defined for each different JMS Message Server instance, as shown in Figure 10-27. The JMS Message Server would ideally be different from the one used by the domain being monitored.

Figure 10-27. AlertAgent JMS Channel configuration

Configuring one or more JMS Channels allows Java CAPS Alerts to be delivered to JMS-based infrastructure. Note that one or more recipients that use the JMS Channel must be configured, and at least one destination and notification must be configured to use the recipient, before alerts are delivered to the JMS Message Server. This is discussed later.

Once all channels are defined, they can be used to define alert recipients. Except for the SNMP Channel, which only reasonably needs one recipient, there can be one or more recipients using each of the SMTP and JMS Channels.

Each SMTP Recipient defines the association between the SMTP Channel, defined earlier, and an electronic mail address of a recipient to whom electronic mail will be sent using the mail server and account defined by the SMTP Channel. This is illustrated in Figure 10-28.

Figure 10-28. Associating a recipient with an SMTP Channel

Each JMS Recipient defines the association between the JMS Channel, defined earlier, and the JMS topic to which alert messages will be sent using the JMS Message Server defined by the JMS Channel, as illustrated in Figure 10-29.

Figure 10-29. Associating a recipient with a JMS Channel

Note that the “Recipient Address” in this case is the name of the JMS topic. If the topic does not have at least one durable subscriber or at least one active nondurable subscriber, all messages delivered to the topic will be silently discarded by the JMS Message Server.

For a SNMP Channel the Recipient Address value will be the literal “SNMP.”

Whereas channels and recipients together define alert delivery endpoints, an Alert Agent Destination is a logical grouping of recipients. The destination name is used in configuring notifications, discussed later. The collection of recipients defined through the destination will receive the same alerts. A destination can include any number of recipients of different types.

Alert Agent Notification defines an association between an alert filter and a destination to which to send alerts that satisfy the filter criteria. While Alert Agent documentation does not use the term filter, Notification is a filtering expression combined with the destination.

Notification allows filtering of alerts by type, severity, and component.

The all-encompassing type CODE-00001 denotes all alert types. Alert types are added by Java CAPS products at installation time and are stored in various property files under

<EMInstallRoot>/emanager/server/monitor/alertcodes

Note

Not all endpoints support alerts. See property files in the alertcodes directory and its subdirectories for property files corresponding to various endpoints and alert values they define.

Note

Stopping and starting a Web Services provider generates no alerts.

Note

Starting and stopping eInsight Business Processes generates no alerts.

Some of the alert types, corresponding to components in the installation used for the examples in this book, and alert message templates used by them, are enumerated in Table 10-1.

A JMS Recipient definition associates a JMS Message Server and a JMS topic within that server. When used as part of the destination and notification definitions, the JMS topic on the specified JMS Message Server will receive alert messages. It is expected that at some point a solution that processes these alerts will be developed and deployed.

Severity filters ensure that only alerts of specific severity, and more severe, are included in notifications.

Given a project hierarchy, all of the components, or only selected components, can be included in the notification definition. Figure 10-30 illustrates component selection from the component hierarchy.

Figure 10-30. Selection of component from component hierarchy

Finally, once filtering criteria are specified, one or more destinations can be specified to identify notification targets, as illustrated in Figure 10-31.

Figure 10-31. Selecting notification targets

By defining multiple recipients, destinations, and notification filters, a site can develop an event notification schema of desired complexity.

Some problems, such as database connection credential issues, arise before Java Collaborations are invoked. Alert Agent can be used to provide real-time notification of the occurrence of these kinds of problems.

Chapter 8, section 8.2.2.1, “Simple Alert Processor for a JMS Channel,” and section 8.2.2.2, “Catching ‘Uncatchable’ Exceptions,” in Part II provide examples of Java CAPS solutions that handle alerts sent to a JMS Channel by the Alert Agent, and catch and process “uncatchable” exceptions, ones thrown by code that surrounds Java collaborations.

Java CAPS Alert Agent can be used to forward notable events, generated by Java CAPS infrastructure and solutions, to electronic mail, JMS, and SNMP recipients in real time. By creating appropriate notification definitions, sites can establish convenient early warning systems, minimizing “time to discover” and “time to resolve” when problems occur. In case of exceptions relating to inability to establish a connection with an external resource, for container-managed connections, Alert Agent may be the only way to alert operations staff of an occurrence of a connection problem. If Alert Agent–based infrastructure is configured, components of Java CAPS solutions can explicitly generate custom alerts, to be handled in the same manner as other alerts, to notify operations and administration staff or enterprise-monitoring systems about business-level events of interest.

SNMP Agent is an optional component. Since it can depend on the Alert Agent, another optional component, both the SNMP Agent and optionally the Alert Agent must be installed and configured. See Chapter 3 of the SNMP Agent User’s Guide and Chapter 4 of the Alert Agent User Guide for installation details.

Once installed, both the Alert Agent and the SNMP Agent nodes are added to the J2EE hierarchy in the JCAPS Enterprise Manager; see Figure 10-33. To gain access to the SNMP Agent’s configuration, expand the SNMP Agent node and click on the Configuration tab.

Figure 10-33. SNMP Agent configuration

Settings enumerated in Table 10-2 furnish additional information.

Traps to be sent by the SNMP Agent are configured in the Java CAPS Enterprise Manager as per the SNMP Agent and Alert Agent documentation. The diagram in Figure 10-34 shows the flow of SNMP Trap Events.

Figure 10-34. Flow of SNMP Trap Events

The Java CAPS SNMP Agent sends events as SNMPv2c Traps to the enterprise management system. The only major decision you need to make is where to do the filtering of events: in Java CAPS or a third-party network management system.

An example of a Java CAPS SNMP Agent Trap, captured by a packet sniffer, is shown in Figure 10-35.

Figure 10-35. A SNMP Agent Trap

The SNMP Agent Listener is configured in the Java CAPS Enterprise Manager as per the SNMP Agent documentation. It exposes a number of properties for management using SNMPv3 requests.

The diagram in Figure 10-36 shows the flow of SNMP management and monitoring information. Note that all requests start from the network management system.

Figure 10-36. Flow of SNMP information

Usernames, passwords, and community names must match for the SNMP Agent to work correctly with the network management system. You can choose usernames, passwords, and community names as long as the relationships shown in Figure 10-37 are maintained.

Figure 10-37. Relationships between property values in Java CAPS and SNMP components

Note

Some SNMP tools enforce the SNMPv3 minimum password length of 8 characters. The Java CAPS SNMP Agent does not.

Most of the base configuration is stored in the following two files:

<JCAPSInstallRoot>/emanager/server/monitor/snmpagent/config/SnmpAgent.xml
<JCAPSInstallRoot>/emanager/server/monitor/snmpagent/config/snmpagent.properties

The Java CAPS SNMP structures are defined in the MIB file:

<JVAPSInstallRoot>/emanager/server/monitor/snmpagent/mibs/CAPS51-MIB.txt

Note

The SNMP version can be manually changed in the SnmpAgent.xml file for SNMP Agent Listener but not for SNMP Agent Traps.

Note

The directory snmpagent and its subdirectories will only exist if the SNMP Agent is installed.

A log of SNMP-related activities is merged into the Enterprise Manager log, typically found in:

<JCAPSInstallRoot>/emanager/server/logs

To increase logging of SNMP Agent–related events, it is necessary to modify the log4j.properties file:

<JCAPSInstallRoot>/emanager/server/conf/log4j.properties

Setting the logging categories listed in Listing 10-12 to debug will show details of SNMP messaging.

com.stc.eventmanagement
com.stc.snmpagent.webservices
com.stc.snmpagent

The Service Manager Service returns an array of Enterprise Manager Web Service listeners, or fails. Given a SOAP Request, shown in Listing 10-20, the service returns, in the book development environment, the response shown in Listing 10-21.

<soapenv:Envelope
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:soap="http://soap.ws.services.em.egate.stc.com">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:getAvailableServices
     soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
   </soapenv:Body>
</soapenv:Envelope>

<soapenv:Envelope
       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <ns1:getAvailableServicesResponse
       soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
       xmlns:ns1="http://soap.ws.services.em.egate.stc.com">
         <getAvailableServicesReturn
             soapenc:arrayType="soapenc:string[2]"
             xsi:type="soapenc:Array"
             xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
            <getAvailableServicesReturn
               xsi:type=
         "soapenc:string">RuntimeService51x</getAvailableServicesReturn>
            <getAvailableServicesReturn
               xsi:type=
         "soapenc:string">AlertService51x</getAvailableServicesReturn>
         </getAvailableServicesReturn>
      </ns1:getAvailableServicesResponse>
   </soapenv:Body>
</soapenv:Envelope>

It may or may not be worthwhile knowing that these services are running. When the Enterprise Manager Agent Server is not running, none of the Enterprise Manager Web Services will be available.

All operations of the Runtime Service and the Alert Service require a Session ID parameter. The Login Service’s only operation, openSession, requires a username and a password. Listing 10-22 shows a sample SOAP Request invoking the openSession operation with credentials.

<soapenv:Envelope
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:soap="http://soap.ws.services.em.egate.stc.com">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:openSession
       soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <name xsi:type="soapenc:string"
               xmlns:soapenc=
        "http://schemas.xmlsoap.org/soap/encoding/">Administrator</name>
         <password xsi:type="soapenc:string"
               xmlns:soapenc=
        "http://schemas.xmlsoap.org/soap/encoding/">STC</password>
      </soap:openSession>
   </soapenv:Body>
</soapenv:Envelope>

In response to this request, the Login Service returns the Session ID that can be used when invoking Runtime and Alert services. Listing 10-23 shows the SOAP Response.

<soapenv:Envelope
       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <ns1:openSessionResponse
       soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
       xmlns:ns1="http://soap.ws.services.em.egate.stc.com">
         <openSessionReturn
             xsi:type="soapenc:string"
             xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
D134E3B637D819749A8A30FDD1C3BBB5</openSessionReturn>
      </ns1:openSessionResponse>
   </soapenv:Body>
</soapenv:Envelope>

Regardless of whether credentials are valid, a Session Id is returned. If the credentials are invalid, the Session ID will be rejected and another SOAP Fault will be returned—for example, an insufficient privileges message when another service attempts to use it. Listing 10-24 shows a SOAP Fault returned in response to a request with invalid credentials.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Server.userException</faultcode>
         <faultstring>
java.rmi.RemoteException: User does not have privileges for requested operation.
         </faultstring>
         <detail>
            <ns1:hostname xmlns:ns1="http://xml.apache.org/axis/">
MCZ01</ns1:hostname>
         </detail>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

Both Runtime and Alert services implement closeSession operations. One of these operations should be invoked to close and invalidate the management session opened by the invocation of the openSession operation of the Login Service.

Note that Session ID does not survive Enterprise Manager Agent Service restart. If an invalid Session ID is used, a SOAP Fault is returned, as illustrated in Listing 10-25.

<soapenv:Envelope
       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Server.userException</faultcode>
         <faultstring>
java.rmi.RemoteException: Session not found for:D134E3B637D819749A8A30FDD1C3BBB5
         </faultstring>
         <detail>
            <ns1:hostname xmlns:ns1=
                     "http://xml.apache.org/axis/">MCZ01</ns1:hostname>
         </detail>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

At runtime the Integration Server may support many Java CAPS projects deployed and executing concurrently. Operational reasons may dictate that some components need to be stopped and started automatically. The execution state of components may need to be confirmed at intervals to satisfy the dictates of the operational monitoring policy of the site. A third-party enterprise monitoring solution may need to obtain status information for runtime components.

The Runtime Service supports such requirements by providing access to the list of components executing within the Integration Server, obtaining their state and status and starting and stopping them programmatically.

To successfully invoke any of the Alert Service Web Services operations, the invoker must have a valid Session ID. Session ID is obtained by invoking the Login Service’s openSession operation; see section 10.2.8.2.

Let’s invoke the service operation getComponentList to obtain the list of components visible to the Enterprise Manager. Listing 10-26 shows a sample request.

<soapenv:Envelope
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:soap="http://soap.ws.services.em.egate.stc.com">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:getComponentsList
       soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <sessionId
            xsi:type="soapenc:string"
            xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
BB0396DF02BBB43932872B597BFDFA7A</sessionId>
      </soap:getComponentsList>
   </soapenv:Body>
</soapenv:Envelope>

The response looks like that shown in Listing 10-27.

<soapenv:Envelope
      xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/
      xmlns:xsd=http://www.w3.org/2001/XMLSchema
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <ns1:getComponentsListResponse
         soapenv:encodingStyle=
                 "http://schemas.xmlsoap.org/soap/encoding/"
         xmlns:ns1=http://soap.ws.services.em.egate.stc.com>
         <getComponentsListReturn
               soapenc:arrayType="xsd:anyType[10]"
               xsi:type="soapenc:Array"
               xmlns:soapenc=
                    "http://schemas.xmlsoap.org/soap/encoding/">
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000     is51x
            </getComponentsListReturn>
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000|Sun_SeeBeyond_JMS_IQ_Manager     jms51x
            </getComponentsListReturn>
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|cXAOra_1
ORACLEADAPTER.ExternalApplication
            </getComponentsListReturn>
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|cXAOra_2
ORACLEADAPTER.ExternalApplication
            </getComponentsListReturn>
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|svc_bpUp
dateXA    BPMS.BusinessProcessRepositoryObject
            </getComponentsListReturn>
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|svc_jcdU
pdateXA     jce.JavaCollaborationDefinition
            </getComponentsListReturn>
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|svc_jcdU
pdateXA|svc_jcdUpdateXA_cXAOra_1     ORACLEADAPTER.ExternalApplication.LINK
            </getComponentsListReturn>
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|svc_jcdU
pdateXA|svc_jcdUpdateXA_cXAOra_2     ORACLEADAPTER.ExternalApplication.LINK
            </getComponentsListReturn>
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|wssWebSe
rviceApplication     WSSoapHttpApplication.WSSoapHttpApplication
            </getComponentsListReturn>
            <getComponentsListReturn xsi:type="soapenc:string">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|wssWebSe
rviceApplication|wssWebServiceApplication_svc_bpUpdateXA
WSSoapHttpApplication.WSSoapHttpApplication.LINK
         </getComponentsListReturn>
         </getComponentsListReturn>
      </ns1:getComponentsListResponse>
   </soapenv:Body>
</soapenv:Envelope>

Component paths such as the following, required to invoke other Runtime Service operations, can be obtained through the Enterprise Manager:

e51x|Servers|localhost
:20000|__Bo
ok|Examples
|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|wssWebServiceApplication|wssWebServiceApplication_svc_bpUpdateXA

The Java Collaboration service svc_jcdUpdateXA belongs to the connectivity map cmWSSPXA in deployment profile dpWSSPXA in project __Book/Examples/ WSSPXA/DPs, as shown in Figure 10-38.

Figure 10-38. Component path in Enterprise Manager

Component types, also required to invoke component-specific operations, must be obtained by invoking the getComponentList operation and inspecting the result for the component in question. For example, let’s query the status of component

e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|svc_jcdUpdateXA

of type

jce.JavaCollaborationDefinition

The request is shown in Listing 10-28.

<soapenv:Envelope
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:soap="http://soap.ws.services.em.egate.stc.com">
   <soapenv:Header/>
   <soapenv:Body>
    <soap:getStatus soapenv:encodingStyle=
                                "http://schemas.xmlsoap.org/soap/encoding/">
     <sessionId xsi:type="soapenc:string" xmlns:soapenc=
                                "http://schemas.xmlsoap.org/soap/encoding/">
BB0396DF02BBB43932872B597BFDFA7A
     </sessionId>
     <component xsi:type="soapenc:string"
         xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|svc_jcdUpdateXA
     </component>
     <componentType
         xsi:type="soapenc:string"
         xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
jce.JavaCollaborationDefinition
     </componentType>
    </soap:getStatus>
   </soapenv:Body>
</soapenv:Envelope>

The response is shown in Listing 10-29.

<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
    <ns1:getStatusResponse soapenv:encodingStyle=
                                     "http://schemas.xmlsoap.org/soap/encoding/"
                           xmlns:ns1="http://soap.ws.services.em.egate.stc.com">
     <getStatusReturn href="#id0"/>
    </ns1:getStatusResponse>
    <multiRef id="id0" soapenc:root="0" soapenv:encodingStyle=
              "http://schemas.xmlsoap.org/soap/encoding/"
          xsi:type="ns2:Map" xmlns:ns2="http://xml.apache.org/xml-soap"
          xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
     <item>
      <key xsi:type="soapenc:string">HostAndPort</key>
      <value xsi:type="soapenc:string">localhost:20000</value>
     </item>
     <item>
      <key xsi:type="soapenc:string">System</key>
      <value xsi:type="soapenc:string">e51x</value>
     </item>
     <item>
      <key xsi:type="soapenc:string">Component</key>
      <value xsi:type="soapenc:string">
e51x|Servers|localhost:20000|__Book|Examples|WSSPXA|DPs|dpWSSPXA|cmWSSPXA|svc_jcdUpdateXA
      </value>
     </item>
     <item>
      <key xsi:type="soapenc:string">State</key>
      <value xsi:type="soapenc:string">Up</value>
     </item>
    </multiRef>
   </soapenv:Body>
</soapenv:Envelope>

If the component is not deployed or is disabled, the SOAP Fault response will be returned. This response is quite misleading, as it states that the component type is invalid for the component rather than saying that the component does not exist, as shown in Listing 10-30.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <soapenv:Body>
                <soapenv:Fault>
                        <faultcode>soapenv:Server.userException</faultcode>
                        <faultstring>
java.rmi.RemoteException: Invalid componentType: jce.JavaCollaborationDefinition f
or component: e51x|Servers|localhost:20000|__Book|SystemManagement|Programmatic|JM
SPassThrough|dpJMSPassThrough|cmJMSPassThrough|svc_jcd_00</faultstring>
                        <detail>
                       <ns1:hostname xmlns:ns1="http://xml.apache.org/axis/">
MCZ01
                       </ns1:hostname>
                        </detail>
                </soapenv:Fault>
        </soapenv:Body>
</soapenv:Envelope>

Components can be stopped and started using appropriate operations. What is unclear is whether there are any limitations as to what kind of components can be managed this way. It would appear that some forms of Java Collaborations can be stopped and started, such as collaborations invoked by arrival of a JMS Message.

The ability to stop and start components programmatically could lead to solutions that automatically start and stop components to a schedule, for example, to synchronize a Java CAPS solution with an operational downtime window of external systems, or to automatically bring additional components on line to smooth out processing peaks.

Note

Enterprise Manager API WSDL interface definitions are not WS-I compliant. Neither Java CAPS nor NetBeans 5.x nor Axis 2 can cope with them. Of the generally available tools, SoapUI readily deals with the WSDL and successfully invokes all operations.

To take advantage of the interface from Java CAPS, a lowest common denominator solution, HTTP Request/Reply, can be constructed to invoke service operations. Input SOAP Request can be constructed using string operations, and SOAP Responses can be processed using substring operations. Low tech but guaranteed to work.

See project __Book/SystemManagement/Programmatic/ManagerHttp (on the accompanying CD-ROM) for an example of how to implement a lowest common denominator solution that uses the Enterprise Manager Web Services API to obtain component status. A solution that starts and stops components using the same techniques can be readily developed using this project as the basis.

As events occur within Java CAPS, components are started or stopped, components report problems, solutions explicitly log alerts, and alert event messages are collected in the event database. Until a user explicitly acknowledges having seen a particular alert, or having “observed” it, the alert has the “unobserved” status. An observed alert will have the observed status until a user explicitly “resolves” the alert. Marking alerts as observed and resolved is performed through the Enterprise Manager. The Alert Service provides programmatic access to Alert management and maintenance. Using this service, a solution can automate observing and resolving alerts, resetting alerts to unobserved state, and deleting alerts from the event database. Performing automated maintenance of selected routine alerts will reduce the size of the event database and the number of alerts displayed in the Enterprise Manager. Judiciously implemented, this will reduce the clutter in the Enterprise Manager alert display and focus operations personnel on alerts of importance.

Note

The Web Services interfaces are not WS-Interoperability compliant, so most of the services cannot be directly invoked from Java CAPS using built-in Web Services support frameworks.

To successfully invoke any of the Alert Service Web Services operations, the invoker must have a valid Session ID. Session ID is obtained by invoking the Login Service’s openSession operation, explained in section 10.2.8.2.

Some of the Web Services operations operate on complete collections of alerts. These operations require a valid Session ID and affect all alerts. getAllAlerts, observeAllAlerts, resolveAllAlerts, deleteAllAlerts, and resetAllAlerts all fall into this category. Note that all of these operations potentially operate on a very large collection of alerts. Note, too, that the getAllAlerts potentially returns a very large SOAP Response message.

A SOAP Request for all alerts is shown in Listing 10-31.

<soapenv:Envelope
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:soap="http://soap.ws.services.em.egate.stc.com">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:getAllAlerts
      soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <sessionId
            xsi:type="soapenc:string"
            xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
815C0B9F5750CDEA1D73A3349706881F</sessionId>
      </soap:getAllAlerts>
   </soapenv:Body>
</soapenv:Envelope>

The request will return a very large SOAP Response with a collection of all alerts and their complete details. The example response in Listing 10-32 has been edited, removing most of the repetitions for brevity.

<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <ns1:getAllAlertsResponse
             soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
             xmlns:ns1="http://soap.ws.services.em.egate.stc.com">
         <getAllAlertsReturn
                soapenc:arrayType="ns2:local[500]"
                xsi:type="soapenc:Array"
                xmlns:ns2="myNameSpace:fixIt"
                xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
            <getAllAlertsReturn href="#id0"/>
...
            <getAllAlertsReturn href="#id499"/>
         </getAllAlertsReturn>
      </ns1:getAllAlertsResponse>
      <multiRef id="id54"
                soapenc:root="0"
             soapenv:encodingStyle=
                            "http://schemas.xmlsoap.org/soap/encoding/"
                xsi:type="ns3:local"
                xmlns:ns3="myNameSpace:fixIt"
                xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
         <alertName xsi:nil="true" xsi:type="soapenc:string"/>
         <comment xsi:nil="true" xsi:type="soapenc:string"/>
         <component xsi:type="soapenc:string"></component>
         <componentName xsi:type="soapenc:string"></componentName>
         <componentProjectPathName
                xsi:type="soapenc:string"></componentProjectPathName>
         <componentType
                xsi:type="soapenc:string">INTEGRATION</componentType>
         <date xsi:type="xsd:dateTime">2007-01-23T10:34:00.513Z</date>
         <deploymentName xsi:type="soapenc:string"></deploymentName>
         <details
                xsi:type="soapenc:string">Application Server Started</details>
         <elementName xsi:type="soapenc:string"></elementName>
         <environmentName xsi:type="soapenc:string"></environmentName>
         <event xsi:nil="true" xsi:type="xsd:anyType"/>
         <eventName xsi:type="soapenc:string">null</eventName>
         <eventType xsi:type="soapenc:string">ALERT</eventType>
         <id xsi:type="soapenc:string">4626</id>
         <index xsi:nil="true" xsi:type="soapenc:long"/>
         <logicalHostName xsi:type="soapenc:string">MCZ01</logicalHostName>
         <message xsi:type="soapenc:string">IS-00001</message>
         <messageCode xsi:type="soapenc:string">IS-00001</messageCode>
         <name xsi:nil="true" xsi:type="soapenc:string"/>
         <observationalState
                xsi:type="soapenc:string">Unobserved</observationalState>
         <observed href="#id500"/>
         <operationalState xsi:type="soapenc:string">Started</operationalState>
         <physicalHostName
                xsi:type="soapenc:string">localhost:20000</physicalHostName>
         <reference xsi:nil="true" xsi:type="xsd:anyType"/>
         <resolved href="#id501"/>
         <serverName xsi:type="soapenc:string">MCZ01</serverName>
         <serverType xsi:type="soapenc:string">INTEGRATION</serverType>
         <severity xsi:type="soapenc:string">INFO</severity>
         <timeStamp xsi:type="soapenc:string">01/23/07 09:34:00 PM</timeStamp>
         <type xsi:type="soapenc:string">INTEGRATION</type>
      </multiRef>
...
      <multiRef id="id470"
                soapenc:root="0"
                soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                xsi:type="ns502:local"
                xmlns:ns502="myNameSpace:fixIt"
                xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
         <alertName xsi:nil="true" xsi:type="soapenc:string"/>
         <comment xsi:nil="true" xsi:type="soapenc:string"/>
         <component xsi:type="soapenc:string">svc_jcdUPDATE_XA</component>
         <componentName xsi:type="soapenc:string">svc_jcdUPDATE_XA</componentName>
         <componentProjectPathName
             xsi:type="soapenc:string">DLI_POC2|XA|DPs</componentProjectPathName>
         <componentType xsi:type="soapenc:string">COLLABORATION</componentType>
         <date xsi:type="xsd:dateTime">2007-01-15T22:31:44.568Z</date>
         <deploymentName xsi:type="soapenc:string">dpUPDATE_XA</deploymentName>
         <details xsi:type="soapenc:string">
Collaboration svc_jcdUPDATE_XA is RUNNING
         </details>
         <elementName xsi:type="soapenc:string">svc_jcdUPDATE_XA</elementName>
         <environmentName xsi:type="soapenc:string">envDLIPOC</environmentName>
         <event xsi:nil="true" xsi:type="xsd:anyType"/>
         <eventName xsi:type="soapenc:string">null</eventName>
         <eventType xsi:type="soapenc:string">ALERT</eventType>
         <id xsi:type="soapenc:string">4208</id>
         <index xsi:nil="true" xsi:type="soapenc:long"/>
         <logicalHostName xsi:type="soapenc:string">DLIPOC_LH</logicalHostName>
         <message xsi:type="soapenc:string">COL-00001</message>
         <messageCode xsi:type="soapenc:string">COL-00001</messageCode>
         <name xsi:nil="true" xsi:type="soapenc:string"/>
         <observationalState
               xsi:type="soapenc:string">Unobserved</observationalState>
         <observed href="#id1498"/>
         <operationalState xsi:type="soapenc:string">Running</operationalState>
         <physicalHostName
               xsi:type="soapenc:string">localhost:20000</physicalHostName>
         <reference xsi:nil="true" xsi:type="xsd:anyType"/>
         <resolved href="#id1499"/>
         <serverName xsi:type="soapenc:string">DLIPOC_IS</serverName>
         <serverType xsi:type="soapenc:string">INTEGRATION</serverType>
         <severity xsi:type="soapenc:string">INFO</severity>
         <timeStamp xsi:type="soapenc:string">01/16/07 09:31:44 AM</timeStamp>
         <type xsi:type="soapenc:string">COLLABORATION</type>
      </multiRef>
      <multiRef
            id="id885"
            soapenc:root="0"
            soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
            xsi:type="xsd:boolean"  xmlns:soapenc=
                  "http://schemas.xmlsoap.org/soap/encoding/">false</multiRef>
      <multiRef
            id="id1227"
            soapenc:root="0"
               soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
            xsi:type="xsd:boolean"
            xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
false
      </multiRef>
...
      <multiRef id="id760"
            soapenc:root="0"
      soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
            xsi:type="xsd:boolean"
      xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">false</multiRef>
   </soapenv:Body>
</soapenv:Envelope>

Let’s work with the following alerts in the Enterprise Manager, as shown in Figure 10-39.

Figure 10-39. Selected Enterprise Manager alerts

Let’s “observe” all alerts (not just the ones listed but all alerts for all components) using a SOAP Request like the one shown in Listing 10-33.

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://
schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://
soap.ws.services.em.egate.stc.com">
   <soapenv:Header/>
   <soapenv:Body>
    <soap:observeAllAlerts
         soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <sessionId xsi:type="soapenc:string"
         xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
5DABD3370E5D3C02C41C5E334C5D40D8
     </sessionId>
    </soap:observeAllAlerts>
   </soapenv:Body>
</soapenv:Envelope>

Submitting this request will result in the response like the one shown in Listing 10-34.

<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
    <ns1:observeAllAlertsResponse
        soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:ns1="http://soap.ws.services.em.egate.stc.com"/>
   </soapenv:Body>
</soapenv:Envelope>

The Enterprise Manager will show all alerts as observed (see Figure 10-40).

Figure 10-40. Programmatically observed alerts in Enterprise Manager

Let’s now reset all alerts using a SOAP Request similar to that shown in Listing 10-35.

<soapenv:Envelope
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:soap="http://soap.ws.services.em.egate.stc.com">
   <soapenv:Header/>
   <soapenv:Body>
    <soap:resetAllAlerts
        soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <sessionId xsi:type="soapenc:string"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
5DABD3370E5D3C02C41C5E334C5D40D8
     </sessionId>
    </soap:resetAllAlerts>
   </soapenv:Body>
</soapenv:Envelope>

The Response looks like that in Listing 10-36.

<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
    <ns1:resetAllAlertsResponse
        soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:ns1="http://soap.ws.services.em.egate.stc.com"/>
   </soapenv:Body>
</soapenv:Envelope>

For each of the xxxxAllAlerts operations, there is an xxxxAlerts operation that requires a Session ID and a filter. The filter is an expression that restricts the collection of alerts to which the operation applies to these that satisfy the filter expression.

The filter expression has the following form, where semicolon is the AND operator. There may well be other operators, like the OR operator or a negation operator, but our experimentation did not uncover any:

fieldName=fieldValue;fieldName=fieldValue

fieldName can be one of the items returned by the getAlertQueryFields operation with a request like the one shown in Listing 10-37.

<soapenv:Envelope
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:soap="http://soap.ws.services.em.egate.stc.com">
   <soapenv:Header/>
   <soapenv:Body>
    <soap:getAlertQueryFields
        soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <sessionId xsi:type="soapenc:string"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
5DABD3370E5D3C02C41C5E334C5D40D8
     </sessionId>
    </soap:getAlertQueryFields>
   </soapenv:Body>
</soapenv:Envelope>

The response, shown in Listing 10-38, enumerates all “Query Fields” that can be used.

<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
    <ns1:getAlertQueryFieldsResponse
        soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:ns1="http://soap.ws.services.em.egate.stc.com">
     <getAlertQueryFieldsReturn
        soapenc:arrayType="soapenc:string[16]" xsi:type="soapenc:Array"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">from</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">to</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">id</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">environmentName</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">physicalHostName</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">logicalHostName</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">serverName</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">
componentProjectPathName
      </getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">deploymentName</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">componentName</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">severity</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">type</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">observationalState</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">operationalState</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">messageCode</getAlertQueryFieldsReturn>
      <getAlertQueryFieldsReturn
        xsi:type="soapenc:string">details</getAlertQueryFieldsReturn>
     </getAlertQueryFieldsReturn>
    </ns1:getAlertQueryFieldsResponse>
   </soapenv:Body>
</soapenv:Envelope>

The fields are tabulated and discussed in Table 10-3.

Table 10-4 lists values that can be used for the messageCode.

Table 10-5 lists values that can be used for type.

The following values can be used for severity. Since severity does not seem to work, however, this information is perhaps not very relevant.

FATAL, CRITICAL, MAJOR, MINOR, WARNING, INFO

The following values can be used for operationalState. Since operationalState does not seem to work, however, this information is perhaps not very relevant.

UNKNOWN, STARTING, SUSPENDING, SUSPENDED, STOPPING, STOPPED, RUNNING

The following values can be used for observationalState. Since observationalState does not seem to work, however, this information is perhaps not very relevant.

UNOBSERVED, OBSERVED, RESOLVED

Alerting and SNMP agent logging can be increased or decreased by configuring one or more of the logging categories listed in Listing 10-39 in the Enterprise Manager’s log4j.properties.

com.stc.eventmanagement
com.stc.snmpagent.webservices
com.stc.snmpagent

Now that we discussed filtering and filter values, let’s submit a request with a filter expression asking for all “Component Running” alerts for the collaboration svc_jcdUpdateXA on January 26, 2007. The filter expression will be:

from=01/26/2007;to=01/27/2007;componentName=svc_jcdUpdateXA;messageCode=COL-00001

The request in Listing 10-40 uses that filter expression to get corresponding alerts.

<soapenv:Envelope
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:soap="http://soap.ws.services.em.egate.stc.com">
   <soapenv:Header/>
   <soapenv:Body>
    <soap:getAlerts
        soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <sessionId xsi:type="soapenc:string"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
5DABD3370E5D3C02C41C5E334C5D40D8
     </sessionId>
     <filter xsi:type="soapenc:string"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
from=01/26/2007;to=01/27/2007;componentName=svc_jcdUpdateXA;messageCode=COL-00001
     </filter>
    </soap:getAlerts>
   </soapenv:Body>
</soapenv:Envelope>

The (edited) response is shown in Listing 10-41.

<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
    <ns1:getAlertsResponse
        soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:ns1="http://soap.ws.services.em.egate.stc.com">
     <getAlertsReturn soapenc:arrayType="ns2:local[5]" xsi:type="soapenc:Array"
        xmlns:ns2="myNameSpace:fixIt"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
      <getAlertsReturn href="#id0"/>
...
      <getAlertsReturn href="#id4"/>
     </getAlertsReturn>
    </ns1:getAlertsResponse>
    <multiRef id="id1" soapenc:root="0"
        soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
        xsi:type="ns3:local" xmlns:ns3="myNameSpace:fixIt"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
     <alertName xsi:nil="true" xsi:type="soapenc:string"/>
     <comment xsi:nil="true" xsi:type="soapenc:string"/>
     <component xsi:type="soapenc:string">svc_jcdUpdateXA</component>
     <componentName xsi:type="soapenc:string">svc_jcdUpdateXA</componentName>
     <componentProjectPathName xsi:type="soapenc:string">
__Book|Examples|WSSPXA|DPs
     </componentProjectPathName>
     <componentType xsi:type="soapenc:string">COLLABORATION</componentType>
     <date xsi:type="xsd:dateTime">2007-01-26T11:40:41.903Z</date>
     <deploymentName xsi:type="soapenc:string">dpWSSPXA</deploymentName>
     <details xsi:type="soapenc:string">
Collaboration svc_jcdUpdateXA is RUNNING
     </details>
     <elementName xsi:type="soapenc:string">svc_jcdUpdateXA</elementName>
     <environmentName xsi:type="soapenc:string">envWSSPXA</environmentName>
     <event xsi:nil="true" xsi:type="xsd:anyType"/>
     <eventName xsi:type="soapenc:string">null</eventName>
     <eventType xsi:type="soapenc:string">ALERT</eventType>
     <id xsi:type="soapenc:string">4678</id>
     <index xsi:nil="true" xsi:type="soapenc:long"/>
     <logicalHostName xsi:type="soapenc:string">WSSPXA_LH</logicalHostName>
     <message xsi:type="soapenc:string">COL-00001</message>
     <messageCode xsi:type="soapenc:string">COL-00001</messageCode>
     <name xsi:nil="true" xsi:type="soapenc:string"/>
     <observationalState xsi:type="soapenc:string">Unobserved</observationalState>
     <observed href="#id5"/>
     <operationalState xsi:type="soapenc:string">Running</operationalState>
     <physicalHostName
          xsi:type="soapenc:string">localhost:20000</physicalHostName>
     <reference xsi:nil="true" xsi:type="xsd:anyType"/>
     <resolved href="#id6"/>
     <serverName xsi:type="soapenc:string">WSSPXA_IS</serverName>
     <serverType xsi:type="soapenc:string">INTEGRATION</serverType>
     <severity xsi:type="soapenc:string">INFO</severity>
     <timeStamp xsi:type="soapenc:string">01/26/07 10:40:41 PM</timeStamp>
     <type xsi:type="soapenc:string">COLLABORATION</type>
    </multiRef>
...
    <multiRef id="id2" soapenc:root="0"
          soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
          xsi:type="ns7:local" xmlns:ns7="myNameSpace:fixIt"
          xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
     <alertName xsi:nil="true" xsi:type="soapenc:string"/>
     <comment xsi:nil="true" xsi:type="soapenc:string"/>
     <component xsi:type="soapenc:string">svc_jcdUpdateXA</component>
     <componentName xsi:type="soapenc:string">svc_jcdUpdateXA</componentName>
     <componentProjectPathName xsi:type="soapenc:string">
__Book|Examples|WSSPXA|DPs
     </componentProjectPathName>
     <componentType xsi:type="soapenc:string">COLLABORATION</componentType>
     <date xsi:type="xsd:dateTime">2007-01-26T06:01:22.358Z</date>
     <deploymentName xsi:type="soapenc:string">dpWSSPXA</deploymentName>
     <details xsi:type="soapenc:string">
Collaboration svc_jcdUpdateXA is RUNNING
     </details>
     <elementName xsi:type="soapenc:string">svc_jcdUpdateXA</elementName>
     <environmentName xsi:type="soapenc:string">envWSSPXA</environmentName>
     <event xsi:nil="true" xsi:type="xsd:anyType"/>
     <eventName xsi:type="soapenc:string">null</eventName>
     <eventType xsi:type="soapenc:string">ALERT</eventType>
     <id xsi:type="soapenc:string">4673</id>
     <index xsi:nil="true" xsi:type="soapenc:long"/>
     <logicalHostName xsi:type="soapenc:string">WSSPXA_LH</logicalHostName>
     <message xsi:type="soapenc:string">COL-00001</message>
     <messageCode xsi:type="soapenc:string">COL-00001</messageCode>
     <name xsi:nil="true" xsi:type="soapenc:string"/>
     <observationalState xsi:type="soapenc:string">Observed</observationalState>
     <observed href="#id13"/>
     <operationalState xsi:type="soapenc:string">Running</operationalState>
     <physicalHostName
          xsi:type="soapenc:string">localhost:20000</physicalHostName>
      <reference xsi:nil="true" xsi:type="xsd:anyType"/>
      <resolved href="#id14"/>
      <serverName xsi:type="soapenc:string">WSSPXA_IS</serverName>
      <serverType xsi:type="soapenc:string">INTEGRATION</serverType>
      <severity xsi:type="soapenc:string">INFO</severity>
      <timeStamp xsi:type="soapenc:string">01/26/07 05:01:22 PM</timeStamp>
      <type xsi:type="soapenc:string">COLLABORATION</type>
     </multiRef>
     <multiRef id="id14" soapenc:root="0"
           soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
           xsi:type="xsd:boolean"
           xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
false
     </multiRef>
...
    <multiRef id="id10" soapenc:root="0"
          soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
          xsi:type="xsd:boolean"
          xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
false
    </multiRef>
   </soapenv:Body>
</soapenv:Envelope>

The query field content and operation comments in Table 10-3 are a result of empirical study. There is no documentation, to which the author has access, that describes any of this.

Following are some example filters that work.

Other filters may well work as well. The experiments were conducted using SoapUI, which is a quick and easy way to invoke Web Services for experimentation.

Filterable operations for which filters are required are deleteAlerts, getAlerts, observeAlerts, resolveAlerts, and resetAlerts.

Finally, the Alert Service supports the closeSession operation, which allows the session established with the Login Service to be closed and the Session ID to be invalidated.

Attempting to perform an operation using a Session ID for which the session has been closed results in a SOAP Fault similar to the one shown in Listing 10-42.

<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
    <soapenv:Fault>
     <faultcode>soapenv:Server.userException</faultcode>
     <faultstring>
java.rmi.RemoteException: Session not found for:5DABD3370E5D3C02C41C5E334C5D40D8
     </faultstring>
     <detail>
      <ns1:hostname xmlns:ns1="http://xml.apache.org/axis/">MCZ01</ns1:hostname>
     </detail>
    </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

While it is unfortunate that most of the Alert operations cannot be invoked from a Java CAPS solution directly, it is possible to incorporate them into an operational system by building standalone components, using Sun’s Net Beans IDE, and deploying them to the Sun Application Server. These components could use one of the techniques discussed in Chapter 5, “Messaging Infrastructure,” section 5.15, to support integration into a Java CAPS solution.

[eGateSAG] mentions the use of the Java CAPS JMX Console. To invoke the JMX Console, use the URL that points to the host and port for the Application Server domain to be monitored, with the literal “jmx-console” as the servlet context. For example:

http://localhost:20000/jmx-console

where 20000 is the _base port_ for the domain as distinct from the port of the default Web Container in the domain.

Once logged in with administrator credentials, you will see a page similar to the one shown in Figure 10-41, where the number of links will vary with the number of enterprise applications deployed to the domain.

Figure 10-41. Java CAPS jmx-console servlet display

Enterprise Manager information, obtained by clicking the Enterprise Manager link, will look similar to that shown in Figure 10-42, with host names, port numbers, and other site-specific information different from that in the illustration.

Figure 10-42. Results of clicking on the Enterprise Manager link

Those familiar with the internals of the Sun Application Server 8.0 can use the Management Beans (MBeans) to obtain information about various aspects of the Java CAPS integration server and JMS implementation, and modify modifiable properties and attributes.

Just how useful this information may be will vary. Since documentation is scarce, and the System Administration Guide names only one MBean as supported, what you see may vary from release to release.

As an example, let’s look at com.sun.appserv domain’s name=logmanager, category=runtime link, as shown in Figure 10-43.

Figure 10-43. Runtime logmanager link

The MBean supports a number of operations. Invoking its getLogDump operation, as shown in Figure 10-44, produces some insightful information about the logging categories and their dependency hierarchy (Figure 10-45). The list is long.

Figure 10-44. getLogDump operation button

Figure 10-45. Logging categories and levels displayed by getLogDump operation

Executing the getLoggerNamesUnder() operation specifying category com.stc .bpms produces a list of names for which log levels can be specified, as shown in Figure 10-46.

Figure 10-46. Asking for a list of loggers under the com.stc.bpms category

Figure 10-47 shows the list, which is longish and unformatted.

Figure 10-47. List of loggers under com.stc.bpms

Copying the list, pasting into a text editor, and reformatting yields a list of “interesting” logging categories (see Listing 10-43) that can be specified for logging various aspects of the eInsight execution environment.

com.stc.bpms.bpelImpl.util.BPELHelper
com.stc.bpms.mbean.BPEngineMBean
com.stc.bpms.bpelImpl.persistence.adapter.impl.DBAdapter
com.stc.bpms.bpelConnector.ConnectionFactoryImpl
com.stc.bpms.bpelConnector.impl.WorkListenerImpl
com.stc.bpms.bpelImpl.runtime.ExtendedAssignerImpl
com.stc.bpms.bpelImpl.persistence.reporting.ReportsTableDataPersister
com.stc.bpms.bpelImpl.runtime.BPELInterpreter
com.stc.bpms.bpelImpl.runtime.persistence.connectionManager.ConnectionMgr
com.stc.bpms.bpelConnector.impl.ExecutorImpl
com.stc.bpms.bpelConnector.impl.EndPointFactoryRegistryInfoImpl
com.stc.bpms.bpelImpl.runtime.AbstractEventHandler
com.stc.bpms.bpelImpl.persistence.adapter.DAO
com.stc.bpms.bpelImpl.util.CorrelationHelper
com.stc.bpms.bpelImpl.model.BPELAlerterImpl
com.stc.bpms.bpelImpl.persistence.util.PropertiesHelper
com.stc.bpms.bpelImpl.runtime.persistence.dao.DAO
com.stc.bpms.bpelImpl.runtime.persistence.connectionManager.ConnectionPool
com.stc.bpms.bpelImpl.monitoring.MonitoringDataPersisterImpl
com.stc.bpms.bpelConnector.impl.BPELResourceAdapterImpl
com.stc.bpms.bpelImpl.runtime.persistence.FailoverPersister
com.stc.bpms.bpelConnector.impl.AbstractWSProvider
com.stc.bpms.bpelImpl.runtime.Interpreter
com.stc.bpms.bpelImpl.runtime.RecoveryImpl
com.stc.bpms.bpelImpl.runtime.ProcessType
com.stc.bpms.bpelImpl.runtime.persistence.connectionManager.ConnectionImpl

What some of these categories are likely to log can only be guessed at. Others are perhaps more self-evident. One of the more useful categories is com.stc .bpms.bpelImpl.runtime.BPELInterpreter. Configuring this category to Fine, or a more verbose level, will show eInsight execution trace and allow debug logging on activities within Business Processes to be shown in the server.log.

Some interesting links under the com.sun.appserv domain might be the following:

type=messaging-server-config-mbean,jmsservertype=stcms,name=Sun_SeeBeyond_JMS_IQ_Manager

type=messaging-server-admin-mbean,jmsservertype=stcms,name=Sun_SeeBeyond_JMS_IQ_Manager

type=jvm,category=monitor,server=server (provides information on JVM's heap size and heap
 utilization)

j2eeType=JVM,name=MCZ01_1169686101366,J2EEServer=server,category=runtime (where the name,
 here shown as MCZ01_xxx, will be different)

j2eeType=J2EEServer,name=server,category=runtime

You may find, under the SeeBeyond domain, references to Business Process engines, like the following:

EARId=__Book_u002F_MessageExch1329550651,type=BPEngineMBean

You could, with some effort, use this link to manage eInsight Business Processes using the JMX interface.

Under the com.stc.Logging domain, there are other, potentially interesting links:

name=LogConfigurator,type=AppServerLogConfigurator

name=LogReader,type=AppServerLogReader,logger=jms

name=LogReader,type=AppServerLogReader,logger=server

There are a number of other links, in the JMX Console page, that provide access to information and operations of greater or lesser value, depending on your familiarity with the solutions and application server internals.

By default in Java CAPS 5.1.3, JMX instrumentation support required to use JConsole and similar JMX console applications is not enabled, so JConsole cannot be used. To enable interaction with the JConsole, the Integration Server must be started with one or more additional Java Virtual Machine (JVM) options. See [JMXNote] and [JMXNote2] for discussions of the topic.

In brief, setting one or more JVM options for the Integration Server, and restarting the Integration Server, will enable JConsole’s local and/or remote access to the application. Note that depending on the options and how they are set, you may end up with an insecure connection.

To enable the JMX agent for local access, add the following JVM property:

-Dcom.sun.management.jmxremote

Setting this property registers the JVM instrumentation MBeans and publishes the Remote Method Invocation (RMI) connector via a private interface to allow JMX client applications to monitor a local Java platform, that is, a JVM running on the same machine. When you start the JConsole application, it presents a display similar to that shown in Figure 10-48.

Figure 10-48. Connecting JConsole to a JVM running on a local machine

Pressing Connect will cause JConsole to connect and will provide access to the console’s functionality. [JConsole] has a nice discussion of JConsole and its capabilities. Here are some examples.

The Heap graph is shown in Figure 10-49.

Figure 10-49. Heap Graph

The Threads graph is shown in Figure 10-50.

Figure 10-50. Threads graph

Attributes of a selected MBean for a component of the solution deployed to the Integration Server are shown in Figure 10-51, and operations are shown in Figure 10-52. For additional information and specific examples, see Chapter 8, section 8.2.3.1, “Programmatic Management,” in Part II.

Figure 10-51. MBean for a selected enterprise application

Figure 10-52. MBean operations

Some of the virtual machine and environment information is shown in Figure 10-53.

Figure 10-53. Virtual machine and environment information in JConsole

All of the above can be accessed with JConsole as long as JConsole and the monitored application reside on the same physical machine. To enable remote monitoring, a couple of other JVM options, shown in Listing 10-44, need to be set.

-Dcom.sun.management.jmxremote.port=portNum
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.authenticate=false

This will allow a remote JConsole to connect to the Integration Server without authentication and over an insecure connection, as shown in Figure 10-54. Remote monitoring and management may be desirable, as JConsole is fairly heavy on resources. Running it on the host already heavily utilized will skew some results.

Figure 10-54. JConsole properties used to connect to the remote JVM

See [JMXNote2] for a discussion of how to enable authentication and channel security for remote JMX management.

The URL for programmatic access to the managed resource, given port number of 9999 and the application running on localhost, is:

service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi

Figure 10-55 shows the dialog box where this value must be entered.

Figure 10-55. JMX URL for remote monitoring

The URL in Figure 10-55 is what you would specify to the MC4J [MC4J], another JXM Console application that some people might prefer and perhaps find more friendly, to permit it to connect to the Java CAPS Integration Server.

Figure 10-56 shows MC4J connection properties that allow MC4J to connect to the Java CAPS environment.

Figure 10-56. MC4J properties needed to monitor a Java CAPS solution

The URL for programmatic access to the managed resource, given port number of 9999 and the application running on localhost, is:

service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi

JMX technology allows programmatic access to managed components. JConsole and MC4J use the JMX API for this purpose. A Java CAPS solution designer can use the API to programmatically manage solution components as well. One of the questions that frequently pops up in mailing lists and elsewhere is, “How can I programmatically stop a Java Collaboration?” This and a related question—“How can I tell if a component is up or down?”—can be addressed using the JMX API. This section discusses an example Java Collaboration that can be used to execute JMX management actions on other Java CAPS components, including stop, start, getStatus, and others. Which actions can be executed depends on the component. The example itself is developed in Chapter 8, section 8.2.3.1, “Programmatic Management,” in Part II.

Knowing the name of the MBean associated with a particular Java CAPS component allows you to manage it. Both the name of the MBean and the management actions supported by a component can be discovered using JConsole or MC4J. Let’s take the example from project __Book/MessageExchangePatterns/MessageExpiration developed for this book, with the project hierarchy shown in Figure 10-57.

Figure 10-57. MessageExpiration project hierarchy

The connectivity map in Figure 10-58 shows the following components: qIn, qOut, qPark, svc_jcdExpireMessageEarly, and svcJMS2JMSShowExpiration.

Figure 10-58. Connectivity map for project MessageExpiration

The deployment profile is named dpMessageExpiration.

The deployed project appears in the Enterprise Manager’s Deployer, as shown in Figure 10-59.

Figure 10-59. Project represented by deployment profile dpMessageExpiration in Deployer

MC4J, under the domain named SeeBeyond, lists all the MBeans created for the components in this project, as shown in Figure 10-60.

Figure 10-60. MBeans under the SeeBeyond domain

The text in Figure 10-60 is unreadable, so let’s reformat the list so it is decipherable. Listing 10-45 shows the reference to the MBean, which is discussed in subsequent paragraphs, where all components are in reality on a single line.

Name=dpMessageExp__BookMessag_1670182084
    |MessageExpiration
    |dpMessageExpiration
    |qIn_svc_jcdExpireMessagesEarly
    ,GUID={8E010000-48F444ED110100-C0A83C02-01}

The string following Name= corresponds to the EAR name as seen in the Deployer. The string MessageExpiration corresponds to the name of the project containing deployment profile, dpMessageExpiration, which is the next string.

The string qIn_svc_jcdExpireMessagesEarly contains both the name of the JMS queue and the name of the Java Collaboration that subscribes to it. Looking back to the connectivity map, we will surmise that this MBean corresponds to the subscription of the CM service svc_jcdExpireMessagesEarly to JMS Queue qIn.

The GUID is not particularly interesting.

Here are the remaining components.

Name=dpMessageExp__BookMe
ssag_1670182084|MessageExpiration|dpMessageExpiration|qOut_svcJMS2JMSShowExpiration,
 GUID={8F010000-48F444ED110100-C0A83C02-01}

qOut_svcJMS2JMSShowExpiration is the subscription of svcJMS2JMSShowExpiration to qOut.

Name=dpMessageExp__BookMessag_1670182084|MessageExpiration|dpMessageExpiration|svc
JMS2JMSShowExpiration, GUID={8F010000-48F444ED110100-C0A83C02-01}

svcJMS2JMSShowExpiration is the Java Collaboration service.

Name=dpMessageExp__BookMessag_1670182084|MessageExpiration|dpMessageExpiration|svc
JMS2JMSShowExpiration_qPark, GUID={8F010000-48F444ED110100-C0A83C02-01}

svcJMS2JMSShowExpiration_qPark is the publication of svcJMS2JMSShowExpiration to JMS Destination qPark.

Name=dpMessageExp__BookMessag_1670182084|MessageExpiration|dpMessageExpiration|svc
_jcdExpireMessagesEarly, GUID={8F010000-48F444ED110100-C0A83C02-01}

svc_jcdExpireMessagesEarly is the Java Collaboration service.

Name=dpMessageExp__BookMessag_1670182084|MessageExpiration|dpMessageExpiration|svc
_jcdExpireMessagesEarly_qOut, GUID={8F010000-48F444ED110100-C0A83C02-01}

svc_jcdExpireMessagesEarly_qOut is the publication of svc_jcdExpireMessagesEarly to JMS queue qOut.

Any one of these MBeans can be used to inspect the attributes of the corresponding component. Some MBeans will allow their managed object to be started, stopped, or queried. Which actions or operations are supported will vary from object to object. JMS queue subscription or a Java Collaboration service, for example, can be started and stopped. Publication to a JMS queue cannot be started or stopped.

Let’s use the MC4J JMX Console to look at the subscription qIn_svc_jcdExpireMessagesEarly, as shown in Figure 10-61.

Figure 10-61. Operations under subscription qIn_svc_jcdExpireMessagesEarly

Some of the more interesting operations are getStatus, isStoppable, isStartable, Stop, and Start. Executing some of these operations produces results that vary with operation. Figures 10-62 through 10-64 illustrate execution of getStatus and isRestartable operations.

Figure 10-62. Execute getStatus operation

Figure 10-63. Result of execution of the getStatus operation

Figure 10-64. Results of execution of the isRestartable operation

The same can be achieved from a standalone Java application or from a Java Collaboration.

In a solution that takes advantage of the JMS Message Server infrastructure to pass messages from component to component, latency, the amount of time it takes for the message to travel from the sending component to the next receiving component downstream, may be of interest. Regardless of the characteristics of the platform and of the workload, there will always be some minimum latency. Latency is affected by the workload and by solution design. The design involving serial receivers is more likely to experience increased latency with increased workload than the design involving concurrent consumers.

Measurement of latency can be accomplished by taking advantage of the timeToLive parameter to most JMS send() methods in senders and the JMS Message Server–calculated message Expiration property value of messages at the receivers.

For the explicitly set timeToLive value, the calculation is:

timeToLivesender – (Expirationreceiver - CurrentTimeMillisecondsreceiver)

The result of this calculation will be the latency. This value can be passed to the performance data collection component using one of the techniques discussed later in this chapter. It must be borne in mind that performing latency calculation based on timeToLive value introduces interdependency between the sender, which sets the timeToLive value, and the receiver, which uses it to calculate latency, as both components must agree on the value and both hardcode it. Needless to say, the calculation itself introduces some overhead unrelated to the primary purpose of the component in which it occurs.

In the absence of explicit timeToLive value, the JMS Message Server global Maximum Lifetime property value can be used. The calculation is:

Maximum Lifetimeglobal – (Expirationreceiver - CurrentTimeMillisecondsreceiver)

The result of this calculation will be the latency. This value can then be passed to the performance data collection component using one of the techniques discussed later in this chapter. It must be borne in mind that whereas the timeToLive value is presumably explicitly hardcoded in the sending component and therefore will not readily change, the Maximum Lifetime value is configurable through the Integration Server Administration interface and can be readily changed, affecting results of all latency calculations that are based on this property. Furthermore, the receiver that calculates latency must hardcode the Maximum Lifetime value to perform the calculation. This value will become incorrect if the global JMS Message Server property value changes.

Instead of hardcoding timeToLive or Maximum Lifetime values, you could read these values from a database or a properties file. This would make the solution more adaptable to change but in itself introduces additional complexity and overheads that require careful consideration.

For the purpose of calculating latency, it is immaterial whether the sender is a Java Collaboration or an eInsight Business Process. It is the receiver that performs the calculation. A receiver Java Collaboration could use code similar to that shown in Listing 10-46 to calculate latency.

    public void receive
        (com.stc.connectors.jms.Message input
        ,com.stc.connectors.jms.JMS W_toJMS )
            throws Throwable
    {
        long lExpiration = input.getMessageProperties().getExpiration();
        long lNow = System.currentTimeMillis();
        long lTimeToLive = 60000;
        ;
        long lLatency = lTimeToLive - (lExpiration - lNow);
        ;
        logger.debug( "
Latency: " + lLatency );
        ;
        W_toJMS.send( input );
    }

A receiver eInsight Business Process has no built-in access to the value of the current time in milliseconds; therefore a helper Java Collaboration is required. This collaboration would be invoked as an activity and would return a long time value needed for the latency calculation.

Chapter 8, section 8.2.4.1, “JMS Latency,” in Part II, provides an example of both the helper collaboration and the solution that calculates JMS latency using eInsight Business Process.

Whereas JMS latency can be readily calculated from information already carried in messages during normal processing, it can only be calculated on a hop-by-hop basis and “inlined” in the processing components themselves.

If there are multiple components in a solution and message processing statistics like latency and throughput are to be calculated on a global basis, standard JMS Header properties cannot be used to collect the necessary data.

Recall that JMS topics with no durable subscribers act as Channel Purgers [EIP]. Any message placed in such a topic is discarded by the JMS Message Server. This property can be exploited to introduce Wire Taps [EIP] into solutions at the time business functionality is developed, without the need to concurrently develop statistics collection and processing components.

Let’s imagine that a Wire Tap is added as the first activity in the first component of a solution and as the last activity in the last component of a solution. As each message passes through the set of components, it is replicated to both JMS topics, which are the Wire Taps, in full or in part, and its message identification is propagated as a Correlation ID property or a user-defined property in the JMS Message Header. The solution is completed, tested, and deployed in production. The cost of the overhead of replicating messages, only to have them discarded by the JMS Message Server, will vary with the size of messages, how much information is sent to Wire Taps, and the message volume.

Some time later, when the organization decided in what statistics it might be interested, a messaging system management and information processing solution, or two, or three, can be developed and deployed. The existing production solution will be unaffected by deployment of the solution that processes messages placed in Wire Taps.

Just correlating messages from the initial and the final Wire Taps leads to a number of useful statistics:

All these statistics can be obtained with no disruption and minimum overhead to the business solution and without even looking at what the messages themselves are. Because Wire Taps are implemented as JMS topics, a number of independent statistics processing solutions can be built and deployed over time to operate concurrently. If the overhead of processing statistics becomes excessive, statistics processing solutions can be deployed to a separate, independent Application Server.

Once you start looking at the messages themselves, other useful statistics can be obtained, including the following:

With the aid of judiciously placed Wire Taps, both new and existing solutions can be readily instrumented to feed management and monitoring solutions with information about messages being processed. Information gleaned from message traffic can be collected and manipulated to provide useful statistics on the state and performance of the messaging systems. Using tools like Business Activity Monitor—for example, Sun eBAM—runtime statistics can be displayed, alerts can be raised, and solution components can be reconfigured based on real-time feedback.