sofya.ed.semantic
Interface EventSpecification

All Known Implementing Classes:

AbstractEventSpecification, AllEvents, AllModuleEvents, AtomicityEvents, ModuleDescription

public interface EventSpecification

Defines the interface to be implemented by classes which supply a specification of events to be produced by a SemanticEventDispatcher.

Version:

12/07/2005

Author:

Alex Kinneer

Nested Class Summary

static class	EventSpecification.CallType Type-safe enumeration for the invoke instructions.
static class	EventSpecification.FieldType Type-safe enumeration for the field related instructions.
static class	EventSpecification.MethodAction Type-safe enumeration for the method entry and exit events.
static class	EventSpecification.MonitorType Type-safe enumeration for the monitor events.

Field Summary

static int	FIELD_WITNESS_NONE Bitmask which indicates that no events should be witnessed for a field.
static int	FIELD_WITNESS_READ Bitmask to check the bit specifying that read events should be witnessed for a field.
static int	FIELD_WITNESS_WRITE Bitmask to check the bit specifying that write events should be witnessed for a field.

Method Summary

EventSpecification	deserialize(java.io.DataInputStream stream) Deserializes the specification from binary data.
java.util.Set	getModuleClasses(boolean asStrings) Gets the set of classes comprising the module.
java.util.Set	getSystemClasses(boolean asStrings) Gets the set of classes comprising the entire system.
void	serialize(java.io.DataOutputStream stream) Serializes the specification as binary data.
boolean	useCallInterceptor(org.apache.bcel.generic.InvokeInstruction call, org.apache.bcel.generic.ConstantPoolGen cpg) Checks whether a method call should be observed using an "interceptor" that can provide additional data about the call.
boolean	witnessAnyMonitor(EventSpecification.MonitorType type, org.apache.bcel.generic.MethodGen inMethod) Checks whether any monitor events of a given type occurring in a given location are included in the specification.
boolean	witnessCall(org.apache.bcel.generic.InvokeInstruction call, org.apache.bcel.generic.ConstantPoolGen cpg, org.apache.bcel.generic.MethodGen inMethod) Checks whether a method call in a given location is included in the specification.
boolean	witnessCatch(java.lang.String exceptionClass) Checks whether the catching of an exception of a given class is included in the specification; that is, there is some location at which catching an exception of the given class is considered an observable event.
boolean	witnessCatch(java.lang.String exceptionClass, org.apache.bcel.generic.MethodGen inMethod) Checks whether the catching of an exception of a given class at a given location is included in the specification.
boolean	witnessConstructorEntry(org.apache.bcel.generic.MethodGen mg) Checks whether entry into a constructor is included in the specification.
boolean	witnessConstructorExit(org.apache.bcel.generic.MethodGen mg) Checks whether exit from a constructor is included in the specification.
boolean	witnessField(org.apache.bcel.generic.FieldInstruction fi, org.apache.bcel.generic.ConstantPoolGen cpg, org.apache.bcel.generic.MethodGen inMethod) Checks whether the field referenced by a field instruction in a given location is part of the specification and should be witnessed.
int	witnessField(java.lang.String fieldName, boolean isStatic) Checks whether a named field is included in the specification.
boolean	witnessField(java.lang.String fieldName, EventSpecification.FieldType fType, java.lang.String className, java.lang.String methodName, java.lang.String signature) Checks whether a field event occurring in a given location is included in the specification.
boolean	witnessMethodEntry(org.apache.bcel.generic.MethodGen mg) Checks whether entry into a method is included in the specification.
boolean	witnessMethodExit(org.apache.bcel.generic.MethodGen mg) Checks whether exit from a method is included in the specification.
boolean	witnessMonitor(java.lang.String className, EventSpecification.MonitorType type) Checks whether events associated with monitors on instances of a given class should be witnessed.
boolean	witnessNewObject(java.lang.String newClass, org.apache.bcel.generic.MethodGen inMethod) Checks whether an allocation of a class by a NEW instruction in a given location should be witnessed (is part of the specification).
boolean	witnessStaticInitializerEntry(java.lang.String className) Checks whether entry into a static intializer is included in the specification.
boolean	witnessThrow(java.lang.String exceptionClass) Checks whether the throwing of an exception of a given class is included in the specification; that is, there is some location from which throwing an exception of the given class is considered an observable event.
boolean	witnessThrow(java.lang.String exceptionClass, java.lang.String className, java.lang.String methodName, java.lang.String signature) Checks whether the throwing of an exception of a given class from a given location is included in the specification.

Field Detail

FIELD_WITNESS_NONE

static final int FIELD_WITNESS_NONE

Bitmask which indicates that no events should be witnessed for a field.

See Also:

Constant Field Values

FIELD_WITNESS_READ

static final int FIELD_WITNESS_READ

Bitmask to check the bit specifying that read events should be witnessed for a field.

See Also:

Constant Field Values

FIELD_WITNESS_WRITE

static final int FIELD_WITNESS_WRITE

Bitmask to check the bit specifying that write events should be witnessed for a field.

See Also:

Constant Field Values

Method Detail

getSystemClasses

java.util.Set getSystemClasses(boolean asStrings)

Gets the set of classes comprising the entire system.

Parameters:

asStrings - Specifies whether the returned set should directly contain the class names as strings. If false, the set will contain ProgramUnits containing the classes.

Returns:

An unmodifiable set containing all of the classes in the system.

getModuleClasses

java.util.Set getModuleClasses(boolean asStrings)

Gets the set of classes comprising the module.

Parameters:

asStrings - Specifies whether the returned set should directly contain the class names as strings. If false, the set will contain ProgramUnits containing the classes.

Returns:

An unmodifiable set containing all of the classes for which observables are included unless otherwise constrained.

witnessNewObject

boolean witnessNewObject(java.lang.String newClass,
                         org.apache.bcel.generic.MethodGen inMethod)

Checks whether an allocation of a class by a NEW instruction in a given location should be witnessed (is part of the specification).

Parameters:

newClass - Name of the class to check for inclusion.

inMethod - Method in which the NEW instruction is executed.

Returns:

true if the NEW instruction is included in the specification and should be observed.

witnessField

boolean witnessField(org.apache.bcel.generic.FieldInstruction fi,
                     org.apache.bcel.generic.ConstantPoolGen cpg,
                     org.apache.bcel.generic.MethodGen inMethod)

Checks whether the field referenced by a field instruction in a given location is part of the specification and should be witnessed.

Parameters:

fi - Field instruction to be checked for inclusion in the specification.

cpg - Constant pool for the class containing the instruction.

inMethod - Method in which the field instruction is executed.

Returns:

true if the field is part of the specification.

witnessField

boolean witnessField(java.lang.String fieldName,
                     EventSpecification.FieldType fType,
                     java.lang.String className,
                     java.lang.String methodName,
                     java.lang.String signature)

Checks whether a field event occurring in a given location is included in the specification.

Parameters:

fieldName - Fully qualified name of the field to be checked for inclusion in the specification.

fType - Type of the field to be checked for inclusion.

className - Name of the class in which the field instruction is executed.

methodName - Name of the the method in which the field instruction is executed.

signature - JDI-style signature of the method in which the instruction is executed.

Returns:

true if the specified field event occurring in the given method should be observed.

witnessField

int witnessField(java.lang.String fieldName,
                 boolean isStatic)

Checks whether a named field is included in the specification.

This method is permitted to be heuristic, in the sense that it may in some circumstances indicate that a field is observable in some way when in fact it is not. A correct response should be attempted on a best-effort basis.

Parameters:

fieldName - Fully qualified name of the field to be checked for inclusion in the specification.

isStatic - Specifies whether it is a static field.

Returns:

A bitmask indicating which events on the field should be witnessed. If no bits are set, the field should not be witnessed at all. If the lowest bit is set, reads from the field should be witnessed. If the second lowest bit is set, writes to the field should be witnessed.

witnessCall

boolean witnessCall(org.apache.bcel.generic.InvokeInstruction call,
                    org.apache.bcel.generic.ConstantPoolGen cpg,
                    org.apache.bcel.generic.MethodGen inMethod)

Checks whether a method call in a given location is included in the specification.

Parameters:

call - Invoke instruction to be checked for exclusion in the specification.

cpg - Constant pool for the class containing the invoke instruction.

inMethod - Method in which the call is executed.

Returns:

true if the call is to a method included in the specification.

useCallInterceptor

boolean useCallInterceptor(org.apache.bcel.generic.InvokeInstruction call,
                           org.apache.bcel.generic.ConstantPoolGen cpg)

Checks whether a method call should be observed using an "interceptor" that can provide additional data about the call.

The principle benefit of witnessing a call using an interceptor is that the values of the arguments to the method can be obtained. Important information can be obtained about calls for which subsequent EventListener.virtualMethodEnterEvent(sofya.ed.semantic.EventListener.ThreadData, sofya.ed.semantic.EventListener.ObjectData, sofya.ed.semantic.EventListener.MethodData)s cannot be raised, either because it is not possible (such as with native methods), or desirable (such as with Thread.start() or Thread.join() methods). However, there is considerable extra cost and potential interference associated with an interceptor, so they generally should not be used for other method calls.

Parameters:

call - Invoke instruction to be checked for observation using an interceptor.

cpg - Constant pool for the class containing the invoke instruction.

Returns:

true if the call is to a method that should be witnessed using an interceptor.

witnessConstructorEntry

boolean witnessConstructorEntry(org.apache.bcel.generic.MethodGen mg)

Checks whether entry into a constructor is included in the specification.

Parameters:

mg - Constructor to be checked for inclusion in the specification.

Returns:

true if entry into the constructor is included in the specification.

witnessConstructorExit

boolean witnessConstructorExit(org.apache.bcel.generic.MethodGen mg)

Checks whether exit from a constructor is included in the specification.

Parameters:

mg - Constructor to be checked for inclusion in the specification.

Returns:

true if exit from the constructor is included in the specification.

witnessMethodEntry

boolean witnessMethodEntry(org.apache.bcel.generic.MethodGen mg)

Checks whether entry into a method is included in the specification.

This query treats interface methods as virtual methods since they are also dynamically bound, a behavior that distinguishes this query from the call invocation events where interface method calls and other virtual calls are treated as distinct events.

Parameters:

mg - Virtual method to be checked for inclusion in the specification.

Returns:

true if entry into the virtual method is included in the specification.

witnessMethodExit

boolean witnessMethodExit(org.apache.bcel.generic.MethodGen mg)

Checks whether exit from a method is included in the specification.

This query treats interface methods as virtual methods since they are also dynamically bound, a behavior that distinguishes this query from the call invocation events where interface method calls and other virtual calls are treated as distinct events.

Parameters:

mg - Virtual method to be checked for inclusion in the specification.

Returns:

true if exit from the virtual method is included in the specification.

witnessAnyMonitor

boolean witnessAnyMonitor(EventSpecification.MonitorType type,
                          org.apache.bcel.generic.MethodGen inMethod)

Checks whether any monitor events of a given type occurring in a given location are included in the specification.

This is a helper method which is used by the instrumentor to optimize away the associated instrumentation if no monitor events of a certain type are to be witnessed at all.

Parameters:

type - Monitor event type for which the check should be performed.

inMethod - Method in which the monitor events are executed.

Returns:

true if monitor events of the specified type may be witnessed, false otherwise.

witnessMonitor

boolean witnessMonitor(java.lang.String className,
                       EventSpecification.MonitorType type)

Checks whether events associated with monitors on instances of a given class should be witnessed.

Parameters:

className - Fully qualified name of the class to be checked for monitor event inclusion in the specification.

type - Type of monitor event.

Returns:

true if the given monitor events should be witnessed for monitors on instances of the given class, false otherwise.

witnessThrow

boolean witnessThrow(java.lang.String exceptionClass,
                     java.lang.String className,
                     java.lang.String methodName,
                     java.lang.String signature)

Checks whether the throwing of an exception of a given class from a given location is included in the specification.

Parameters:

exceptionClass - Fully qualified name of the exception class to be checked for inclusion in the specification.

className - Name of the class in which the throw occurs.

methodName - Name of the the method in which the throw occurs.

signature - JDI-style signature of the method in which the throw occurs.

Returns:

true if the throwing of the given exception from the specified location should be observed, false otherwise.

witnessThrow

boolean witnessThrow(java.lang.String exceptionClass)

Checks whether the throwing of an exception of a given class is included in the specification; that is, there is some location from which throwing an exception of the given class is considered an observable event.

Parameters:

exceptionClass - Fully qualified name of the exception class to be checked for inclusion in the specification.

Returns:

true if the throwing of the given exception from some location in the program should be observed, false otherwise.

witnessCatch

boolean witnessCatch(java.lang.String exceptionClass,
                     org.apache.bcel.generic.MethodGen inMethod)

Checks whether the catching of an exception of a given class at a given location is included in the specification.

Parameters:

exceptionClass - Fully qualified name of the exception class to be checked for inclusion in the specification.

inMethod - Method in which the catch occurs.

Returns:

true if the catching of the given exception at the specified location should be observed, false otherwise.

witnessCatch

boolean witnessCatch(java.lang.String exceptionClass)

Checks whether the catching of an exception of a given class is included in the specification; that is, there is some location at which catching an exception of the given class is considered an observable event.

Parameters:

exceptionClass - Fully qualified name of the exception class to be checked for inclusion in the specification.

Returns:

true if the catching of the given exception at some location in the program should be observed, false otherwise.

witnessStaticInitializerEntry

boolean witnessStaticInitializerEntry(java.lang.String className)

Checks whether entry into a static intializer is included in the specification.

Parameters:

className - Fully qualified name of the class containing the static initializer to be checked for inclusion in the specification.

Returns:

true if entry into the static initializer is included in the specification.

serialize

void serialize(java.io.DataOutputStream stream)
               throws java.io.IOException

Serializes the specification as binary data.

Parameters:

stream - Stream to which the specification is serialized.

Throws:

java.io.IOException - On any I/O error that prevents serialization.

deserialize

EventSpecification deserialize(java.io.DataInputStream stream)
                               throws java.io.IOException

Deserializes the specification from binary data.

An instance of the class will need to be instantiated first, likely by reflection. If called on an existing instance, that specification will be destroyed (overwritten).

Parameters:

stream - Stream from which the specification is deserialized.

Returns:

A reference to the specification.

Throws:

java.io.IOException - On any I/O error that prevents deserialization.