Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 8 Advanced Features : Advisory Handling

Advisory Handling
TIBCO Adapter SDK provides an advisory methodology for developers and end users to report or listen to advisory messages generated by TIBCO Adapters and TIBCO Rendezvous.
Both TIBCO Rendezvous and the TIBCO Adapter SDK software present asynchronous advisory messages to custom adapters based on the SDK. Advisory messages indicate errors, warnings, and other information.
In contrast to status codes, which indicate success or failure within a specific TIBCO Adapter SDK call, asynchronous advisory messages notify custom adapters of events that occur outside of the adapter’s direct flow of control. For example, the adapter is processing inbound messages too slowly, causing the TIBCO Rendezvous daemon’s message queue to overflow.
Receiving Advisory Messages
Custom adapters can receive advisory messages in the same way as any other messages—by listening to subject names.
For example, the subject _RV.*.SYSTEM.> matches all advisories related to TIBCO Rendezvous communications. Programs can also listen for specific advisories. Where the advisory becomes available depends on whether they are related to a transport.
Advisories related to a specific transport present on that transport. A custom adapter that creates several transports might need to listen for advisory messages on each transport.
Advisory messages wait for dispatch in the queue that the custom adapter designates when creating the listener.
To handle advisories, a custom adapter can instantiate MAdvisory directly and use the default advisory handling capabilities, or create a custom advisory listener.
Advisory Listeners
The advisory listener represents an event handler. The SDK allows you to use the default SDK advisory listener or create a custom advisory listener.
The event handler should be implemented by a custom adapter that needs to take specific action when an advisory event occurs.
Standard Advisory Listener
The SDK provides a default advisory listener that reports advisory messages being collected to the MTrace object. The advisory listener can listen to advisory messages from the sources listed in Table 32.
Advisory messages sent when an ActiveEnterprise operation server receives a request that it cannot serve. This could be because the incoming messages is in a bad format or cannot be demarshalled by the server.
User-defined advisory. Not Recommended unless there is a special situation.
A typical usage scenario is to have an application listen to TIBCO Rendezvous error advisories such as _RV.ERROR.>. Using a simple configuration with the default advisory listener, any TIBCO Rendezvous error would be routed directly to the errorRole of the SDK MTrace object.
Custom Advisory Listener
You can replace the SDK default advisory listener with a custom advisory listener. For example, a custom advisory listener can be used to handle _RV.RVCM.COLLISION. In this case, the application might need to take specific action. To extend the default behavior, you can create a subclass that inherits MAdvisoryListener and explicitly calls the superclass callback.
To set a custom advisory listener, use the MApp method setAdvisoryListener().
Advisory Publisher
The SDK provides an API to generate user-defined advisories. See the description of the MAdvisory::send() methods in the online API documentation.
The advisory publisher provides standard SDK advisory events for anomalies.
User advisories are intended for situations where there is no other way of notifying internal code that an unusual situation has occurred. For example, in cases where an API is using the SDK to offer services, it is possible that exceptions cannot be thrown when errors occur. It may be appropriate to send a user-generated advisory under these circumstances.
Advisory Subject Format
TIBCO Rendezvous Advisory Message
TIBCO Rendezvous advisory messages contain the following subject name as specified in the TIBCO Rendezvous Concepts:
 
_RV.<class>.<source>.<category>.<role>.<condition>.<name>
TIBCO Adapter SDK Advisory Message Structure
SDK advisory messages have the following structure:
 
   _SDK.<class>.<category>.<name>
or
   _SDK.<class>.<category>.<subject suffix>
Table 33 lists the message fields and descriptions.
ERROR—problem is severe and not repairable.
WARN—problem exists during the operation but the program managed to resolve the problem. Undesirable side effects might occur.
INFO—information that may be of interest to the user. SDK takes no action. It only detects these conditions and reports to the users.
RPC—operations-related advisory messages
USER—user-reported advisory messages
Advisory Message Format
Advisory messages are free-form. They are attached to an MTree to be sent out. All SDK advisory messages are wrapped into an MTree and sent to the advisory event listener. The advisory event mechanism delivers messages among the threads of a program and does not go into the network.
Here are the predefined SDK advisory messages:
Advisory messages generated when an ActiveEnterprise Operation server receives an unknown request.
The original message is appended as a part of the advisory message, but the destination name is not included. You should be able to determine this from the operation server endpoint itself. You can then use this information to acknowledge the message manually, in case of durable subscribers with auto acknowledge disabled.
Advisory messages generated when an ActiveEnterprise Operation server receives a legal request but cannot deserialize the request parameters.
(C++ only) Advisory message generated when a TIBCO Hawk microagent receives an unknown or malformed request. The advisory could be caused by Adapter SDK subscribing to the unsupported Hawk subject _HAWK.AMI.DISCOVERY when the Hawk standard microagent is enabled.
(C++ only) Advisory message generated when a TIBCO Hawk method implementation is missing from the Hawk microagent for an incoming request.
This advisory is sent to adapters with JMS subscribers that failed to receive messages due to a JMS internal error. This can occur if the JMS server crashes or terminates during a receiving operation: jms status = SERVER_NOT_CONNECTED. This error advisory is an unrecoverable condition. Applications that rely on this JMS session must exit.
However, if the JMS session has a fault tolerant connection URL specified, JMS will fail over to next server. If the JMS session has a reconnect URL specified instead, this advisory occurs only after JMS has exhausted all its reconnection attempts. Note that no error or exceptions are thrown by JMS while it is attempting to reconnect.
User-Defined Advisories
Use the MAdvisory::send() method for user-defined advisories.
C++ Code Example
MAdvisory * pAdvisory = pMApp->getAdvisory();
pAdvisory->send( "ADVISORIES.DB.SEVERE"
                ,"ERROR"
                ,"Insert operation failed
                ,"queued for retry"
                ,"remoteLoggingSession" );
Java Code Example
In Java, use the MAdvisory.send() method, as in the following example:
MAdvisory advisory = mapp.getAdvisory();
advisory.send("ADVISORIES.DB.SEVERE",
              "ERROR",
              "Insert operation failed",
              "remoteLoggingSession");

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved