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


Chapter 12 Creating a Deployable Custom Adapter : Modifying Code for TIBCO Administrator Compliance

Modifying Code for TIBCO Administrator Compliance
The following standard TIBCO Hawk microagent methods are required for the adapter to comply with TIBCO Administrator.
To use these microagent methods, modify the code as follows:
1.
2.
3.
4.
Adding MHostInfo
The following information is Java-specific. For changes required in the C++ adapter, look at the C++ example code in the SDK_HOME\resourceKit directory. The main difference is that, for C++ SDK, you need to change code to link with the Service Wrapper library.
The MHostInfo contains the application name, instance ID, and state information that is returned to the SDK standard Hawk microagent method getHostInformation(). It can also contain backend specific information such as the backend application name, version, connection status, and so on.
1.
Create MHostInfo in the ZapAdapter constructor and set application status (AppState) to INITIALIZING.
AppName and Instance ID are automatically set in the constructor from the information provided by the MApp parameter.
Application status is not reported to TIBCO Administrator until the standard microagent has been registered with TIBCO Runtime Agent and event dispatch has started.
MApp app = new TestAdapterCore( p );
MHostInfo hostInfo = new MHostInfo(app);
  //** set hostInfo service state   hostInfo.setAppState(MUserApplicationState.INITIALIZING);   app.setHostInfo(hostInfo);
  app.start();

 
2.
Obtain MHostInfo back inside onInitialization() method and set AppState to RUNNING. After connecting to ZAP, set the backend information obtained. Events dispatch starts after onInitialization() is done.

 
onInitialization() {
//** Create Host information
MHostInfo hostInfo = getHostInfo(); hostInfo.setAppState(MUserApplicationState.RUNNING); setHostInfo(hostInfo);
    ....
 
ZAPCustomer.zap_Init();
ZAPConnection conn = new ZAPConnection(this);
if (conn.connect()) {
     //** Trace no tracking id, second param set to null      getTrace().trace("AEZAP-2000", null,
        "Successfully connected to ZAP database");      hostInfo.setExtendedInfo("Host", conn.getHostName());      hostInfo.setExtendedInfo("Port",
         new Integer(conn.getPortNumber()).toString()); setHostInfo(hostInfo);
}
....
}

 
3.
Obtain MHostInfo back inside onTermination() method and set AppState to STOPPED. The onTermination() method is called when MApp.stop() is called, which happens when the standard Hawk method stopApplicationInstance() is invoked or by wrapper shutdown function (shown below).

 
protected void onTermination() throws MException
{
    // update HostInfo to STOPPED
    getTrace().trace("AEZAP-2000", null, "onTermination: stopping     adapter");
    MHostInfo hostInfo = getHostInfo();     hostInfo.setAppState(MUserApplicationState.STOPPED);     setHostInfo(hostInfo);
}

 
4.
In the wrapper's shutdown function, (Note that this function is used by wrapper --stop), call MApp.stop() to shut down the adapter correctly, that is, do the cleanup specified in MApp.onTermination().

 
public void shutdown()
{
try {
// set service state to stopping
MHostInfo hostInfo = new MHostInfo(app);
hostInfo.setAppState(MUserApplicationState.STOPPING);
app.setHostInfo(hostInfo);
  // Stop adapter, this will call MApp.onTermination()
  app.stop();
  } catch (Exception ex) {
   System.out.println( "shutdown: " + ex);
    ex.printStackTrace();
  }
}

 
Adding MAdapterServiceInfo
Adapter services are defined in terms of a service name, endpoint, and associated schema class(es). Adapters must register all its services either by enumeration of all endpoint components or simply by component name. For each service, the application must call set (serviceName, endpointName, schema) to register the adapter service.
Inside onInitialization() retrieves all publisher/subscriber, client/server endpoints with their associated schema and registers them as adapter services using MAdapterServiceInfo.

 
onInitialization()
{
...
 
//** Register publisher service
     MAdapterServiceInfo appInfo = new MAdapterServiceInfo();      Enumeration classEnum = pub.getClassNames();
 
     //** Retrieve all class schema specified for this endpoint
     while ( classEnum.hasMoreElements() )
     {
        String schemaname = (String) classEnum.nextElement();         appInfo.set("Publish service", pub.getName(), schemaname);
     }
setAdapterServiceInfo(appInfo);
...
 
}

 
Implementing Custom Advisory Listener
Replace the default advisory listener with a custom advisory listener that sends messages to a log file instead of stdout.
Depending on the advisory subject, additional action can also be taken. For example, stop the adapter on a RVCM collision advisory. You can then access the log file using the TIBCO Administrator user interface. Note that the user can subclass from MAdvisoryListener and explicitly call the superclass callback directly to extend the default behavior.
To set a custom advisory listener, use the MApp::setAdvisoryListener() method.
1.

 
...
app = new TestAdapterCore( props );
...
app.setAdvisoryListener(new CustomAdvisoryListener(app));
...
app.start();

 
2.
User advisory listener should be implemented in a separate CustomAdvisoryListener class. This will log configured advisory messages into log file.
Implementing Standard ActiveEnterprise Tracing with MMessageBundle
To implement standard tracing in the code, the trace and debug methods must use the (errorCode, trackingInfo) form. For Java, the message bundle properties file can be used to store all error codes and messages.
The zapadapter.properties file contains the following information:

 
errorRole.Application.AEZAP-0001="Connection to Zap failed with parameters: %1"
errorRole.Application.AEZAP-0002="Connection to Zap failed or system unavailable: %1"
errorRole.Application.AEZAP-0003="Request to Zap failed with parameters: %1"
errorRole.Application.AEZAP-0999="Exception caught: %1"
debugRole.Application.AEZAP-1000="debugTrace: %1"
infoRole.Application.AEZAP-2000="infoTrace: %1"

 
The zapdapter.properties file is loaded after MApp is instantiated and before MApp.start() is invoked.

 
app = new TestAdapterCore( props );
...
//** load application resource file MMessageBundle.addResourceBundle("zap", "zapadapter");
...
app.start();

 
A sample use of the error trace and info trace in onInitialization() method is as follows:

 
if (conn.connect())
    {
    //** Trace no tracking id, second param set to null     getTrace().trace("AEZAP-2000", null, "Successfully connected     to ZAP database");
    ...
    }
else
    {
    //** Trace with no tracking id     getTrace().trace("AEZAP-0002", null, "Fail to connect to ZAP     database");
    ...
    }

 
To include resources that depend on external files, such as the Java Activity in TIBCO ActiveMatrix BusinessWorks, you must create an AliasLibrary. Resources in the project can reference aliases in the AliasLibrary to resolve external file dependencies that they may have at runtime or debug time.
When building an enterprise archive file, the files referenced by the aliases defined in an AliasLibrary that you include in the project are included in the archive file. For more information, refer to the TIBCO Designer User’s Guide.

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