ARMOR


Browser Version

What is ARMOR?

ARMOR is our tool that implements our automatic workaround technique. ARMOR works in the following general scenario: a Java application fails because of faults in one of the libraries it uses. Such faults may trigger a failure in the library code or in the application code. ARMOR, which is embedded within the application and is notified of the failure, reacts to the failure by first restoring the state of the application to a previously set checkpoint, and then by selecting and executing an equivalent sequence of operations that might avoid the failure and lead to the expected result.

Related publications

Index

  1. Downloads
  2. ARMOR: Getting started
  3. Tutorial
  4. Limitations
  5. Evaluation artifacts

Downloads

All you need to integrate ARMOR with your application.

ARMOR: Getting started

The easiest way to integrate your application with ARMOR is to modify the Makefile provided in ARMOR source distribution.

Downloading and compiling ARMOR

  1. Download ARMOR source code
  2. Launch “ant” to compile ARMOR. It should take few seconds
  3. You should find the compiled version of ARMOR with all its dependencies and a Makefile into “target/deploy/”

Libraries used by ARMOR

ARMOR Makefile guide

ARMOR-specific
Application-specific
JAVA-specific
Checkpoint-specific

Tutorial

This tutorial shows you how to integrate ARMOR with an application called FB2PDF. FB2PDF is an open-source application that converts .fb2 e-books to PDF files. FB2PDF natively uses Java standard features to deal with dates and time. We have manually modified FB2PDF to use the Joda-Time library instead.

This tutorial consists of two examples. Example 1 shows how to integrate and to run FB2PDF with ARMOR. Example 2 shows ARMOR effectiveness in avoiding failures at runtime with a real buggy version of the Joda-Time library.

Example 1 - FB2PDF with a working version of Joda-Time

Downloading FB2PDF and running it
  1. Download the modified FB2PDF application [tar.gz - md5 - sha1]
  2. Launch “ant” to compile the application. It should take few seconds
  3. Launch ”./run.sh” to run the application with an example
Working with ARMOR
  1. Copy ARMOR (armor/ and Makefile) into the main directory of FB2PDF
  2. Go into FB2PDF main directory
  3. Download the Joda-Time rewriting rules
  4. Set up ARMOR using the "Makefile". The properties that you have to set up are:
    1. ORIG_CLASSESDIR, path to the .class files of the application
    2. ARMOR_RULES, name of the file containing the transformation rules
    3. APPSRC, directory of the original sources
    4. APPCLASSPATH, classpath for the application
    5. LIBSIGNATURE, signature (or part of) of the redundant library
    6. JAVAROOT, absolute path of your Java home directory
    7. JAVARUNTIMELIBS, Java Runtime libraries separated by a blank space. Only the rt.jar file is needed for this example
    8. JAVAFLAG, additional flags to use for running Java code. We suggest you to add -Xmx2G
  5. Launch “make run-armor” to instrument the source code of FB2PDF. The process should take 2-5 minutes, depending on your computational resources
  6. Launch “ant -f build-armor.xml” to compile FB2PDF with ARMOR instrumentation. It should take few seconds
  7. Launch ”./run-armor.sh” to run FB2PDF with ARMOR agent
Note: if you want you can download a pre-compiled Makefile with most of the properties required. You still need to fill the properties concerning your Java environment (JAVAROOT, JAVARUNTIMELIBS).

Example 2 - FB2PDF with a buggy version of Joda-Time

Downloading FB2PDF and running it
  1. Download the modified buggy FB2PDF application [tar.gz - md5 - sha1]
  2. Launch “ant” to compile the application. It should take few seconds
  3. Launch ”./run.sh” to run the application with an example. The application should fail with an exception
Working with ARMOR
  1. Copy ARMOR (armor/ and Makefile) into the main directory of FB2PDF
  2. Go into FB2PDF main directory
  3. Download the Joda-Time rewriting rules
  4. Set up ARMOR using the ”Makefile”. The properties that you have to set up are:
    1. ORIG_CLASSESDIR, path to the .class files of the application
    2. ARMOR_RULES, name of the file containing the transformation rules
    3. APPSRC, directory of the original sources
    4. APPCLASSPATH, classpath for the application
    5. LIBSIGNATURE, signature (or part of) of the redundant library
    6. JAVAROOT, absolute path of your Java home directory
    7. JAVARUNTIMELIBS, Java Runtime libraries separated by a blank space. Only the rt.jar file is needed for this example
    8. JAVAFLAG, additional flags to use for running Java code. We suggest you to add -Xmx2G
  5. Launch “make run-armor” to instrument the source code of FB2PDF. The process should take 2-5 minutes, depending on your computational resources
  6. Launch “ant -f build-armor.xml” to compile FB2PDF with ARMOR instrumentation. It should take few seconds
  7. Launch ”./run-armor.sh” to run FB2PDF with ARMOR agent. The application should behave correctly as in Example 1
Note: if you want you can download a pre-compiled Makefile with most of the properties required. You still need to fill the properties concerning your Java environment (JAVAROOT, JAVARUNTIMELIBS).

Limitations

The current implementation of ARMOR has the following limitations:
  1. it supports the Java language up to Java 6
  2. it supports single library self-healing (only one library at time can be made self-healing)
  3. it works for single threaded Java applications
  4. to take advantage of ARMOR, you need a JVM that supports class redefinition, such as the Oracle HotSpot JVM