Package com.intergral.fusionreactor.api

Provides a public API to allow servlets, JSP, CF and other scripting languages to obtain information about the running state of FusionReactor.

See:
Description

Interface Summary

ConfigurationSurrogate	This interface specifies the public members of a FusionReactor Configuration object.
FusionRequestSurrogate	This interface specifies the available proxied information from an internal FusionRequest.

Class Summary

FRAPI

This class defines the public interface to FusionReactor.

Exception Summary

ConfigurationInvalidExceptionSurrogate

This class signals that the ConfigurationSurrogate whose validity was being tested was found to be invalid.

Package com.intergral.fusionreactor.api Description

Provides a public API to allow servlets, JSP, CF and other scripting languages to obtain information about the running state of FusionReactor.

This package uses a shared-memory mechanism to locate a running FusionReactor instance. If FusionReactor is not found, all API methods do something sane, in line with the philosophy that it should be possible to run FRAPI-enabled code without a running instance of FusionReactor.

This communication mechanism relies on the code calling the API to be within the same ClassLoader context as FusionReactor itself. This is normally the case, but can fail if your J2EE application server uses esoteric class context partitioning.

If you are encountering problems with FRAPI locating a running FusionReactor instance, it is usually worth investigating if your JSP/script pages are running in the same ClassLoader context as FusionReactor itself.

Objects produced by this API package are completely disconnected from objects instantiated internally by FusionReactor. It should therefore be safe to store references to objects produced by this package. However, it is good practice not to hold on to objects longer than necessary, in order to avoid memory leaks. Apart from the FRAPI object itself, we would not recommend storing references to objects produced by this package longer than the scope of a page request.

Example: Using FRAPI To List and Kill Requests

The following example illustrates how one might use FRAPI calls in ColdFusion to list and kill requests. The file should be saved as frapi_killtest.cfm.

<cfscript>

    // Get a FRAPI Class object and create an instance of it.
    FrapiClass = createObject("java", "com.intergral.fusionreactor.api.FRAPI");
    frapi = FrapiClass.getInstance();

    // If the URL 'id' parameter is defined, kill that ID and provide an
    // explanation of the result of the kill operation.
    if( IsDefined( "URL.id" ) )
    {
        WriteOutput("<pre>Killing: " & URL.id);        

        // If you supply a trace string, you can see it attached to this request
        // within the 'markers' view of the FusionReactor Request Details page.
        traceString = "FRAPI Killtest Script is killing " & URL.id;

        // Actually perform the kill.
        killStatus = frapi.kill( URL.id, "");

        // Ask FRAPI to explain the kill status in English to us
        explanation = frapi.explainKillStatus( killStatus );

        // Output all this information back to the page.
        WriteOutput( "<br><br>Kill Status: "
            & killStatus
            & ", Meaning: <i>" & explanation & "</i><br>" );
    }
    else
    {
        // Allow requests to be killed manually
        WriteOutput("<b>Enter a FusionRequest ID to kill, "
            & "or click a link from the list.</b><br><br>");

        WriteOutput("<form method='get' action='frapi_killtest.cfm'>
            FusionReactor ID: 
            <input type='text' name='id'>
            </form>");

        // List running requests
        runningRequests = frapi.getRunningRequests();

        WriteOutput( "<pre>" );

        for( index = 1; index LTE ArrayLen( runningRequests ); index = index + 1 )
        {
            // Read the individual details from each FusionRequestSurrogate object
            id = runningRequests[index].getFusionRequestId();
            requestUrl = runningRequests[index].getRequestUrl();
            start = runningRequests[index].getStartTimeMillis();

            // Output a list element.
            WriteOutput( "<a href='frapi_killtest.cfm?id=" & id & "'>"
                & "ID: " & id
                & "</a>, URL: " & requestUrl.toString()
                & ", Started: " & start
                & "<br>" );
        }

        WriteOutput( "</pre>" );
    }

</cfscript>