Skip to content

Latest commit

 

History

History
157 lines (113 loc) · 5.13 KB

JavaMOPAgentUsage.md

File metadata and controls

157 lines (113 loc) · 5.13 KB
Raw

JavaMOPAgent Documentation

Prerequisites

  1. Running JavaMOPAgent, requires the installation and use of JavaMOP and RV-Monitor.

  2. Currently, JavaMOPAgent does not support multiple .aj input files. A single .aj file can be generated from multiple multiple property files by running JavaMOP with -merge option (see example below).

  3. All the monitor libraries (.java files) generated by RV-Monitor should be contained in a single directory (see the example below).

Building and Using a JavaMOP Agent

Building a JavaMOP Agent

The following command can be used to build agents for runtime instrumentation of applications:

javamopagent <AJ-File> <Monitor-Lib-Dir> [-n <agent name>] [-excludeJars]

The required <AJ-File> option specifies the path to the single AspectJ file (generated by JavaMOP) from which the agent will be built. <Monitor-Lib-Dir> is the directory containing all monitor library files (generated by RV-Monitor). [-n <agent name>] optionally allows the user to specify the name of the generated agent. The optional [-excludeJars] option will prevent jars for the RV-Monitor runtime and AspectJ Weaver from being included in the generated agent -- the user will the have to manually include those jars in the CLASSPATH before running the agent.

Example of Building an Agent

The following procedure shows how to build an agent from two .mop files on a Unix-like system:

  1. git clone https://github.com/runtimeverification/javamop.git

  2. mvn package

  3. cd examples/agent/many/rvm/cfg. This directory contains two property files: SafeFile.mop and SafeFileWriter.mop.

  4. Generate the single .aj file and .rvm files from the properties ( After this step, these files will be generated: MultiSpec_1MonitorAspect.aj, SafeFile.rvm and SafeFileWriter.rvm):

    javamop -merge *.mop

  5. Create directories for storing the monitor libraries:

    mkdir -p classes/mop

  6. Generate the monitor libraries using RV-Monitor:

    rv-monitor -merge -d classes/mop/ *.rvm

    After this step, MultiSpec_1RuntimeMonitor.java will be generated in folder classes/mop.

  7. (Optional) Compile the monitor library file and remove Java file:

    javac classes/mop/MultiSpec_1RuntimeMonitor.java

    rm classes/mop/MultiSpec_1RuntimeMonitor.java

  8. Build a JavaMOP agent which does not contain AspectJ Weaver and RV-Monitor jars:

    javamopagent MultiSpec_1MonitorAspect.aj classes -n JavaMOPAgent -excludeJars

After step 8, JavaMOPAgent.jar will be created in the current directory and can be used for runtime monitoring, as explained below.

Using a Java Agent

An agent, "JavaMOPAgent.jar", built as described in the previous section, can be used in the following ways:

  1. For projects with a well-defined entry point, such as a Main class, first compile the source code and then run the following command:

    java -javaagent:JavaMOPAgent.jar Main

    In other words, you will need to run the same command as you would normally use for running your Java application, but with the addition of the -javaagent:JavaMOPAgent.jar, as shown above.

  2. For Maven-based projects with tests, you can modify pom.xml to use the agent when running tests by adding following lines:

  <build>
  	<plugins>
  		...
      	<plugin>
    		<groupId>org.apache.maven.plugins</groupId>
    		<artifactId>maven-surefire-plugin</artifactId>
    		<version>${surefire-version}</version>
    		<configuration>
      			<argLine>-javaagent:JavaMOPAgent.jar</argLine>
    		</configuration>
      	</plugin>
  	...
    	</plugins>
   </build>

Replace ${surefire-version} with the exact surefire plugin version used by the project (e.g., 2.16).

After that, you can run tests as usual with the mvn test command. The execution of the tests will now be monitored by the agent.

  1. For Ant-based projects with tests, you can modify build.xml to use the agent when running tests by adding one line under the junit task:
  <target name=...>
  	<junit ...>
  		...
      	<jvmarg value="-javaagent:JavaMOPAgent.jar"/>
  	...
    	</plugins>
   </target>

After that, you can run tests as usual with the ant ${test_target_name} command. The execution of the tests will now be monitored by the agent.

  1. A java agent can be easily integrated into IDEs like IntelliJ, Eclipse, etc.

    For IntelliJ: click the "Run" tab -> select the "Edit Configurations" tab -> select the application you are running -> select "configuration" tab -> enter "javaagent:JavaMOPAgent.jar" in the "VM options" textbox.

    For Eclipse: click "Run" tab -> select "Run configurations" tab -> select the application you are running -> select "Arguments" tab -> enter "javaagent:JavaMOPAgent.jar" into "VM options" textbox.

    By doing this, you will be able to run or debug programs with the agent within your IDE.