Package org.jboss.byteman.agent.submit
Class Submit
- java.lang.Object
-
- org.jboss.byteman.agent.submit.Submit
-
public class Submit extends Object
A Java API that can be used to submit requests to a remote Byteman agent. This also includes a main routine for use as a command-line utility. This object provides a means by which you communicate with the Byteman agent at runtime allowing loading, reloading, unloading of rules and listing of the current rule set and any successful or failed attempts to inject, parse and typecheck the rules. Note that this class is completely standalone and has no dependencies on any other Byteman class. It can be shipped alone in a client jar to be used as a very small app.
-
-
Field Summary
Fields Modifier and Type Field Description static String
DEFAULT_ADDRESS
static int
DEFAULT_PORT
-
Constructor Summary
Constructors Constructor Description Submit()
Create a client that will connect to a Byteman agent on the default host and port and writing output to System.out.Submit(String address, int port)
Create a client that will connect to a Byteman agent on the given host and port and writing output to System.out.Submit(String address, int port, PrintStream out)
Create a client that will connect to a Byteman agent on the given host and port and writing output to System.out.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description String
addJarsToBootClassloader(List<String> jarPaths)
This adds the given list of files to the Byteman agent's boot classloader.String
addJarsToSystemClassloader(List<String> jarPaths)
This adds the given list of files to the Byteman agent's system classloader.String
addRules(Map<String,String> rules)
Deprecated.String
addRulesFromFiles(List<String> filePaths)
Deploys rules into Byteman, where the rule definitions are found in the local files found at the given paths.String
addRulesFromResources(List<InputStream> resourceStreams)
Deploys rules into Byteman, where the rule definitions are found in the given streams.String
addScripts(List<ScriptText> scripts)
Deploys rule scripts into BytemanString
deleteAllRules()
Tells the Byteman agent to delete all rules.String
deleteRules(Map<String,String> rules)
Deprecated.String
deleteRulesFromFiles(List<String> filePaths)
Deletes rules from Byteman, where the rule definitions are found in the local files found at the given paths.String
deleteRulesFromResources(List<InputStream> resourceStreams)
Deletes rules from Byteman, where the rule definitions are found in the given streams.String
deleteScripts(List<ScriptText> scripts)
Deletes rules from Byteman.String
determineRuleName(String ruleDefinition)
Given the content of an individual rule definition, this will return the name of that rule.String
getAddress()
String
getAgentVersion()
Returns the version of the remote Byteman agent.Map<String,String>
getAllRules()
Deprecated.List<ScriptText>
getAllScripts()
Gets all deployed rules from the agent just aslistAllRules()
, but will return the rules organized by script (i.e.String
getClientVersion()
Returns the version of this Byteman submit client.List<String>
getLoadedBootClassloaderJars()
Returns a list of jars that were added to the Byteman agent's boot classloader.List<String>
getLoadedSystemClassloaderJars()
Returns a list of jars that were added to the Byteman agent's system classloader.int
getPort()
String
listAllRules()
Tells the Byteman agent to list all deployed rules.Properties
listSystemProperties()
Returns the system properties set in the Byteman agent VM.static void
main(String[] args)
A main routine which submits requests to the Byteman agent utilizing the Java API.String
setSystemProperties(Properties propsToSet)
Sets system properties in the Byteman agent VM.List<String>
splitAllRulesFromScript(String scriptContent)
Given the content of a script (which will be one or more rule definitions), this will return each rule definition as an individual string within the returned list.String
submitRequest(String request)
Submits the generic request string to the Byteman agent for processing.
-
-
-
Field Detail
-
DEFAULT_ADDRESS
public static final String DEFAULT_ADDRESS
- See Also:
- Constant Field Values
-
DEFAULT_PORT
public static final int DEFAULT_PORT
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Submit
public Submit()
Create a client that will connect to a Byteman agent on the default host and port and writing output to System.out.
-
Submit
public Submit(String address, int port)
Create a client that will connect to a Byteman agent on the given host and port and writing output to System.out.- Parameters:
address
- the hostname or IP address of the machine where Byteman agent is located. Ifnull
, the default host is used.port
- the port that the Byteman agent is listening to. If 0 or less, the default port is used.
-
Submit
public Submit(String address, int port, PrintStream out)
Create a client that will connect to a Byteman agent on the given host and port and writing output to System.out.- Parameters:
address
- the hostname or IP address of the machine where Byteman agent is located. Ifnull
, the default host is used.port
- the port that the Byteman agent is listening to. If 0 or less, the default port is used.out
- the print stream used for writing output
-
-
Method Detail
-
getAddress
public String getAddress()
- Returns:
- identifies the host where this client expects a Byteman agent to be running.
-
getPort
public int getPort()
- Returns:
- the port that this client expects a Byteman agent to be listening
to on the given
host
.
-
getAgentVersion
public String getAgentVersion() throws Exception
Returns the version of the remote Byteman agent.- Returns:
- the version of the remote Byteman agent
- Throws:
Exception
- if the request failed
-
getClientVersion
public String getClientVersion() throws Exception
Returns the version of this Byteman submit client.- Returns:
- the version of the submit client, or
null
if unknown - Throws:
Exception
- if the request failed
-
deleteAllRules
public String deleteAllRules() throws Exception
Tells the Byteman agent to delete all rules. This will effectively revert the Byteman's VM to its original state; that is, no Byteman injected byte-code will be invoked.- Returns:
- the results of the delete-all request to the Byteman agent
- Throws:
Exception
- if the request failed
-
listAllRules
public String listAllRules() throws Exception
Tells the Byteman agent to list all deployed rules.- Returns:
- all the rules deployed in the Byteman agent
- Throws:
Exception
- if the request failed
-
getAllScripts
public List<ScriptText> getAllScripts() throws Exception
Gets all deployed rules from the agent just aslistAllRules()
, but will return the rules organized by script (i.e. rule file). Each "script", or rule file, has a set of rules associated with it.- Returns:
- all the scripts deployed in the Byteman agent the keys are the script names (typically this is the filenames where the rule definitions were found); the values are the rule definitions in the scripts
- Throws:
Exception
- if the request failed
-
getAllRules
@Deprecated public Map<String,String> getAllRules() throws Exception
Deprecated.old version which returns a map rather than a list of scripts- Returns:
- as above but as a map
- Throws:
Exception
- if the request failed
-
splitAllRulesFromScript
public List<String> splitAllRulesFromScript(String scriptContent) throws Exception
Given the content of a script (which will be one or more rule definitions), this will return each rule definition as an individual string within the returned list. The returned list will be ordered - that is, the first rule in the list is the first rule encountered in the script. One usage of this method is to pass in map values from the results ofgetAllScripts()
in case you need the scripts' individual rules.- Parameters:
scriptContent
- the actual content of a script (i.e. the rule definitions)- Returns:
- all the rule definitions found in the given script
- Throws:
Exception
- if an string processing error occurs
-
determineRuleName
public String determineRuleName(String ruleDefinition) throws Exception
Given the content of an individual rule definition, this will return the name of that rule.- Parameters:
ruleDefinition
- the actual content of an individual rule- Returns:
- the name of the given rule, or
null
if it could not be determined - Throws:
Exception
- if the name cannot be determined
-
addJarsToBootClassloader
public String addJarsToBootClassloader(List<String> jarPaths) throws Exception
This adds the given list of files to the Byteman agent's boot classloader. Note that if the Byteman agent is running on a remote machine, the paths must resolve on that remote host (i.e. the file must exist on the remote machine at the paths given to this method).- Parameters:
jarPaths
- the paths to the library .jar files that will be loaded- Returns:
- the result of the load as reported by Byteman
- Throws:
Exception
- if the request failed
-
addJarsToSystemClassloader
public String addJarsToSystemClassloader(List<String> jarPaths) throws Exception
This adds the given list of files to the Byteman agent's system classloader. Note that if the Byteman agent is running on a remote machine, the paths must resolve on that remote host (i.e. the file must exist on the remote machine at the paths given to this method).- Parameters:
jarPaths
- the paths to the library .jar files that will be loaded- Returns:
- the result of the load as reported by Byteman
- Throws:
Exception
- if the request failed
-
getLoadedBootClassloaderJars
public List<String> getLoadedBootClassloaderJars() throws Exception
Returns a list of jars that were added to the Byteman agent's boot classloader.- Returns:
- list of jars that were added to the boot classloader
- Throws:
Exception
- if the request failed
-
getLoadedSystemClassloaderJars
public List<String> getLoadedSystemClassloaderJars() throws Exception
Returns a list of jars that were added to the Byteman agent's system classloader.- Returns:
- list of jars that were added to the system classloader
- Throws:
Exception
- if the request failed
-
addRulesFromFiles
public String addRulesFromFiles(List<String> filePaths) throws Exception
Deploys rules into Byteman, where the rule definitions are found in the local files found at the given paths. The rule definitions found in the files are actually passed down directly to Byteman, not the file paths themselves. Therefore, these files must exist on the machine where this client is running (i.e. the files are not loaded directly by the Byteman agent).- Parameters:
filePaths
- the local files containing the rule definitions to be deployed to Byteman- Returns:
- the results of the deployment
- Throws:
Exception
- if the request failed
-
addRulesFromResources
public String addRulesFromResources(List<InputStream> resourceStreams) throws Exception
Deploys rules into Byteman, where the rule definitions are found in the given streams. Rule definitions are read from the streams and the rule text uploaded directly to the Byteman agent. This method is useful for using rules files from the classpath.- Parameters:
resourceStreams
- input streams containing the rule definitions to be deployed to Byteman- Returns:
- the results of the deployment
- Throws:
Exception
- if the request failed
-
addScripts
public String addScripts(List<ScriptText> scripts) throws Exception
Deploys rule scripts into Byteman- Parameters:
scripts
- scripts to be deployed to Byteman- Returns:
- the results of the deployment
- Throws:
Exception
- if the request failed
-
addRules
@Deprecated public String addRules(Map<String,String> rules) throws Exception
Deprecated.old version which uses a Map- Parameters:
rules
- the rules to be added- Returns:
- the results of the deployment
- Throws:
Exception
- if the request failed
-
deleteRulesFromFiles
public String deleteRulesFromFiles(List<String> filePaths) throws Exception
Deletes rules from Byteman, where the rule definitions are found in the local files found at the given paths. After this method is done, the given rules will no longer be processed by Byteman. The rule definitions found in the files are actually passed down directly to Byteman, not the file paths themselves. Therefore, these files must exist on the machine where this client is running (i.e. the files are not read directly by the Byteman agent).- Parameters:
filePaths
- the local files containing the rule definitions to be deleted from Byteman- Returns:
- the results of the deletion
- Throws:
Exception
- if the request failed
-
deleteRulesFromResources
public String deleteRulesFromResources(List<InputStream> resourceStreams) throws Exception
Deletes rules from Byteman, where the rule definitions are found in the given streams. Rule definitions are read from the streams so that details of which rules to unload can be uploaded directly to the Byteman agent. This method is useful for using rules files from the classpath.- Parameters:
resourceStreams
- the URLS to files containing the rule definitions to be deleted from Byteman- Returns:
- the results of the deletion
- Throws:
Exception
- if the request failed
-
deleteScripts
public String deleteScripts(List<ScriptText> scripts) throws Exception
Deletes rules from Byteman.- Parameters:
scripts
- rule scripts to be deleted from Byteman- Returns:
- the results of the deletion
- Throws:
Exception
- if the request failed
-
deleteRules
@Deprecated public String deleteRules(Map<String,String> rules) throws Exception
Deprecated.old version which uses a Map- Parameters:
rules
- the rules to be deleted- Returns:
- the results of the deletion
- Throws:
Exception
- if the request failed
-
setSystemProperties
public String setSystemProperties(Properties propsToSet) throws Exception
Sets system properties in the Byteman agent VM. If Byteman was configured for strict mode, only Byteman related system properties will be allowed to be set.- Parameters:
propsToSet
- system properties to set in the Byteman agent VM- Returns:
- response from the Byteman agent
- Throws:
Exception
- if the request failed
-
listSystemProperties
public Properties listSystemProperties() throws Exception
Returns the system properties set in the Byteman agent VM. If Byteman was configured for strict mode, only Byteman related system properties will be returned.- Returns:
- system properties defined in the Byteman agent VM
- Throws:
Exception
- if the request failed
-
submitRequest
public String submitRequest(String request) throws Exception
Submits the generic request string to the Byteman agent for processing.- Parameters:
request
- the request to submit- Returns:
- the response that the Byteman agent replied with
- Throws:
Exception
- if the request failed
-
main
public static void main(String[] args)
A main routine which submits requests to the Byteman agent utilizing the Java API.- Parameters:
args
- seeusage(PrintStream, int)
for a description of the allowed arguments
-
-