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:

1.5

Version:

3.0.1

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.
abstract long	getAllocatedMemory() Get the quantity of memory allocated to the JVM by the operating system.
abstract short	getCpuUsage() Get the current CPU usage.
abstract long	getFreeMemory() Get the quantity of free memory available to the VM, including any not yet allocated.
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 long	getStartTime() Get the time in milliseconds since the epoch at which the server was started.
abstract String	getStartTimeString() Get the system uptime as a date/time string of the form HH:mm:ss dd-MMM-yyyy
abstract long	getTotalMemory() Get the quantity of memory availble to the JVM, including any not yet allocated to it by the JVM.
abstract long	getUptime() Get the number of milliseconds since FusionReactor was last started.
abstract long	getUsedMemory() Get the quantity of memory currently allocated by the JVM to Java objects.
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

getFreeMemory

public abstract long getFreeMemory()

Get the quantity of free memory available to the VM, including any not yet allocated. This value represents the hard upper limit, after which Java will respond to further demand with OutOfMemoryError. This value is commonly influenced using the -Xmx JVM parameter.

Returns:

a long representing the quantity of unused memory in bytes.

Since:

2.0.3

getTotalMemory

public abstract long getTotalMemory()

Get the quantity of memory availble to the JVM, including any not yet allocated to it by the JVM. This value is commonly influenced using the -Xmx JVM parameter.

Returns:

a long representing the total quantity of memory available to the JVM in bytes.

Since:

2.0.3

getUsedMemory

public abstract long getUsedMemory()

Get the quantity of memory currently allocated by the JVM to Java objects.

Returns:

a long representing the total quantity of memory allocated to Java objects in bytes.

Since:

2.0.3

getAllocatedMemory

public abstract long getAllocatedMemory()

Get the quantity of memory allocated to the JVM by the operating system. This may vary as the JVM progressively requests and releases memory.

Returns:

the quantity of allocated memory in bytes.

Since:

2.0.3

getCpuUsage

public abstract short getCpuUsage()

Get the current CPU usage.

Returns:

a short describing the JVMs processor occupancy in percent, accross all cores. If CPU sampling is not supported on this platform, -1 is returned.

Since:

2.0.3

getStartTime

public abstract long getStartTime()

Get the time in milliseconds since the epoch at which the server was started. The epoch, for Java purposes, is defined as having its datum at midnight, January 1st 1970 UTC.

Returns:

the time at which the server was started.

Since:

2.0.3

getStartTimeString

public abstract String getStartTimeString()

Get the system uptime as a date/time string of the form HH:mm:ss dd-MMM-yyyy

Returns:

a user-friendly representation of the uptime of the system

Since:

2.0.3

getUptime

public abstract long getUptime()

Get the number of milliseconds since FusionReactor was last started.

Returns:

the number of milliseconds since FusionReactor was last started.

Since:

2.0.3