com.intergral.fusionreactor.api
Class FRAPI

java.lang.Object
  com.intergral.fusionreactor.api.FRAPI

public abstract class FRAPI
extends Object

This class defines the public interface to FusionReactor.

All API calls internally check whether FusionReactor is available before proceding. Storing references to objects produced by this type any longer than strictly necessary (certainly not longer than the course of a single page request) is strongly discouraged, in order to reduce the scope for memory leaks. This object itself may be stored and reused if required.

This is a factory-type class; you must not instantiate it yourself, rather use the getInstance() method.

Since:

2.0

Version:

2.0

Field Summary

static int	KILL_STATUS_ALREADY_DISPOSED Indicates this request has already been disposed of, i.e.
static int	KILL_STATUS_ALREADY_NOTIFIED Indicates this request has already been notified of a kill action by some other mechanism.
static int	KILL_STATUS_KILLED Indicates this request was killed.

Method Summary

abstract String	explainKillStatus(int killStatus) Explain a given kill result value.
static FRAPI	getInstance() Get a concrete instance of the FusionReactor API, on which further calls can be made.
abstract ConfigurationSurrogate	getRunningConfiguration() Return a deep-clone of the currently running configuration.
abstract FusionRequestSurrogate[]	getRunningRequests() Return an array containing objects representing all requests currently being tracked by FusionReactor.
abstract boolean	isFusionReactorRunning() Attempt to locate FusionReactor in memory and return a boolean indicating success or failure.
abstract int	kill(long fusionRequestId, String userTraceMarker) Kill a running request.
abstract void	setPageTimeout(int seconds) Reset the timeout value for this page.
abstract void	setRequestCaptureFolder(String fullPath) Change the location to which Request Capture will store request and response data.
abstract void	setRunningConfiguration(ConfigurationSurrogate configurationSurrogate) Set the running configuration to the passed ConfigurationSurrogate.
abstract void	trace(String traceString) Attach a user trace string to this request.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

KILL_STATUS_ALREADY_DISPOSED

public static final int KILL_STATUS_ALREADY_DISPOSED

Indicates this request has already been disposed of, i.e. already completed or killed.

See Also:

Constant Field Values

KILL_STATUS_ALREADY_NOTIFIED

public static final int KILL_STATUS_ALREADY_NOTIFIED

Indicates this request has already been notified of a kill action by some other mechanism.

See Also:

Constant Field Values

KILL_STATUS_KILLED

public static final int KILL_STATUS_KILLED

Indicates this request was killed.

See Also:

Constant Field Values

Method Detail

getInstance

public static final FRAPI getInstance()

Get a concrete instance of the FusionReactor API, on which further calls can be made.

Returns:

a concrete FusionReactor API instance.

Since:

2.0

trace

public abstract void trace(String traceString)

Attach a user trace string to this request. These strings are available within the FusionReactor GUI in the Request Details page, and also appear in the FusionReactor debug console.

If FusionReactor is not running, this method does nothing.

Parameters:

traceString - The string to be attached to this request.

Since:

2.0

isFusionReactorRunning

public abstract boolean isFusionReactorRunning()

Attempt to locate FusionReactor in memory and return a boolean indicating success or failure.

Returns:

a boolean indicating whether Fusion Reactor was detected and running.

Since:

2.0

setPageTimeout

public abstract void setPageTimeout(int seconds)

Reset the timeout value for this page. If Timeout Protection is not active within FusionReactor, calls to this method have no effect. If Timeout Protection is active, the value passed to this method overrides the value configured in FusionReactor.

If FusionReactor is not running, this method does nothing.

Parameters:

seconds - the timeout in seconds after which this page will be aborted.

Since:

2.0

getRunningRequests

public abstract FusionRequestSurrogate[] getRunningRequests()

Return an array containing objects representing all requests currently being tracked by FusionReactor. There is a small time penalty associated with this method, since it must temporarily lock FusionReactor to obtain the list of running requests.

N.b. By the time your code uses the objects returned by this method, they may have completed.

Returns:

an array of FusionRequestSurrogate objects representing all running tracked requests, or a zero-length array if FusionReactor was not detected.

Since:

2.0

getRunningConfiguration

public abstract ConfigurationSurrogate getRunningConfiguration()

Return a deep-clone of the currently running configuration. It is safe to manipulate this object.

Returns:

a ConfigurationSurrogate object constructed as a deep-clone of the running configuration, which may be manipulated safely.

Since:

2.0

setRunningConfiguration

public abstract void setRunningConfiguration(ConfigurationSurrogate configurationSurrogate)
                                      throws ConfigurationInvalidExceptionSurrogate,
                                             FileNotFoundException,
                                             IOException

Set the running configuration to the passed ConfigurationSurrogate. The sequence of actions is as follows:

• the configuration is checked for validity against the FusionReactor Configuration Key rules
• the configuration is saved to disk (reactor.conf, usually)
• the reference to the live configuration is altered to point to this one
• the running Fusion Reactor is signalled that the configuration has changed (this means that many subsystems are restarted).

Parameters:

configurationSurrogate - a ConfigurationSurrogate object representing the required configuration.

Throws:

ConfigurationInvalidExceptionSurrogate - if the configuration was invalid (examine the message of the exception to find out more)

FileNotFoundException - if the system could not find the file or folder into which the configuration should be saved

IOException - if the system encountered an IOException whilst saving the configuration to disk.

Since:

2.0

setRequestCaptureFolder

public abstract void setRequestCaptureFolder(String fullPath)
                                      throws ConfigurationInvalidExceptionSurrogate,
                                             IOException

Change the location to which Request Capture will store request and response data. Will cause FusionReactor to restart.

Parameters:

fullPath - a full path specifying a folder which exists on the system.

Throws:

ConfigurationInvalidExceptionSurrogate - with a descriptive message, if FusionReactor could not adopt the new configuration.

IOException - if FusionReactor could not open write a new configuration prior to adopting it.

Since:

2.0

kill

public abstract int kill(long fusionRequestId,
                         String userTraceMarker)

Kill a running request.

Parameters:

fusionRequestId - the ID of the request which is to be killed

userTraceMarker - if non-null and not an empty string, this trace marker will be stored with the request.

Returns:

an integer corresponding to the KILL_STATUS_* set of enumerations defined in this type.

Since:

2.0

explainKillStatus

public abstract String explainKillStatus(int killStatus)

Explain a given kill result value.

Parameters:

killStatus - the status to be explained.

Returns:

a concise English sentence explaining the kill status

Since:

2.0