Class Instrumentor
- java.lang.Object
-
- org.jboss.byteman.contrib.dtest.Instrumentor
-
public class Instrumentor extends java.lang.Object
The Instrumentor provides for installing tracing and other rules into a remote JVM.
-
-
Field Summary
Fields Modifier and Type Field Description private java.lang.Class<?>
helperClass
private java.util.List<ScriptText>
installedScripts
private java.util.Map<java.lang.String,InstrumentedClass>
instrumentedClasses
private java.io.File
redirectedSubmissionsFile
private java.rmi.registry.Registry
registry
private int
rmiRegistryPort
private Submit
submit
-
Constructor Summary
Constructors Constructor Description Instrumentor()
Instrumentor(java.lang.String address, int port)
Instrumentor(java.lang.String address, int port, int rmiPort)
Instrumentor(Submit submit, int rmiRegistryPort)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description private void
appendToFile(java.io.File file, java.lang.String rule)
Write the given text to the end of the file.void
crashAtMethod(java.lang.String className, java.lang.String methodName, java.lang.String atInjection)
Inject a Rule to kill the target JVM at a given point within the specified Class.method()void
crashAtMethodEntry(java.lang.Class clazz, java.lang.String methodName)
Inject a Rule to kill the target JVM upon entry to the specified Class.method()void
crashAtMethodEntry(java.lang.String className, java.lang.String methodName)
Inject a Rule to kill the target JVM upon entry to the specified Class.method()void
crashAtMethodExit(java.lang.Class clazz, java.lang.String methodName)
Inject a Rule to kill the target JVM upon exit of the specified Class.method()void
crashAtMethodExit(java.lang.String className, java.lang.String methodName)
Inject a Rule to kill the target JVM upon exit of the specified Class.method()private ScriptText
findInstalledScript(java.lang.String scriptName)
Looping through installed scripts and checking if scriptName is there.java.lang.Class<?>
getHelperClass()
Returns a helper class which thisInstrumentor
instance defines as parameter ofHELPER
clause.java.io.File
getRedirectedSubmissionsFile()
Returns the file to which Rule submission is currently redirectedvoid
injectFault(java.lang.Class clazz, java.lang.String methodName, java.lang.Class<? extends java.lang.Throwable> fault, java.lang.Object[] faultArgs)
Inject a fault (i.e.void
injectOnCall(java.lang.Class clazz, java.lang.String methodName, java.lang.String action)
Inject an action to take place upon the invocation of the specified class.methodvoid
injectOnCall(java.lang.String className, java.lang.String methodName, java.lang.String action)
Inject an action to take place upon the invocation of the specified class.methodvoid
injectOnExit(java.lang.Class clazz, java.lang.String methodName, java.lang.String action)
Inject an action to take place upon exit of the specified class.methodvoid
injectOnExit(java.lang.String className, java.lang.String methodName, java.lang.String action)
Inject an action to take place upon exit of the specified class.methodvoid
injectOnMethod(java.lang.Class clazz, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String atInjection)
Inject an action to take place at a given point within the specified class.methodvoid
injectOnMethod(java.lang.String className, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String atInjection)
Inject an action to take place at a given point within the specified class.methodvoid
injectOnMethodWhere(java.lang.Class clazz, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String where)
Inject an action to take place at a given point within the specified class.methodvoid
injectOnMethodWhere(java.lang.String className, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String where)
Inject an action to take place at a given point within the specified class.methodvoid
installHelperJar(java.lang.String path)
Add the specified jar to the remote app's system classpath.java.lang.String
installRule(RuleConstructor builder)
Installing rule based on definition available by buildingRuleConstructor
.void
installScript(java.lang.String scriptName, java.lang.String scriptString)
Pass the assembled script to the remote JVM, either via.InstrumentedClass
instrumentClass(java.lang.Class clazz)
Add method tracing rules to the specified class.InstrumentedClass
instrumentClass(java.lang.Class clazz, java.lang.String... methodNames)
InstrumentedClass
instrumentClass(java.lang.Class clazz, java.util.Set<java.lang.String> methodNames)
Add method tracing rules to the specified class.InstrumentedClass
instrumentClass(java.lang.String className, java.lang.String... methodNames)
InstrumentedClass
instrumentClass(java.lang.String className, java.util.Set<java.lang.String> methodNames)
Add method tracing rules to the specified class name.
If a null set of method names is supplied,NullPointerException
is thrown.private boolean
isInterface(java.lang.String className)
Trying to load a class and if successful then check if class is interface.private InstrumentedClass
publish(java.lang.String className)
Create a local communication endpoint for the the given class.void
removeAllInstrumentation()
Flush any instrumentation for the given class in the remote system and clean up the local cache.void
removeLocalState()
Flush the local cache of scripts and proxies to remote instrumented classes.void
removeRule(RuleConstructor builder)
Removing particular script installed as a rule byRuleConstructor
.void
removeScript(java.lang.String scriptName)
Removing particular script from the remote byteman agent.void
setHelperClass(java.lang.Class<?> helperClass)
Redefine a helper class which is used as parameter ofHELPER
clause by this instance ofInstrumentor
void
setRedirectedSubmissionsFile(java.io.File redirectedSubmissionsFile)
Sets the file to which Rule submissions should be redirected.private void
unpublish(java.lang.String className)
Remove the local communication endpoint for the given class.
-
-
-
Field Detail
-
submit
private final Submit submit
-
registry
private final java.rmi.registry.Registry registry
-
rmiRegistryPort
private final int rmiRegistryPort
-
instrumentedClasses
private final java.util.Map<java.lang.String,InstrumentedClass> instrumentedClasses
-
installedScripts
private final java.util.List<ScriptText> installedScripts
-
redirectedSubmissionsFile
private java.io.File redirectedSubmissionsFile
-
helperClass
private java.lang.Class<?> helperClass
-
-
Constructor Detail
-
Instrumentor
public Instrumentor(Submit submit, int rmiRegistryPort) throws java.rmi.RemoteException
- Throws:
java.rmi.RemoteException
-
Instrumentor
public Instrumentor() throws java.rmi.RemoteException
- Throws:
java.rmi.RemoteException
-
Instrumentor
public Instrumentor(java.lang.String address, int port) throws java.rmi.RemoteException
- Throws:
java.rmi.RemoteException
-
Instrumentor
public Instrumentor(java.lang.String address, int port, int rmiPort) throws java.rmi.RemoteException
- Throws:
java.rmi.RemoteException
-
-
Method Detail
-
getRedirectedSubmissionsFile
public java.io.File getRedirectedSubmissionsFile()
Returns the file to which Rule submission is currently redirected- Returns:
- a file, or null if no redirection is in effect.
-
setRedirectedSubmissionsFile
public void setRedirectedSubmissionsFile(java.io.File redirectedSubmissionsFile)
Sets the file to which Rule submissions should be redirected.- Parameters:
redirectedSubmissionsFile
- a file, or null to cancel any existing redirection.
-
getHelperClass
public java.lang.Class<?> getHelperClass()
Returns a helper class which thisInstrumentor
instance defines as parameter ofHELPER
clause.- Returns:
- the helper class
-
setHelperClass
public void setHelperClass(java.lang.Class<?> helperClass)
Redefine a helper class which is used as parameter of
HELPER
clause by this instance ofInstrumentor
When setting you will probably create your own byteman helper class which extends the default one
BytemanTestHelper
.
You need to know what you are doing when setting this parameter different from default helper implementation as it provides core functionality fordtest
library.- Parameters:
helperClass
- the new helper class
-
installHelperJar
public void installHelperJar(java.lang.String path) throws java.lang.Exception
Add the specified jar to the remote app's system classpath.- Parameters:
path
- the absolute path to the .jar file.- Throws:
java.lang.Exception
- in case of failure.
-
instrumentClass
public InstrumentedClass instrumentClass(java.lang.Class clazz) throws java.lang.Exception
Add method tracing rules to the specified class.- Parameters:
clazz
- the Class to instrument.- Returns:
- a local proxy for the instrumentation.
- Throws:
java.lang.Exception
- in case of failure.
-
instrumentClass
public InstrumentedClass instrumentClass(java.lang.Class clazz, java.lang.String... methodNames) throws java.lang.Exception
- Throws:
java.lang.Exception
-
instrumentClass
public InstrumentedClass instrumentClass(java.lang.Class clazz, java.util.Set<java.lang.String> methodNames) throws java.lang.Exception
Add method tracing rules to the specified class. If a non-null set of method names is supplied, only those methods are instrumented.- Parameters:
clazz
- the Class to instrument.methodNames
- the selection of methods to instrument.- Returns:
- a local proxy for the instrumentation.
- Throws:
java.lang.Exception
- in case of failure.
-
instrumentClass
public InstrumentedClass instrumentClass(java.lang.String className, java.lang.String... methodNames) throws java.lang.Exception
- Parameters:
className
- the class name to instrument.methodNames
- the selection of methods to instrument.- Throws:
java.lang.Exception
- in case of failure.
-
instrumentClass
public InstrumentedClass instrumentClass(java.lang.String className, java.util.Set<java.lang.String> methodNames) throws java.lang.Exception
Add method tracing rules to the specified class name.
If a null set of method names is supplied,NullPointerException
is thrown.- Parameters:
className
- the class name to instrument.methodNames
- the selection of methods to instrument.- Returns:
- a local proxy for the instrumentation.
- Throws:
java.lang.NullPointerException
- in case of methodNames parameter is nulljava.lang.Exception
- in case of failure.
-
injectOnCall
public void injectOnCall(java.lang.Class clazz, java.lang.String methodName, java.lang.String action) throws java.lang.Exception
Inject an action to take place upon the invocation of the specified class.method- Parameters:
clazz
- The Class in which the injection point resides.methodName
- The method which should be intercepted.action
- The action that should take place upon invocation of the method.- Throws:
java.lang.Exception
- in case of failure.
-
injectOnCall
public void injectOnCall(java.lang.String className, java.lang.String methodName, java.lang.String action) throws java.lang.Exception
Inject an action to take place upon the invocation of the specified class.method- Parameters:
className
- The name of the Class in which the injection point resides.methodName
- The method which should be intercepted.action
- The action that should take place upon invocation of the method.- Throws:
java.lang.Exception
- in case of failure.
-
injectOnExit
public void injectOnExit(java.lang.Class clazz, java.lang.String methodName, java.lang.String action) throws java.lang.Exception
Inject an action to take place upon exit of the specified class.method- Parameters:
clazz
- The Class in which the injection point resides.methodName
- The method which should be intercepted.action
- The action that should take place upon invocation of the method.- Throws:
java.lang.Exception
- in case of failure.
-
injectOnExit
public void injectOnExit(java.lang.String className, java.lang.String methodName, java.lang.String action) throws java.lang.Exception
Inject an action to take place upon exit of the specified class.method- Parameters:
className
- The name of the Class in which the injection point resides.methodName
- The method which should be intercepted.action
- The action that should take place upon invocation of the method.- Throws:
java.lang.Exception
- in case of failure.
-
injectOnMethod
public void injectOnMethod(java.lang.Class clazz, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String atInjection) throws java.lang.Exception
Inject an action to take place at a given point within the specified class.method- Parameters:
clazz
- The Class in which the injection point resides.methodName
- The method which should be intercepted.action
- The action that should take place upon invocation of the method.atInjection
- the injection point e.g. "ENTRY".condition
- the rule condition- Throws:
java.lang.Exception
- in case of failure.
-
injectOnMethod
public void injectOnMethod(java.lang.String className, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String atInjection) throws java.lang.Exception
Inject an action to take place at a given point within the specified class.method- Parameters:
className
- The name of the Class in which the injection point resides.methodName
- The method which should be intercepted.action
- The action that should take place upon invocation of the method.atInjection
- the injection point e.g. "ENTRY".condition
- the rule condition- Throws:
java.lang.Exception
- in case of failure.
-
injectOnMethodWhere
public void injectOnMethodWhere(java.lang.Class clazz, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String where) throws java.lang.Exception
Inject an action to take place at a given point within the specified class.method
Difference to
injectOnMethod(Class, String, String, String, String)
resides at injection definition. The prior one expects "AT" injection point. This one expects the whole location qualifier.- Parameters:
clazz
- The Class in which the injection point resides.methodName
- The method which should be intercepted.action
- The action that should take place upon invocation of the method.where
- the injection definition e.g. "AT ENTRY" or "AFTER SYNCHRONIZATION".condition
- the rule condition- Throws:
java.lang.Exception
- in case of failure.
-
injectOnMethodWhere
public void injectOnMethodWhere(java.lang.String className, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String where) throws java.lang.Exception
Inject an action to take place at a given point within the specified class.method
Difference to
injectOnMethod(String, String, String, String, String)
resides at injection definition. The prior one expects "AT" injection point. This one expects the whole location qualifier.- Parameters:
className
- The name of the Class in which the injection point resides.methodName
- The method which should be intercepted.action
- The action that should take place upon invocation of the method.where
- the injection definition e.g. "AT ENTRY" or "AFTER SYNCHRONIZATION".condition
- the rule condition- Throws:
java.lang.Exception
- in case of failure.
-
injectFault
public void injectFault(java.lang.Class clazz, java.lang.String methodName, java.lang.Class<? extends java.lang.Throwable> fault, java.lang.Object[] faultArgs) throws java.lang.Exception
Inject a fault (i.e. Exception) to be thrown upon the invocation of the specified Class.method()- Parameters:
clazz
- The Class in which the injection point resides.methodName
- The method which should be intercepted.fault
- The type of Exception to be throw. If a checked exception, must be declared thrown by the specified method.faultArgs
- Optional constructor arguments for the Exception.- Throws:
java.lang.Exception
- in case of failure.
-
crashAtMethodExit
public void crashAtMethodExit(java.lang.Class clazz, java.lang.String methodName) throws java.lang.Exception
Inject a Rule to kill the target JVM upon exit of the specified Class.method()- Parameters:
clazz
- The Class in which the injection point resides.methodName
- The method which should be intercepted.- Throws:
java.lang.Exception
- in case of failure.
-
crashAtMethodExit
public void crashAtMethodExit(java.lang.String className, java.lang.String methodName) throws java.lang.Exception
Inject a Rule to kill the target JVM upon exit of the specified Class.method()- Parameters:
className
- The name of the Class in which the injection point resides.methodName
- The method which should be intercepted.- Throws:
java.lang.Exception
- in case of failure.
-
crashAtMethodEntry
public void crashAtMethodEntry(java.lang.Class clazz, java.lang.String methodName) throws java.lang.Exception
Inject a Rule to kill the target JVM upon entry to the specified Class.method()- Parameters:
clazz
- The Class in which the injection point resides.methodName
- The method which should be intercepted.- Throws:
java.lang.Exception
- in case of failure.
-
crashAtMethodEntry
public void crashAtMethodEntry(java.lang.String className, java.lang.String methodName) throws java.lang.Exception
Inject a Rule to kill the target JVM upon entry to the specified Class.method()- Parameters:
className
- The name of the Class in which the injection point resides.methodName
- The method which should be intercepted.- Throws:
java.lang.Exception
- in case of failure.
-
crashAtMethod
public void crashAtMethod(java.lang.String className, java.lang.String methodName, java.lang.String atInjection) throws java.lang.Exception
Inject a Rule to kill the target JVM at a given point within the specified Class.method()- Parameters:
className
- The name of the Class in which the injection point resides.methodName
- The method which should be intercepted.atInjection
- the injection point e.g. "ENTRY".- Throws:
java.lang.Exception
- in case of failure.
-
installScript
public void installScript(java.lang.String scriptName, java.lang.String scriptString) throws java.lang.Exception
Pass the assembled script to the remote JVM, either via. the Submit or, if redirection is in effect, to a file which will then be read at restart of the remote JVM. Keep a local handle on the script, such that it can be removed on request.- Parameters:
scriptName
- The name of the script. Should be unique.scriptString
- The text of the script i.e. one or more Rules.- Throws:
java.lang.Exception
- in case of failure.
-
installRule
public java.lang.String installRule(RuleConstructor builder) throws java.lang.Exception
Installing rule based on definition available by buildingRuleConstructor
.- Parameters:
builder
- rule builder with a rule definition to be installed as script- Returns:
- name of script that rule was installed under
- Throws:
java.lang.Exception
- in case of failure
-
removeScript
public void removeScript(java.lang.String scriptName) throws java.lang.Exception
Removing particular script from the remote byteman agent.
If you submitted a rule directly to remote JVM then the scriptName is the name under the script was installed.
If you used
setRedirectedSubmissionsFile(File)
to define a file where the rule will be written then this method won't work and you will get anIllegalStateException
.- Parameters:
scriptName
- name of script that should be removed- Throws:
java.lang.Exception
- in case that script can't be removed
-
removeRule
public void removeRule(RuleConstructor builder) throws java.lang.Exception
Removing particular script installed as a rule byRuleConstructor
.- Parameters:
builder
- a rule defining a script to be removed- Throws:
java.lang.Exception
- in case of failure
-
removeLocalState
public void removeLocalState() throws java.lang.Exception
Flush the local cache of scripts and proxies to remote instrumented classes. Useful to reset local state when a remote JVM is crashed and hence reset.- Throws:
java.lang.Exception
- in case of failure.
-
removeAllInstrumentation
public void removeAllInstrumentation() throws java.lang.Exception
Flush any instrumentation for the given class in the remote system and clean up the local cache.- Throws:
java.lang.Exception
- in case of failure.
-
appendToFile
private void appendToFile(java.io.File file, java.lang.String rule) throws java.lang.Exception
Write the given text to the end of the file.- Parameters:
file
- a file name.rule
- the text to append to the file.- Throws:
java.lang.Exception
- in case of failure.
-
publish
private InstrumentedClass publish(java.lang.String className) throws java.lang.Exception
Create a local communication endpoint for the the given class.- Parameters:
className
- the class to create the wrapper for.- Returns:
- a local handle for accessing trace information received from the remote instrumentation.
- Throws:
java.lang.Exception
- in case of failure.
-
unpublish
private void unpublish(java.lang.String className) throws java.lang.Exception
Remove the local communication endpoint for the given class.- Parameters:
className
- the class to remove.- Throws:
java.lang.Exception
- in case of failure.
-
isInterface
private boolean isInterface(java.lang.String className)
Trying to load a class and if successful then check if class is interface. If it's then returns true. In all other cases returns false.
-
findInstalledScript
private ScriptText findInstalledScript(java.lang.String scriptName)
Looping through installed scripts and checking if scriptName is there. If so returns it otherwise returns null.
-
-