de.uni_hildesheim.sse.monitoring.runtime.boot

Class RecorderFrontend

java.lang.Object

de.uni_hildesheim.sse.monitoring.runtime.boot.RecorderFrontend

Direct Known Subclasses:

Recorder

public abstract class RecorderFrontend
extends java.lang.Object

Defines a frontend to be called from instrumented code. This class helps separating the real recorder implementation from the calls. This is needed because this class is loaded (automatically by the agent) to the boot class path in order to be available also from (instrumented) Java library classes. If the real implementation would be available, this would disturb class loading and have negative effects on the instrumented program. Thus, the instrumentation is responsible for setting instance properly and instrumented code needs to call methods of the recorder (frontend) via this class.

Methods intended for Java monitoring are tagged with [Java call] and should not be called during native monitoring. Methods tagged with [native call] are intended for native monitoring and should not be called during Java monitoring except of indirect calls from [Java call] methods or in case that methods are tagged twice. We assume that System.nanoTime and System.currentTimeMillis work properly in a native environment. Required thread ids are indirectly obtained from IThreadDataGatherer.getCurrentId(). In case that the returned identifiers do not map to native identifiers, replace the native implementation of IThreadDataGatherer.

Since:

1.00

Version:

1.20

Author:

Holger Eichelberger

Field Summary

Fields

Modifier and Type	Field and Description
static RecorderFrontend	instance Stores the instance of this class.

Constructor Summary

Constructors

Constructor and Description
RecorderFrontend()

Method Summary

Modifier and Type	Method and Description
abstract void	assignAllTo(java.lang.String recId, boolean enter) Notifies that the following values (if not further calls to this method or other recording ids occur) should be assigned to the given recId.
abstract void	changeValueContext(java.lang.String id, boolean push) Notifies the recorder about changing the value context.
abstract void	clearTemporaryData() Notify that temporary data e.g. from instrumentation shall be cleared.
abstract void	configurationChange(java.lang.String ids) Notify the recorder that a new variability configuration might have been entered.
abstract void	enableVariabilityDetection(boolean enable) Changes if automated variability detection should be enabled or not.
abstract void	endSystem() Notifies about the end of the monitored program.
abstract void	enter(java.lang.String caller, java.lang.String recId, boolean exclude, boolean directId, long instanceId) Notifies the recorder about a method being called.
abstract void	exit(java.lang.String caller, java.lang.String recId, boolean exclude, boolean directId, long instanceId) Notifies the recorder about a method being exited.
abstract void	memoryAllocated(long tag, long size) Notifies the recorder about an object allocated to memory.
abstract void	memoryAllocated(java.lang.Object allocated) Notifies the recorder about an object allocated to memory.
abstract void	memoryAllocated(java.lang.Object tag, long size) Notifies the recorder about an object allocated to memory.
abstract void	memoryFreed(long tag, long size) Notifies the recorder about an object freed from memory.
abstract void	memoryFreed(java.lang.Object freed) Notifies the recorder about an object freed from memory.
abstract void	memoryFreed(java.lang.Object tag, long size) Notifies the recorder about an object freed from memory.
abstract void	notifyProgramEnd() Notifies about end of monitoring (this might occur at different point of time than endSystem() and at multiple times).
abstract void	notifyProgramStart() Notifies about start of monitoring.
abstract void	notifyThreadEnd() Notifies about the end of the current thread.
abstract void	notifyThreadEnd(long newThreadId) Notifies about an ended thread.
abstract void	notifyThreadStart(long newThreadId) Notifies about a started thread.
abstract void	notifyThreadStart(java.lang.Thread thread) Notifies about a started thread.
abstract void	notifyTimer(java.lang.String id, TimerState state, boolean considerThreads) Notifies about a timer event.
abstract void	notifyValueChange(java.lang.String recId, boolean newValue) Notifies the recorder about a changing value.
abstract void	notifyValueChange(java.lang.String recId, byte newValue) Notifies the recorder about a changing value.
abstract void	notifyValueChange(java.lang.String recId, char newValue) Notifies the recorder about a changing value.
abstract void	notifyValueChange(java.lang.String recId, double newValue) Notifies the recorder about a changing value.
abstract void	notifyValueChange(java.lang.String recId, float newValue) Notifies the recorder about a changing value.
abstract void	notifyValueChange(java.lang.String recId, int newValue) Notifies the recorder about a changing value.
abstract void	notifyValueChange(java.lang.String recId, long newValue) Notifies the recorder about a changing value.
abstract void	notifyValueChange(java.lang.String recId, java.lang.Object newValue) Notifies the recorder about a changing value.
abstract void	notifyValueChange(java.lang.String recId, short newValue) Notifies the recorder about a changing value.
abstract void	notifyValueChange(java.lang.String recId, java.lang.String newValue) Notifies the recorder about a changing value.
abstract void	printCurrentState() Prints the current (aggregated) state to the output formatter.
abstract void	printStatistics() Emits the values collected so far.
abstract int	readIo(java.lang.String recId, java.lang.String caller, int bytes, StreamType type) Notifies the recorder about an amount of bytes read from some I/O channel.
abstract void	registerAsOverheadStream(java.io.InputStream in) Register the given input stream as overhead stream, i.e. set the attribute added by instrumentation via reflection so that the recorder is notified.
abstract void	registerAsOverheadStream(java.io.OutputStream out) Register the given output stream as overhead stream, i.e. set the attribute added by instrumentation via reflection so that the recorder is notified.
abstract void	registerForRecording(java.lang.String className, MonitoringGroupSettings settings) Registers a given class for recording.
abstract void	registerThisThread(boolean register) Registers a JVM thread with its native counterpart.
abstract int	writeIo(java.lang.String recId, java.lang.String caller, int bytes, StreamType type) Notifies the recorder about an amount of bytes written to some I/O channel.

Methods inherited from class java.lang.Object

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

Field Detail

instance

public static RecorderFrontend instance

Stores the instance of this class. At runtime we assume that this attribute is initialized properly and never null when the instrumenter is running.

Constructor Detail

RecorderFrontend

public RecorderFrontend()

Method Detail

registerForRecording

public abstract void registerForRecording(java.lang.String className,
                                          MonitoringGroupSettings settings)

Registers a given class for recording. Optional, a (group) of ids might be specified to which the measurements are assigned to. Ids are unique strings without inherent semantics. If not given, the className is used for grouping and assigning measurements (implicit 1-groups). [Java call, native call]

Parameters:

className - the name of the class measurements should be registered for

settings - the monitoring group settings including all configuration information (reference should not be stored, will be freed explicitly)

Since:

1.00

registerAsOverheadStream

public abstract void registerAsOverheadStream(java.io.InputStream in)

Register the given input stream as overhead stream, i.e. set the attribute added by instrumentation via reflection so that the recorder is notified. [Java call]

Parameters:

in - the stream to be registered

Since:

1.00

registerAsOverheadStream

public abstract void registerAsOverheadStream(java.io.OutputStream out)

Register the given output stream as overhead stream, i.e. set the attribute added by instrumentation via reflection so that the recorder is notified. [Java call]

Parameters:

out - the stream to be registered

Since:

1.00

notifyProgramStart

public abstract void notifyProgramStart()

Notifies about start of monitoring. [Java call, native call]

Since:

1.00

notifyProgramEnd

public abstract void notifyProgramEnd()

Notifies about end of monitoring (this might occur at different point of time than endSystem() and at multiple times). [Java call, native call]

Since:

1.00

enableVariabilityDetection

public abstract void enableVariabilityDetection(boolean enable)

Changes if automated variability detection should be enabled or not. [Java call, native call]

Parameters:

enable - true if it should be enabled (can be switched off by annotation) or if manual notification via annotation should be considered only

Since:

1.00

notifyThreadStart

public abstract void notifyThreadStart(java.lang.Thread thread)

Notifies about a started thread. [Java call]

Parameters:

thread - the started thread

Since:

1.00

notifyThreadStart

public abstract void notifyThreadStart(long newThreadId)

Notifies about a started thread. [native call]

Parameters:

newThreadId - the identification of the started thread

Since:

1.00

notifyThreadEnd

public abstract void notifyThreadEnd()

Notifies about the end of the current thread. [Java call]

Since:

1.00

notifyThreadEnd

public abstract void notifyThreadEnd(long newThreadId)

Notifies about an ended thread. [native call]

Parameters:

newThreadId - the identification of the ended thread

Since:

1.00

assignAllTo

public abstract void assignAllTo(java.lang.String recId,
                                 boolean enter)

Notifies that the following values (if not further calls to this method or other recording ids occur) should be assigned to the given recId. [Java call, native call]

Parameters:

recId - the recording id (may be also the variability prefix)

enter - true if this is a method enter event, false else

Since:

1.00

printStatistics

public abstract void printStatistics()

Emits the values collected so far. [Java call, native call]

Since:

1.00

endSystem

public abstract void endSystem()

Notifies about the end of the monitored program. [Java call, native call]

Since:

1.00

enter

public abstract void enter(java.lang.String caller,
                           java.lang.String recId,
                           boolean exclude,
                           boolean directId,
                           long instanceId)

Notifies the recorder about a method being called. [Java call, native call]

Parameters:

caller - the type of the caller

recId - the recorder id (may be null)

exclude - is this an exclusion from monitoring

directId - is recId direct, e.g. in case of an annotated method

instanceId - the optional instance identifier, 0 means disabled

Since:

1.20

exit

public abstract void exit(java.lang.String caller,
                          java.lang.String recId,
                          boolean exclude,
                          boolean directId,
                          long instanceId)

Notifies the recorder about a method being exited. [Java call, native call]

Parameters:

caller - the type of the caller

recId - the recorder id (may be null)

exclude - is this an exclusion from monitoring

directId - is recId direct, e.g. in case of an annotated method

instanceId - the optional instance identifier, 0 means disabled

Since:

1.00

configurationChange

public abstract void configurationChange(java.lang.String ids)

Notify the recorder that a new variability configuration might have been entered. The recorder should resolve the concrete configuration by tracking the configuration activations. [Java call, native call]

Parameters:

ids - an optional list of group identifications

Since:

1.00

memoryAllocated

public abstract void memoryAllocated(java.lang.Object allocated)

Notifies the recorder about an object allocated to memory. Please note that dependent on the concrete instrumentation not all allocated objects might be cleaned up. [Java call]

Parameters:

allocated - the allocated

Since:

1.00

memoryAllocated

public abstract void memoryAllocated(java.lang.Object tag,
                                     long size)

Notifies the recorder about an object allocated to memory. This method is required for explicit notifications. [Java call]

Parameters:

tag - an object which serves as the identification for object size to be freed

size - the allocated memory size

Since:

1.00

memoryAllocated

public abstract void memoryAllocated(long tag,
                                     long size)

Notifies the recorder about an object allocated to memory. that dependent on the concrete instrumentation not all allocated objects might be cleaned up. [native call]

Parameters:

tag - the identification of the memory object, e.g. its memory address

size - the allocated memory size

Since:

1.00

memoryFreed

public abstract void memoryFreed(java.lang.Object freed)

Notifies the recorder about an object freed from memory. Please note that dependent on the concrete instrumentation not all memory frees might be detected, e.g. those of immediate system classes (e.g. Object cannot be instrumented, garbage collector not called when JVM is running, etc.). [Java call]

Parameters:

freed - the freed object

Since:

1.00

memoryFreed

public abstract void memoryFreed(java.lang.Object tag,
                                 long size)

Notifies the recorder about an object freed from memory. This method is required for explicit notifications. [Java call]

Parameters:

tag - an object which serves as the identification for object size to be freed

size - the size of the freed object

Since:

1.00

memoryFreed

public abstract void memoryFreed(long tag,
                                 long size)

Notifies the recorder about an object freed from memory. Please note that dependent on the concrete instrumentation not all memory frees might be detected, e.g. those of immediate system classes (e.g. Object cannot be instrumented, garbage collector not called when JVM is running, etc.). [Java call, native call]

Parameters:

tag - the identification of the object to be freed, e.g. its memory address

size - the size of the freed object

Since:

1.00

readIo

public abstract int readIo(java.lang.String recId,
                           java.lang.String caller,
                           int bytes,
                           StreamType type)

Notifies the recorder about an amount of bytes read from some I/O channel. [Java call, native call]

Parameters:

recId - an the target group identification

caller - the type of the caller

bytes - the number of bytes

type - the type of the channel

Returns:

bytes

Since:

1.00

writeIo

public abstract int writeIo(java.lang.String recId,
                            java.lang.String caller,
                            int bytes,
                            StreamType type)

Notifies the recorder about an amount of bytes written to some I/O channel. [Java call, native call]

Parameters:

recId - an the target group identification

caller - the type of the caller

bytes - the number of bytes

type - the type of the channel

Returns:

bytes

Since:

1.00

changeValueContext

public abstract void changeValueContext(java.lang.String id,
                                        boolean push)

Notifies the recorder about changing the value context. [Java call, native call]

Parameters:

id - the value identification representing the context

push - if true push the context to the context stack, false else

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       java.lang.Object newValue)

Notifies the recorder about a changing value. [Java call, native call]

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       int newValue)

Notifies the recorder about a changing value. [Java call, native call]

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       byte newValue)

Notifies the recorder about a changing value. [Java call, native call]

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       char newValue)

Notifies the recorder about a changing value. [Java call, native call]

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       short newValue)

Notifies the recorder about a changing value. [Java call, native call]

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       long newValue)

Notifies the recorder about a changing value. [Java call, native call]

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       double newValue)

Notifies the recorder about a changing value. [Java call, native call]

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       float newValue)

Notifies the recorder about a changing value. [Java call, native call]

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       java.lang.String newValue)

Notifies the recorder about a changing value. [Java call, native call]

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

notifyValueChange

public abstract void notifyValueChange(java.lang.String recId,
                                       boolean newValue)

Notifies the recorder about a changing value.

Parameters:

recId - the recorder id (optional, may be null)

newValue - the value after the value change

Since:

1.00

printCurrentState

public abstract void printCurrentState()

Prints the current (aggregated) state to the output formatter. [Java call, native call]

Since:

1.00

notifyTimer

public abstract void notifyTimer(java.lang.String id,
                                 TimerState state,
                                 boolean considerThreads)

Notifies about a timer event. [Java call, native call]

Parameters:

id - the timer identification (may overlap with recorder ids)

state - the new timer state

considerThreads - false if the id is thread save and threads must not be considered explicitly, false else

Since:

1.00

registerThisThread

public abstract void registerThisThread(boolean register)

Registers a JVM thread with its native counterpart. Needed only if the JVM/JDK is not able to handle this, e.g. in 1.4 or Android. [Java call]

Parameters:

register - register or unregister the thread

Since:

1.00

clearTemporaryData

public abstract void clearTemporaryData()

Notify that temporary data e.g. from instrumentation shall be cleared. The specific cleanup implementation may decide upon this request whether a cleanup is actually required.

Since:

1.00