org.jboss.byteman.agent.submit
Class Submit

java.lang.Object
  extended by org.jboss.byteman.agent.submit.Submit

public class Submit
extends java.lang.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.


Nested Class Summary
private  class Submit.Comm
           
 
Field Summary
private  java.lang.String address
           
static java.lang.String DEFAULT_ADDRESS
           
static int DEFAULT_PORT
           
private  java.io.PrintStream out
           
private  int port
           
 
Constructor Summary
Submit()
          Create a client that will connect to a Byteman agent on the default host and port and writing output to System.out.
Submit(java.lang.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(java.lang.String address, int port, java.io.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
 java.lang.String addJarsToBootClassloader(java.util.List<java.lang.String> jarPaths)
          This adds the given list of files to the Byteman agent's boot classloader.
 java.lang.String addJarsToSystemClassloader(java.util.List<java.lang.String> jarPaths)
          This adds the given list of files to the Byteman agent's system classloader.
 java.lang.String addRules(java.util.Map<java.lang.String,java.lang.String> rules)
          Deprecated. 
 java.lang.String addRulesFromFiles(java.util.List<java.lang.String> filePaths)
          Deploys rules into Byteman, where the rule definitions are found in the local files found at the given paths.
 java.lang.String addScripts(java.util.List<ScriptText> scripts)
          Deploys rule scripts into Byteman
private  boolean confirmRuleFileValidity(java.lang.String path)
           
 java.lang.String deleteAllRules()
          Tells the Byteman agent to delete all rules.
 java.lang.String deleteRules(java.util.Map<java.lang.String,java.lang.String> rules)
          Deprecated. 
 java.lang.String deleteRulesFromFiles(java.util.List<java.lang.String> filePaths)
          Deletes rules from Byteman, where the rule definitions are found in the local files found at the given paths.
 java.lang.String deleteScripts(java.util.List<ScriptText> scripts)
          Deletes rules from Byteman.
 java.lang.String determineRuleName(java.lang.String ruleDefinition)
          Given the content of an individual rule definition, this will return the name of that rule.
 java.lang.String getAddress()
           
 java.lang.String getAgentVersion()
          Returns the version of the remote Byteman agent.
 java.util.Map<java.lang.String,java.lang.String> getAllRules()
          Deprecated. 
 java.util.List<ScriptText> getAllScripts()
          Gets all deployed rules from the agent just as listAllRules(), but will return the rules organized by script (i.e.
 java.lang.String getClientVersion()
          Returns the version of this Byteman submit client.
 java.util.List<java.lang.String> getLoadedBootClassloaderJars()
          Returns a list of jars that were added to the Byteman agent's boot classloader.
 java.util.List<java.lang.String> getLoadedSystemClassloaderJars()
          Returns a list of jars that were added to the Byteman agent's system classloader.
 int getPort()
           
private  java.util.List<ScriptText> getRulesFromRuleFiles(java.util.List<java.lang.String> filePaths)
           
 java.lang.String listAllRules()
          Tells the Byteman agent to list all deployed rules.
 java.util.Properties listSystemProperties()
          Returns the system properties set in the Byteman agent VM.
static void main(java.lang.String[] args)
          A main routine which submits requests to the Byteman agent utilizing the Java API.
 java.lang.String setSystemProperties(java.util.Properties propsToSet)
          Sets system properties in the Byteman agent VM.
 java.util.List<java.lang.String> splitAllRulesFromScript(java.lang.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.
 java.lang.String submitRequest(java.lang.String request)
          Submits the generic request string to the Byteman agent for processing.
private static void usage(java.io.PrintStream out, int exitCode)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_ADDRESS

public static final java.lang.String DEFAULT_ADDRESS
See Also:
Constant Field Values

DEFAULT_PORT

public static final int DEFAULT_PORT
See Also:
Constant Field Values

port

private final int port

address

private final java.lang.String address

out

private java.io.PrintStream out
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(java.lang.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. If null, 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(java.lang.String address,
              int port,
              java.io.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. If null, the default host is used.
port - the port that the Byteman agent is listening to. If 0 or less, the default port is used.
Method Detail

getAddress

public java.lang.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 java.lang.String getAgentVersion()
                                 throws java.lang.Exception
Returns the version of the remote Byteman agent.

Returns:
the version of the remote Byteman agent
Throws:
java.lang.Exception - if the request failed

getClientVersion

public java.lang.String getClientVersion()
                                  throws java.lang.Exception
Returns the version of this Byteman submit client.

Returns:
the version of the submit client, or null if unknown
Throws:
java.lang.Exception - if the request failed

deleteAllRules

public java.lang.String deleteAllRules()
                                throws java.lang.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:
java.lang.Exception - if the request failed

listAllRules

public java.lang.String listAllRules()
                              throws java.lang.Exception
Tells the Byteman agent to list all deployed rules.

Returns:
all the rules deployed in the Byteman agent
Throws:
java.lang.Exception - if the request failed

getAllScripts

public java.util.List<ScriptText> getAllScripts()
                                         throws java.lang.Exception
Gets all deployed rules from the agent just as listAllRules(), 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:
java.lang.Exception - if the request failed

getAllRules

@Deprecated
public java.util.Map<java.lang.String,java.lang.String> getAllRules()
                                                             throws java.lang.Exception
Deprecated. 

old version which returns a map rather than a list of scripts

Returns:
Throws:
java.lang.Exception

splitAllRulesFromScript

public java.util.List<java.lang.String> splitAllRulesFromScript(java.lang.String scriptContent)
                                                         throws java.lang.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 of getAllScripts() 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:
java.lang.Exception

determineRuleName

public java.lang.String determineRuleName(java.lang.String ruleDefinition)
                                   throws java.lang.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:
java.lang.Exception

addJarsToBootClassloader

public java.lang.String addJarsToBootClassloader(java.util.List<java.lang.String> jarPaths)
                                          throws java.lang.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:
java.lang.Exception - if the request failed

addJarsToSystemClassloader

public java.lang.String addJarsToSystemClassloader(java.util.List<java.lang.String> jarPaths)
                                            throws java.lang.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:
java.lang.Exception - if the request failed

getLoadedBootClassloaderJars

public java.util.List<java.lang.String> getLoadedBootClassloaderJars()
                                                              throws java.lang.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:
java.lang.Exception - if the request failed

getLoadedSystemClassloaderJars

public java.util.List<java.lang.String> getLoadedSystemClassloaderJars()
                                                                throws java.lang.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:
java.lang.Exception - if the request failed

addRulesFromFiles

public java.lang.String addRulesFromFiles(java.util.List<java.lang.String> filePaths)
                                   throws java.lang.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:
java.lang.Exception - if the request failed

addScripts

public java.lang.String addScripts(java.util.List<ScriptText> scripts)
                            throws java.lang.Exception
Deploys rule scripts into Byteman

Parameters:
scripts - scripts to be deployed to Byteman
Returns:
the results of the deployment
Throws:
java.lang.Exception - if the request failed

addRules

@Deprecated
public java.lang.String addRules(java.util.Map<java.lang.String,java.lang.String> rules)
                          throws java.lang.Exception
Deprecated. 

old version which uses a Map

Parameters:
rules -
Returns:
Throws:
java.lang.Exception

deleteRulesFromFiles

public java.lang.String deleteRulesFromFiles(java.util.List<java.lang.String> filePaths)
                                      throws java.lang.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:
java.lang.Exception - if the request failed

deleteScripts

public java.lang.String deleteScripts(java.util.List<ScriptText> scripts)
                               throws java.lang.Exception
Deletes rules from Byteman.

Parameters:
scripts - rule scripts to be deleted from Byteman
Returns:
the results of the deletion
Throws:
java.lang.Exception - if the request failed

deleteRules

@Deprecated
public java.lang.String deleteRules(java.util.Map<java.lang.String,java.lang.String> rules)
                             throws java.lang.Exception
Deprecated. 

old version which uses a Map

Parameters:
rules -
Returns:
Throws:
java.lang.Exception

setSystemProperties

public java.lang.String setSystemProperties(java.util.Properties propsToSet)
                                     throws java.lang.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:
java.lang.Exception - if the request failed

listSystemProperties

public java.util.Properties listSystemProperties()
                                          throws java.lang.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:
java.lang.Exception - if the request failed

submitRequest

public java.lang.String submitRequest(java.lang.String request)
                               throws java.lang.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:
java.lang.Exception - if the request failed

getRulesFromRuleFiles

private java.util.List<ScriptText> getRulesFromRuleFiles(java.util.List<java.lang.String> filePaths)
                                                  throws java.lang.Exception
Throws:
java.lang.Exception

confirmRuleFileValidity

private boolean confirmRuleFileValidity(java.lang.String path)

main

public static void main(java.lang.String[] args)
A main routine which submits requests to the Byteman agent utilizing the Java API.

Parameters:
args - see #usage(int) for a description of the allowed arguments

usage

private static void usage(java.io.PrintStream out,
                          int exitCode)