3b) remoteval moved as new trunk

.classpath

 <?xml version="1.0" encoding="UTF-8"?>
 <classpath>
 	<classpathentry kind="src" path="src"/>
+	<classpathentry kind="src" path="src-re-disp"/>
+	<classpathentry kind="src" path="src-re-server"/>
 	<classpathentry kind="src" path="src-agent-java"/>
 	<classpathentry kind="src" path="src-test"/>
 	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
-	<classpathentry kind="lib" path="lib/asm-debug-all-4.0.jar"/>
 	<classpathentry kind="lib" path="build/eclipse-dynamicbypass.jar"/>
+	<classpathentry kind="lib" path="lib/asm-debug-all-4.1.jar"/>
 	<classpathentry kind="output" path="bin"/>
 </classpath>

.project

 <?xml version="1.0" encoding="UTF-8"?>
 <projectDescription>
-	<name>DiSL</name>
+	<name>DiSL-RE</name>
 	<comment></comment>
 	<projects>
 	</projects>

README

-The DiSL language is hosted in Java using annotations, therefore, no special compiler is required.
-A convenient way to specify an instrumentation and to pass it to the DiSL framework is to pack the instrumentation classes with a manifest file into one jar.
-The DiSL framework will load the jar, parse the instrumentation specification, and instrument all classes used by an application at load-time.
-
-The examples of simple instrumentation are in src-test directory.
-The test can be invoked using runTest.sh script in the root directory.
-For user defined instrumentation, it is recommended to mimic the start and build script as they are provided for test.
-We are working on better setup scripts to ease the setup effort for developer.
+DiSL
+====
+
+DiSL is a Java bytecode instrumentation framework intended for observation
+of programs executing in the Java Virtual Machine. It has been mainly used
+for development of dynamic program analysis instrumentations, but it can be
+used equally well to develop instrumentations for, e.g. runtime performance
+monitoring, or other tasks not bent on altering program execution.
+
+DiSL is inspired by AOP, but in contrast to mainstream AOP languages, it
+features an open join point model where any region of bytecodes can serve as
+a join point (i.e., code location to be instrumented). DiSL also reconciles
+high-level language concepts, such as the pointcut/advice programming model
+found in AOP, with high expressiveness, and efficiency of bytecode
+manipulation performed using low-level libraries such as ASM. As a result,
+instrumentations written using DiSL almost as compact as aspects written in
+AspectJ, but perform about as fast as those written using ASM.
+
+However, in contrast to AspectJ, DiSL does not restrict the code locations
+that can be instrumented, and the code generated by DiSL avoids expensive
+operations (such as object allocations that are not visible to the
+programmer). Furthermore, DiSL supports instrumentations with complete
+bytecode coverage out-of-the-box and avoids structural modifications of
+classes that would be visible through reflection and could break the
+instrumented code.
+
+link: http://forge.ow2.org/projects/disl/
+
+
+INSTALL
+=======
+
+DiSL currently fully supports "Linux" and "OS X" platforms with Java, ant, GCC
+and make installed and found on the executable path. DiSL has been used on the
+Windows/Cygwin platform as well, but it was not extensively tested there.
+
+While most of the DiSL is written in Java, it requires a JVM enhanced with a
+native agent written in C, which must be compiled first. For that, the simple
+build system needs to know where your JDK is installed to be able to find JNI
+header files for your platform. On many systems, the JAVA_HOME environment
+variable points to the root of the JDK installation and you should be fine.
+
+If this is not the case, please enter the src-agent-c directory, copy the
+Makefile.local.tmpl file to Makefile.local and modify it to set the JAVA_HOME
+variable to point to the root of the JDK installation you want to use.
+
+Finally, to compile DiSL, run the "ant" command in the root directory.
+
+You can create javadoc documentation by running "ant javadoc".
+
+
+EXAMPLES
+========
+
+For the basic instrumentation example, please look in the example directory.
+Also the src-test directory contains simple examples of DiSL features.
+
+
+DOCUMENTATION
+=============
+
+Please look at http://disl.projects.ow2.org/xwiki/bin/view/Main/Doc.
+
+
+USER ERRORS
+===========
+
+If you get a Java error during instrumentation or running your application,
+please look at USERERRORS document describing most common problems.

USERERRORS

+Exception in thread "main" java.lang.VerifyError: (class: ..., method: ... signature: ... Expecting to find object/array on stack
+ - CAUSE: The instrumentation attempts to access an uninitialized object.
+ - HOW TO FIX: Fix the instrumentation or disable the Java verifier (-noverify
+          commmand line option).
+
+Java process ends with SEGFAULT
+ - CAUSE: The instrumentation instruments one of the java.lang.* classes and
+          disturbs the java initialization
+ - HOW TO FIX: Fix the instrumentation or exclude the class causing the problem
+          in the exclusion list (-Ddisl.exclusionList=exclusion.lst command line
+          option of DiSL server).
+
+Build failure: java.lang.UnsupportedClassVersionError: ch/usi/dag/disl/utilinstr/tlvinserter/ExtendThread : Unsupported major.minor version 51.0
+ - CAUSE: A version 1.7.x JRE is used; this version is not yet supported
+ - HOW TO FIX: Use a version 1.6.x JRE instead.
+

build.properties

-asm.lib=asm-debug-all-4.0.jar
+asm.lib=asm-debug-all-4.1.jar
 asm.path=lib/${asm.lib}
 
 src.disl=src
 src.dynbypass=src-dynbypass
 src.dynbypass.act=src-dynbypass-act
 src.agent.java=src-agent-java
+src.agent.c=src-agent-c
+src.reserver=src-re-server
+src.redispatch=src-re-disp
+src.reagent=src-re-agent
 src.test=src-test
 
 bin=bin
@@ -14,4 +18,4 @@ build.afterbootstrap=build-abs
 
 extendedthread.path=${build}/extendedthread.jar
 
-instr.jar.name=dislinstr.jar
+instr.jar.name=disl-instr.jar

build.xml

@@ -47,22 +47,43 @@
 		</javac>
 	</target>
 
-	<target name="compile-test" depends="compile-disl">
+	<target name="compile-agent-c">
+		<exec executable="make" dir="${src.agent.c}" />
+	</target>
+
+	<target name="compile-reserver">
+		<javac srcdir="${src.reserver}" destdir="${bin}" debug="true" includeAntRuntime="false">
+			<classpath refid="buildpath" />
+		</javac>
+	</target>
+
+	<target name="compile-redispatch">
+		<javac srcdir="${src.redispatch}" destdir="${bin}" debug="true" includeAntRuntime="false">
+			<classpath refid="buildpath" />
+		</javac>
+	</target>
+
+	<target name="compile-reagent">
+		<exec executable="make" dir="${src.reagent}" />
+	</target>
+
+	<target name="compile-test" depends="compile-disl,compile-reserver,compile-redispatch">
 		<javac srcdir="${src.test}" destdir="bin" debug="true" includeAntRuntime="false">
 			<classpath refid="buildpath" />
 		</javac>
 	</target>
 
-	<target name="compile" depends="compile-disl,compile-agent-java,compile-test" />
+	<target name="compile" depends="compile-disl,compile-agent-java,compile-agent-c,compile-test,compile-reserver,compile-redispatch" />
 
 	<target name="package-dislserver" depends="compile-disl">
-		<jar basedir="${bin}" destfile="${build}/dislserver-${disl.version}.jar"
+		<jar basedir="${bin}" destfile="${build}/disl-server.jar"
 			includes="ch/usi/dag/disl/**,ch/usi/dag/dislserver/**"
 			excludes="ch/usi/dag/disl/test/**,ch/usi/dag/disl/testtools/**">
-			
+
 			<manifest>
-				<attribute name="Class-Path" value="${asm.lib} ${instr.jar.name}" />
+				<attribute name="Class-Path" value="${asm.lib}" />
 				<attribute name="Main-Class" value="ch.usi.dag.dislserver.DiSLServer" />
+				<attribute name="DiSL-Version" value="${disl.version}" />
 			</manifest>
 		</jar>
 	</target>
@@ -79,14 +100,14 @@
 		<!-- rename after bootstrap class -->
 		<move file="${build.afterbootstrap}/ch/usi/dag/disl/dynamicbypass/DynamicBypassCheck.class"
 			tofile="${build.afterbootstrap}/DynamicBypassCheck-AfterBootstrap.class" />
-		
-		<jar basedir="${bin}" destfile="${build}/dislagent-${disl.version}.jar"
+
+		<jar basedir="${bin}" destfile="${build}/disl-agent.jar"
 			includes="ch/usi/dag/dislagent/**,ch/usi/dag/disl/dynamicbypass/**">
-			
+
 			<manifest>
-				<attribute name="Class-Path" value="${instr.jar.name}" />
 				<attribute name="Premain-Class" value="ch.usi.dag.dislagent.DiSLAgent" />
 				<attribute name="Can-Redefine-Classes" value="true" />
+				<attribute name="DiSL-Version" value="${disl.version}" />
 			</manifest>
 
 			<!-- include after bootstrap class -->
@@ -97,7 +118,24 @@
 		<delete dir="${build.afterbootstrap}" />
 	</target>
 
-	<target name="package" depends="package-dislserver,package-dislagent-java" />
+	<target name="package-reserver" depends="compile-reserver">
+		<jar basedir="${bin}" destfile="${build}/dislre-server.jar"
+			includes="ch/usi/dag/dislreserver/**">
+			<manifest>
+				<attribute name="Class-Path" value="${asm.lib}" />
+				<attribute name="Main-Class" value="ch.usi.dag.dislreserver.DiSLREServer" />
+				<attribute name="DiSL-Version" value="${disl.version}" />
+			</manifest>
+		</jar>
+	</target>
+
+	<target name="package-redispatch" depends="compile-redispatch">
+		<jar basedir="${bin}" destfile="${build}/dislre-dispatch.jar"
+			includes="ch/usi/dag/dislre/**">
+		</jar>
+	</target>
+
+	<target name="package" depends="package-dislserver,package-dislagent-java,package-reserver,package-redispatch,compile-agent-c,compile-reagent" />
 
 	<target name="eclipse-agent" description="creates simple agent jar file for eclipse">
 		<mkdir dir="build" />
@@ -110,7 +148,7 @@
 
 	<target name="eclipse-dynamicbypass" depends="compile-dynamicbypass"
 		description="creates support library for DiSL development under eclipse">
-		
+
 		<jar basedir="${bin}" destfile="${build}/eclipse-dynamicbypass.jar"
 			includes="ch/usi/dag/disl/dynamicbypass/" />
 	</target>
@@ -128,8 +166,20 @@
 		<delete dir="${build}" />
 		<delete dir="${build.thread}" />
 		<delete dir="${build.afterbootstrap}" />
+		<exec executable="make" dir="${src.agent.c}">
+			<arg value="clean" />
+		</exec>
+		<exec executable="make" dir="${src.reagent}">
+			<arg value="clean" />
+		</exec>
+		
+
 	</target>
 
+	<target name="javadoc" depends="package,eclipse">
+		<javadoc access="public" author="true" overview="doc/overview.html" classpath="build/eclipse-dynamicbypass.jar:${asm.path}" destdir="doc" nodeprecated="false" nodeprecatedlist="false" noindex="false" nonavbar="false" notree="false" packagenames="ch.usi.dag.disl.guardcontext,ch.usi.dag.disl.staticcontext,ch.usi.dag.disl.dynamiccontext,ch.usi.dag.disl.classcontext,ch.usi.dag.disl.marker,ch.usi.dag.disl.transformer,ch.usi.dag.disl.processorcontext,ch.usi.dag.disl.annotation" source="1.7" sourcefiles="src/ch/usi/dag/disl/scope/Scope.java,src/ch/usi/dag/disl/scope/ScopeImpl.java,src/ch/usi/dag/disl/DiSL.java,src/ch/usi/dag/disl/snippet/Shadow.java" sourcepath="src-test:src-agent-java:src" splitindex="true" use="true" version="true"/>
+	</target>
+	
 	<!-- *** test instrumentaion package *** -->
 
 	<target name="check-test-property">

disl.version

-disl.version=unspec
\ No newline at end of file
+disl.version=unspec

doc/overview.html

+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html lang="en">
+	<head>
+		<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+		<title>Overview</title>
+	</head>
+	<body>
+		<div>This documentation serves only as a developer documentation of DiSL API. For the installation notes, please look at the README file in the DiSL distribution. For learning of DiSL, please look at the basic examples and the tutorial papers.</div>
+	</body>
+</html>

example/README

+DiSL SETUP EXAMPLE
+==================
+
+This simple example illustrates a basic instrumentation setup. It shows, how
+the instrumentation should be packaged and contains a scripts that should ease
+running DiSL together with your program.
+
+The example contains simple user application that prints hello string on
+command line and instrumentation printing strings before and after application
+main.
+
+HOW TO RUN THE EXAMPLE
+======================
+
+First be sure that you compiled DiSL (see README in the root directory). Then
+follow the steps:
+
+1) compile application calling "ant" in the app directory
+2) compile instrumentation calling "ant" in the instrumentation directory
+3) run "./runApp.sh instr/build/disl-instr.jar -jar app/build/example-app.jar"
+
+The last command starts the application together with DiSL. The output of the
+application and the applied instrumentation should be visible on command line.
+
+NOTE: If you want to use "runApp.sh" to run your application, don't forget to set
+      "DISL_LIB_P" variable correctly. Also, you can modify DiSL setting in
+      "runServer.sh".
+
+NOTE: If you want to include use some library in your instrumentation you shlould
+      insert it directly to the instrumentation jar using jarjar.
+      http://code.google.com/p/jarjar/
+
+DIRECTORIES (FILES)
+===================
+
+app          - contains sources of simple application
+instr        - contains sources of simple instrumentation
+runApp.sh    - bash script starting the application together with
+               DiSL (+ instrumentation)
+runServer.sh - starts instrumentation server
+runClient.sh - starts application vm with necessary agents
+

example/app/build.xml

+<project name="example-app" default="package" basedir=".">
+
+	<path id="buildpath">
+		<pathelement location="${bin}" />
+	</path>
+
+	<target name="compile">
+		<mkdir dir="bin" />
+		<javac srcdir="src" destdir="bin" debug="true" includeAntRuntime="false">
+			<classpath refid="buildpath" />
+		</javac>
+	</target>
+
+	<target name="package" depends="compile">
+		<mkdir dir="build" />
+		<jar basedir="bin" destfile="build/example-app.jar">
+			<manifest>
+				<attribute name="Main-Class" value="Main" />
+			</manifest>
+		</jar>
+	</target>
+
+	<target name="clean">
+		<delete dir="bin" />
+		<delete dir="build" />
+	</target>
+
+</project>

example/app/src/Main.java

+public class Main {
+	
+	public static void main(String[] args) {
+		System.out.println("Hi -- this is application main");
+	}
+}

example/instr/build.properties

+lib.path=../../build
+
+dislserver.path=${lib.path}/disl-server.jar
+
+asm.lib=asm-debug-all-4.0.jar
+asm.path=${lib.path}/${asm.lib}
+
+instr.jar.name=disl-instr.jar

example/instr/build.xml

+<project name="example-disl" default="package" basedir=".">
+
+	<property file="build.properties" />
+
+	<path id="buildpath">
+		<pathelement location="${asm.path}" />
+		<pathelement location="${dislserver.path}" />
+		<pathelement location="${bin}" />
+	</path>
+
+	<target name="compile">
+		<mkdir dir="bin" />
+		<javac srcdir="src" destdir="bin" debug="true" includeAntRuntime="false">
+			<classpath refid="buildpath" />
+		</javac>
+	</target>
+
+	<target name="package" depends="compile" description="create instrumentation package">
+		<mkdir dir="build"/>
+		<jar jarfile="build/${instr.jar.name}"
+		     basedir="bin"
+		     excludes="MANIFEST.MF"
+		     manifest="src/MANIFEST.MF">
+		</jar>
+	</target>
+	
+	<target name="clean">
+		<delete dir="bin" />
+		<delete dir="build" />
+	</target>
+
+</project>

example/instr/src/DiSLClass.java

+import ch.usi.dag.disl.annotation.After;
+import ch.usi.dag.disl.annotation.AfterReturning;
+import ch.usi.dag.disl.annotation.Before;
+import ch.usi.dag.disl.marker.BodyMarker;
+
+public class DiSLClass {
+	
+	@Before(marker = BodyMarker.class, scope = "Main.main")
+	public static void beforemain() {
+		
+		System.out.println("Before main()");
+	}
+	
+	@After(marker = BodyMarker.class, scope = "Main.main")
+	public static void aftermain() {
+		System.out.println("After main()");
+	}
+}

example/instr/src/MANIFEST.MF

+Manifest-Version: 1.0
+DiSL-Classes: DiSLClass
\ No newline at end of file

example/runApp.sh

+# /bin/sh
+
+# default DiSL lib path
+if [ -z "${DISL_LIB_P}" ]; then
+    DISL_LIB_P=../build
+fi
+
+# test number of arguments
+EXPECTED_ARGS=2
+if [ $# -lt $EXPECTED_ARGS ]
+then
+	echo "Usage: `basename $0` instr-lib java-params"
+	exit
+fi
+
+# set server file
+SERVER_FILE=.server.pid
+export SERVER_FILE
+
+# kill running server
+if [ -e ${SERVER_FILE} ]
+then
+	kill -KILL `cat ${SERVER_FILE}`
+	rm ${SERVER_FILE}
+fi
+
+export DISL_LIB_P
+
+# start server (with instrumentation library) and take pid
+./runServer.sh $1
+
+# wait for server startup
+sleep 3
+
+# run client
+./runClient.sh $*
+
+# wait for server shutdown
+sleep 1
+
+# kill server
+kill -KILL `cat ${SERVER_FILE}` 2> /dev/null
+rm ${SERVER_FILE}

example/runClient.sh

+#!/bin/bash
+
+# set default lib path
+if [ -z "${DISL_LIB_P}" ]; then
+	DISL_LIB_P=./build
+fi
+
+# test number of arguments
+EXPECTED_ARGS=2
+if [ $# -lt $EXPECTED_ARGS ]
+then
+	echo "Usage: `basename $0` instr-lib java-params"
+	exit
+fi
+
+# set proper lib depending on OS
+OS=`uname`
+if [ "${OS}" = "Darwin" ]; then
+	C_AGENT="${DISL_LIB_P}/libdislagent.jnilib"
+else
+	C_AGENT="${DISL_LIB_P}/libdislagent.so"
+fi
+
+# get instrumentation library and shift parameters
+INSTR_LIB=$1
+shift
+
+# start client
+java -agentpath:${C_AGENT} \
+     -javaagent:${DISL_LIB_P}/disl-agent.jar \
+     -Xbootclasspath/a:${DISL_LIB_P}/disl-agent.jar:${INSTR_LIB} \
+      $*

example/runServer.sh

+#!/bin/sh
+
+# set default lib path
+if [ -z "${DISL_LIB_P}" ]; then
+	DISL_LIB_P=./build
+fi
+
+# available options
+#    -Ddebug=true \
+#    -Ddisl.classes="list of disl classes (: - separator)"
+#    -Ddisl.noexcepthandler=true \
+#    -Ddisl.exclusionList="path" \
+#    -Ddislserver.instrumented="path" \
+#    -Ddislserver.uninstrumented="path" \
+#    -Ddislserver.port="portNum" \
+#    -Ddislserver.timestat=true \
+#    -Ddislserver.continuous=true \
+
+# get instrumentation library and shift parameters
+INSTR_LIB=$1
+shift
+
+# start server
+java $* \
+     -cp ${INSTR_LIB}:${DISL_LIB_P}/disl-server.jar \
+     ch.usi.dag.dislserver.DiSLServer \
+     &
+
+# print pid to the server file
+if [ -n "${SERVER_FILE}" ]; then
+    echo $! > ${SERVER_FILE}
+fi

runClient.sh

 #!/bin/bash
 
-OS=`uname`
+# set default lib path
+if [ -z "${DISL_LIB_P}" ]; then
+	DISL_LIB_P=./build
+fi
+
+# test number of arguments
+if [ $# -lt 2 ]; then
+	echo "Usage: `basename $0` instr-lib java-params"
+	exit 1
+fi
 
+# determine libs depending on the OS
+OS=`uname`
 if [ "${OS}" = "Darwin" ]; then
-  C_AGENT="src-agent-c/libdislagent.jnilib"
+	C_AGENT="${DISL_LIB_P}/libdislagent.jnilib"
+	RE_AGENT="${DISL_LIB_P}/libdislreagent.jnilib"
 else
-  C_AGENT="src-agent-c/libdislagent.so"
+	C_AGENT="${DISL_LIB_P}/libdislagent.so"
+	RE_AGENT="${DISL_LIB_P}/libdislreagent.so"
 fi
 
-java -agentpath:${C_AGENT} \
-     -javaagent:build/dislagent-unspec.jar \
-     -Xbootclasspath/a:build/dislagent-unspec.jar:build/dislinstr.jar \
-     -cp bin/ \
-      $*
+# get instrumentation library and shift parameters
+INSTR_LIB=$1
+shift
+
+# start the client
+${JAVA_HOME:+$JAVA_HOME/jre/bin/}java \
+	-agentpath:${C_AGENT} -agentpath:${RE_AGENT} \
+	-javaagent:${DISL_LIB_P}/disl-agent.jar \
+	-Xbootclasspath/a:${DISL_LIB_P}/disl-agent.jar:${INSTR_LIB}:${DISL_LIB_P}/dislre-dispatch.jar \
+	"$@"

runREServer.sh

+#!/bin/sh
+
+# set default lib path
+if [ -z "${DISL_LIB_P}" ]; then
+	DISL_LIB_P=./build
+fi
+
+# test number of arguments
+if [ $# -lt 1 ]; then
+	echo "Usage: `basename $0` instr-lib [java-params]"
+	exit 1
+fi
+