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:

4.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 boolean	deleteLog(String name) Deletes a given logfile.
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 File	getCurrentLogFolder() Get the location of the current FusionReactor log folder.
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 File	getLogfile(String name) Gets a File object representing the named log.
abstract int	getLogFileVersion() Get a string containing the version of the log files.
abstract long	getNextRotationTime() Get the next rotation time.
abstract long	getProbeInterval() Gets the interval, in milliseconds, of the internal resource-gathering probes.
abstract FusionRequestSurrogate	getRequest(long id) Get a request by ID.
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 com.intergral.fusionreactor.fac.scheduler.Scheduler	getScheduler() Gets a reference to the log rotation and FusionAnalytics Connector scheduler
abstract long	getStartedAt() Returns the time in ms since EPOCH that the monitor was started at
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 String	getUserCookieName() Gets the name of the cookie used for authentication.
abstract String	getUserCookieValue(String role) Gets the value of the cookie used for authentication.
abstract boolean	isFusionReactorRunning() Attempt to locate FusionReactor in memory and return a boolean indicating success or failure.
abstract boolean	isInitialized() Gets a boolean indicating whether FR has started up and is ready for FRAPI requests.
abstract boolean	isMemoryProtectionActive() Get a boolean describing whether Crash Protection's Memory Protection feature is enabled.
abstract boolean	isRequestProtectionActive() Get a boolean describing whether Crash Protection's Request Protection feature is enabled.
abstract boolean	isTimeoutProtectionActive() Get a boolean describing whether Crash Protection's Timeout Protection feature is enabled.
abstract int	kill(long fusionRequestId, String userTraceMarker) Kill a running request.
abstract void	log(String filename, String text) Write an INFORMATION entry to a log file
abstract void	log(String filename, String level, String text) Write a message to a log, with a given level.
abstract void	registerPlugin(com.intergral.fusionreactor.plugin.IPlugin plugin) Registers a dynamic plugin with the system.
abstract void	rotateLogs() Requests a log rotation now
abstract boolean	sendOsgiEventAsync(com.intergral.fusionreactor.api.event.IEvent event) Sends an event into the OSGi (Plugin) subsystem.
abstract com.intergral.fusionreactor.api.event.IEvent	sendOsgiEventSync(com.intergral.fusionreactor.api.event.IEvent event, String replyTopic, long timeout) Sends an event into the OSGi (Plugin) framework.
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	setRunningConfiguration(ConfigurationSurrogate config, boolean restart) Set a running configuration in the system, optionally restarting it.
abstract void	setVMOption(String name, String value) Set an option on the Java Virtual Machine
abstract void	subscribeOsgiEvent(String topic, com.intergral.fusionreactor.api.event.IEventHandler handler) Subscribes an IEventHandler within the OSGi plugin subsystem.
abstract void	trace(String traceString) Attach a user trace string to this request.
abstract void	unsubscribeOsgiEvent(com.intergral.fusionreactor.api.event.IEventHandler handler) Unsubscribe a given handler from the OSGi event system.
abstract boolean	wasShutdownCleanly() Gets a boolean indicating whether FR was shutdown cleanly last time.

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

isRequestProtectionActive

public abstract boolean isRequestProtectionActive()

Get a boolean describing whether Crash Protection's Request Protection feature is enabled.

Returns:

a boolean describing the state of Request Proteciton.

Since:

3.2.0

isTimeoutProtectionActive

public abstract boolean isTimeoutProtectionActive()

Get a boolean describing whether Crash Protection's Timeout Protection feature is enabled.

Returns:

a boolean describing the state of Timeout Protection.

Since:

3.2.0

isMemoryProtectionActive

public abstract boolean isMemoryProtectionActive()

Get a boolean describing whether Crash Protection's Memory Protection feature is enabled.

Returns:

a boolean describing the state of Memory Protection.

Since:

3.2.0

getLogFileVersion

public abstract int getLogFileVersion()

Get a string containing the version of the log files. This string is incremented when fields are added or removed.

Returns:

a String containing the version numer of the log files.

Since:

3.2.0

getRequest

public abstract FusionRequestSurrogate getRequest(long id)

Get a request by ID.

Parameters:

id - the ID of the request being sought.

Returns:

a FusionRequestSurrogate if the request could be located in the running request map, or the history list. If not, null is returned.

log

public abstract void log(String filename,
                         String level,
                         String text)

Write a message to a log, with a given level.

Parameters:

filename - filename of the log to write to

level - one of INFO, WARN or SEVERE. null means a log level will not be written

text - text entry to write to the log

log

public abstract void log(String filename,
                         String text)

Write an INFORMATION entry to a log file

Parameters:

filename - filename of the log to write to

text - text entry to write to the log

Since:

4.0

setVMOption

public abstract void setVMOption(String name,
                                 String value)

Set an option on the Java Virtual Machine

Parameters:

name - name of the option to set

value - value for the option

Since:

4.0

getStartedAt

public abstract long getStartedAt()

Returns the time in ms since EPOCH that the monitor was started at

Since:

1.0

rotateLogs

public abstract void rotateLogs()

Requests a log rotation now

Since:

4.0

registerPlugin

public abstract void registerPlugin(com.intergral.fusionreactor.plugin.IPlugin plugin)

Registers a dynamic plugin with the system.

Parameters:

plugin - the plugin to register.

Since:

4.0

getScheduler

public abstract com.intergral.fusionreactor.fac.scheduler.Scheduler getScheduler()

Gets a reference to the log rotation and FusionAnalytics Connector scheduler

Returns:

a Scheduler from where log rotations and FusionAnalytics Connector can be triggered.

Since:

4.0

getProbeInterval

public abstract long getProbeInterval()

Gets the interval, in milliseconds, of the internal resource-gathering probes.

Returns:

an interval in milliseconds.

Since:

4.0

getCurrentLogFolder

public abstract File getCurrentLogFolder()

Get the location of the current FusionReactor log folder. This will change after rotation.

Returns:

a File representing the current FR log folder.

Since:

4.0

getNextRotationTime

public abstract long getNextRotationTime()

Get the next rotation time.

Returns:

a long representing the next rotation time, as measured since the Java epoch (1.1.1970), or -1 if the rotation task is not active (log engine is in legacy mode) or has stopped.

Since:

4.0

getUserCookieName

public abstract String getUserCookieName()

Gets the name of the cookie used for authentication.

Returns:

a String containing the name of the cookie.

Since:

4.0

getUserCookieValue

public abstract String getUserCookieValue(String role)

Gets the value of the cookie used for authentication.

Parameters:

role - the role for which a cookie is required, one of "Administrator", "Manager" or "Observer"

Returns:

a cookie enabling passwordless access to FusionReactor.

Since:

4.0

isInitialized

public abstract boolean isInitialized()

Gets a boolean indicating whether FR has started up and is ready for FRAPI requests. If not,

Returns:

a boolean indicating whether FR is initialized and ready for FRAPI.

Since:

4.0

wasShutdownCleanly

public abstract boolean wasShutdownCleanly()

Gets a boolean indicating whether FR was shutdown cleanly last time.

Returns:

true if the system was shutdown cleanly, otherwise false.

Since:

4.0

getLogfile

public abstract File getLogfile(String name)

Gets a File object representing the named log.

Parameters:

name - the named of the log for which a file is required

Returns:

a File representing the named log (which may not exist yet)

Since:

4.0

deleteLog

public abstract boolean deleteLog(String name)

Deletes a given logfile.

Parameters:

name - the name of the log being deleted.

Returns:

true if the log was deleted, otherwise false.

Since:

4.0

sendOsgiEventAsync

public abstract boolean sendOsgiEventAsync(com.intergral.fusionreactor.api.event.IEvent event)

Sends an event into the OSGi (Plugin) subsystem. Any bundles subscribed to the topic will receive the event. After the event has been sent, this method returns.

If no Event Admin service was available in the OSGi framework, the method returns false.

Parameters:

event - the event to be placed on the OSGi event bus.

Returns:

true if the event was sent.

Since:

4.0

sendOsgiEventSync

public abstract com.intergral.fusionreactor.api.event.IEvent sendOsgiEventSync(com.intergral.fusionreactor.api.event.IEvent event,
                                                                               String replyTopic,
                                                                               long timeout)

Sends an event into the OSGi (Plugin) framework. Any bundles subscribed to the topic will receive the event. The system then waits for a reply on the event bus, with the given topic, waiting for at most timeout milliseconds.

Any bundle may generate the reply event. If more than one reply event is sent by a bundle, the first one is used.

Although the method is able to wait indefinitely for a reply, this is strongly discouraged since OSGi bundles can be removed and restarted with no notice.

Parameters:

event - the event to be placed on the OSGi event bus.

replyTopic - the topic of the event to be waited for in reply

timeout - a timeout value in milliseconds. If no reply is received after this timeout, null is returned. -1 signifies the method should wait indefinitely.

Returns:

the event generated in response.

Since:

4.0

subscribeOsgiEvent

public abstract void subscribeOsgiEvent(String topic,
                                        com.intergral.fusionreactor.api.event.IEventHandler handler)

Subscribes an IEventHandler within the OSGi plugin subsystem. Whenever a topic is raised with the given passed string, the event handler is called.

Any bundle may generate the given event. The passed topic may conform to any valid OSGi topic string, i.e. may contain a single trailing wildcard.

If no Event Admin service was available in the OSGi framework, no events will be raised.

Parameters:

topic - the topic being subscribed to.

handler - an IEventHandler capable of receiving events.

unsubscribeOsgiEvent

public abstract void unsubscribeOsgiEvent(com.intergral.fusionreactor.api.event.IEventHandler handler)

Unsubscribe a given handler from the OSGi event system.

If the given handler is not actually subscribed to any events, the method returns immediately.

Parameters:

handler - the handler being unsubscribed.

Since:

4.0

setRunningConfiguration

public abstract void setRunningConfiguration(ConfigurationSurrogate config,
                                             boolean restart)
                                      throws ConfigurationInvalidExceptionSurrogate,
                                             FileNotFoundException,
                                             IOException

Set a running configuration in the system, optionally restarting it. If the changed keys require a restart to take effect, supply true as the second parameter.

Parameters:

config - the configuration to be set.

restart - causes the system to restart.

Throws:

IOException

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:

4.0