Difference between revisions of "JavaMOPAgent"

From FSL
Jump to: navigation, search
(Building the agent)
Line 103: Line 103:
 
*# ./build-agent.sh
 
*# ./build-agent.sh
  
If step 2.5 is successful, you will find a jar file, "mop_agent.jar" will be created inside the build-agent directory.
+
If it is successful, you will find a jar file, "mop_agent.jar" will be created inside the build-agent directory.
  
 
===== Cleanup =====
 
===== Cleanup =====

Revision as of 01:49, 2 June 2014

Contents

Prerequisite

RV-Monitor

You can clone it from:

 git clone https://github.com/runtimeverification/rv-monitor

Build it.

JavaMOP 4.0

I believe JavaMOP 3.0 works as well, but I'll assume 4.0. You can clone it from:

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

Build it.

However, I have not tested the code in this repository. I've been using one in the Google Code repository:

 svn checkout http://javamop.googlecode.com/svn/trunk/ javamop-read-only

It would be great if someone checks whether the github version works.

Parametric Specifications

You can clone the repository from the Google Code page:

 hg clone https://code.google.com/p/annotated-java-api/

In the properties/ directory, you should be able to see JavaMOP specifications. Throughout this document, I'll call this properties/ directory as $JAVAMOPSPEC_DIR.

The modified AspectJ

The original AspectJ will fail to weave fop of DaCapo 9.12 with the 179 specifications. You will get the following error message, something like "code size too big". To avoid this error, I modified the AspectJ compiler. For more details, refer to the Appendix of Choonghwan Lee's thesis.

You can clone this modified AspectJ from the 'javamop' branch of my repository hosted on fslwork:

 git clone -b javamop ssh://[your-id]@fslwork.cs.illinois.edu/home/clee83/repository/aspectj

You should be able to build it using ant. During the compiltation, an error like "property 'local-properties' not at ..." may occur. You should create local.properties under build/, and you can simply copy from build/sample.local.properties. If the build procedure is successful, you will be able to see the following directory:

 aj-build/dist/tools/lib/

This directory contains all the important files:

  • aspectjtools.jar: the AspectJ compiler
  • aspectjweaver.jar: the load-time weaver (LTW)
  • aspectjrt.jar: runtime

All of these files can be useful, but, for the purpose of generating a JavaMOP-Agent, only the LTW and runtime are necessary. Throughout this document, I'll call this lib/ directory as $ASPECTJ_DIR.

BaseAspect.aj

Traditionally, JavaMOP defines the notwithin pointcut to exclude classes that should not be instrumented. Create BaseAspect.aj with the following contents:

package mop;
public aspect BaseAspect {
pointcut notwithin() :
 !within(sun..*) &&
 !within(java..*) &&
 !within(javax..*) &&
 !within(com.sun..*) &&
 !within(org.dacapo.harness..*) &&
 !within(org.apache.commons..*) &&
 !within(org.apache.geronimo..*) &&
 !within(net.sf.cglib..*) &&
 !within(mop..*) &&
 !within(javamoprt..*) &&
 !within(rvmonitorrt..*) &&
 !within(com.runtimeverification..*);
}

This will be referred to as $BASEASPECT_FILE. This aspect will be referred to by the aspect generated by JavaMOP.

Automated Procedure

C# Version

It turned out that I automated the procedure that will be explained in the "Manual Procedure" section.

It's part of a pretty complicated C# program, which is written for running the DaCapo 9.12 and others. This program is quite complicated because it does many things:

  • runs DaCapo 9.12 under both UNIX and Windows
  • relives some problems in JavaMOP 2.3
  • supports various settings
  • supports resuming; i.e., one can stop the execution and resume later
  • supports both performance measurement and violation collection (with call-site counting)

In short, it won't be very readable. Nevertheless, if you are adventurous and you want to see more formal procedure (i.e., methods and classes), you can get the source from my repository hosted on fslwork:

 git clone ssh://[your-id]@fslwork.cs.illinois.edu/home/clee83/repository/javamop

The corresponding class is CreateAspectJAgentPlugin.

Script

For UNIX-based systems, we have written a script to automate the process of building a java agent which enables to easily monitor some of our manually written Java API specifications.

Prerequisites

During installation, some some repositories will be cloned using Git and Mercurial.

Building the agent

Please follow the steps below:

  • Download the needed files Build-agent
  • On the command line, run the following commands:
    1. cd <directory-where-installation-were-downloaded>
    2. tar xvf build-agent.tgz
    3. cd build-agent
    4. chmod +x build-agent.sh
    5. ./build-agent.sh

If it is successful, you will find a jar file, "mop_agent.jar" will be created inside the build-agent directory.

Cleanup
  • To clean up the files generated while building the java agent, run the following command from the same directory:
    1. ./build-agent.sh clean

Manual Procedure

Run JavaMOP

  • Input: JavaMOP specifications in $JAVAMOPSPEC_DIR
  • Output: RV-Monitor specifications in $RVSPEC_DIR
  • Output: $ASPECT_FILE: an Aspect file in $RVSPEC_DIR

You may run JavaMOP any way that pleases you, but do not forget the -translate2RV option. I typically run as follows:

 javamop -d $RVSPEC_DIR -dacapo -silent -translate2RV -n all -merge <path-to-spec1> <path-to-spec2> ... <path-to-specn>

This will generate the output files in $RVSPEC_DIR.

Both the -dacapo and -silent options are what JavaMOP 3.0 has without any explanation. They have something to do with suppressing log messages, but I'm not sure if they are effective under JavaMOP 4.0. (Qingzhou, could you shed some light on this?)

Here, <path-to-spec1> ... <path-to-specn>, where n = 179 for a thorough test, should be provided. Under UNIX systems, I guess a wildcard may work, although I have not tried.

Note: if you are running under Windows, you cannot use a wildcard. When you provide a list of full paths, you should make sure that the entire command is no longer than a certain limit, imposed by cmd.exe. You may avoid this using Powershell. I used a C# program that directly spawn a process; this is similar to calling one of exec(2) family of POSIX.

Run RV-Monitor

  • Input: RV-Monitor specifications in $RVSPEC_DIR
  • Output: $MONITORJAVA_FILE: a Java file that implements the monitoring functionality in $MONITOR_DIR

I typically run RV-Monitor as follows:

 rvmonitor -d $MONITOR_DIR -dacapo -silent -n all -merge <path-to-spec1> ... <path-to-specn>

This will generate a single Java file in $MONITOR_DIR. This file implements the interface for firing events, and some data structures, such as monitors and monitor sets.

Here, specifications are, of course, RV-Monitor specifications, generated by JavaMOP.

Compile the generated Java file

  • Input: $MONITORJAVA_FILE
  • Output: $MONITORLIB_FILES: many .class files

You can use javac. When you compile this, you should provide the path to the RV-Monitor runtime (rvmonitorrt.jar).

Due to Java's strict rule, there will be many files, one for each class. I'll refer to all of them as $MONITORLIB_FILES.

Compile the generated Aspect file

  • Input: $ASPECT_FILE
  • Input: $BASEASPECT_FILE
  • Output: $AOPAJC_FILE: an XML file
  • Output: $COMPILEDASPECT_FILE

You can run the AspectJ compiler without a program, as follows:

 ajc -1.6 -outxml $BASEASPECT_FILE $ASPECT_FILE

Then, ajc will generate two output files.

It is recommended to edit $AOPAJC_FILE. Right after the <aspects> tag, add the following:

 <weaver options="-nowarn -Xlint:ignore"></weaver>

This will suppress less useful warning messages.

Create a Java Agent

  • Output: $JAVAMOPAGENT_FILE

The goal of this procedure is to create a single .jar file, which is qualified as a Java agent. You can simply view this procedure as merging all the necessary files into one .jar file.

Prepare a working directory

We will start from AspectJ's LTW, and then add necessary things below.

  • Unzip aspectjweaver.jar in $ASPECTJ_DIR into $AGENT_DIR
Copy specification-specific files
  • Place $AOPAJC_FILE$ in $AGENT_DIR/META-INF/
  • Place $COMPILEDASPECT_FILE in $AGENT_DIR/mop/
  • Place $MONITORLIB_FILES in $AGENT_DIR/mop/

The last two operations assume that the specification is defined in the "mop" package, which is the case at the time of writing this.

Copy RV-Monitor runtime
  • Unzip rvmonitorrt.jar
  • Copy recursively com/ to $AGENT_DIR/com/
Zip the directory

Now, you can create .jar file from $AGENT_DIR. I issue the following command:

 jar cmf $AGENT_DIR/META-INF/MANIFEST.MF $JAVAMOPAGENT_FILE -C $AGENT_DIR .

You should make sure that the manifest file is specified. If this is successful, you will get a JavaMOP-Agent, referred to as $JAVAMOPAGENT_FILE.

Enjoy it

Now, you can test a program using $JAVAMOPAGENT_FILE. For example,

 java -javaagent:$JAVAMOPAGENT_FILE Foo

Hope this works!

Personal tools
Namespaces

Variants
Actions
Navigation