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

  • Carzaniga, Gorla, Mattavelli, Perino, Pezzè, "Automatic Recovery from Runtime Failures", ICSE 2013. PDF
  • Carzaniga, Gorla, Mattavelli, Perino, "A Self-Healing Technique for Java Applications", ICSE 2012 (poster paper). PDF
For more information and for the evaluation artifacts please contact: Andrea Mattavelli

Index

  1. Downloads
  2. Getting started
  3. Tutorial
    1. Example 1: Integrating ARMOR into an Application
    2. Example 2: ARMOR with a Buggy Application
  4. Limitations
  5. License

Downloads

All you need to integrate ARMOR with your application:

Getting started

Downloading and compiling ARMOR

  1. Request 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 into target/deploy/

Makefile guide

The easiest way to integrate your application with ARMOR is to modify the Makefile provided in ARMOR source distribution.
ARMOR-specific
  • ARMORROOT: Directory containing ARMOR (absolute path)
  • ARMOR_PRECOMPILED: Destination directory for the precompiled bytecode (relative path)
  • ARMOR_DB_ODB: Database file (relative path)
  • ORIG_CLASSESDIR: .class files resulting from the original compilation (relative path)
  • ARMOR_CLASSESDIR: .class files resulting from the instrumented compilation (relative path)
  • ARMOR_DESTINATIONDIR: Destination directory for the instrumented sources (relative path)
  • ARMOR_SWAPBIN: Temporary directory used by ARMOR (relative path)
  • ARMOR_CHECKPOINT_TYPE: Checkpoint type: conservative, conservative-optimized, runtime, none
  • LOGGINGLEVEL: Level of logging information: debug, info, warn, error, fatal
  • ARMOR_RULES: Filename of the file containing the transformation rules (relative path)
Application-specific
  • APPSRC: Directory of the original sources (absolute path)
  • APPCLASSPATH: Classpath for the application (absolute path)
  • LIBSIGNATURE: Signature (or part of) of the redundant library
JAVA-specific
  • JAVAROOT: Root directory for Java (absolute path).
  • JAVARUNTIMELIBS: Java Runtime libraries separated by a blank space (absolute path). Usually only rt.jar (Linux) or classes.jar (Mac Os X) is needed.
  • JAVABINDIR, JAVA, JAVAC: Default values usually valid
Checkpoint-specific
  • IJCP_EXCLUSIONS: lists the prefixes of (full) class names that will be excluded from the instrumentation of the incremental checkpoint (ijcp). Prefixes are separated by a colon (':'). Default values usually valid

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.

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 1 - FB2PDF with a working version of Joda-Time

Downloading FB2PDF and running it
  1. Download the modified FB2PDF application tar.gz
  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/ directory) into the main experiment 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

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

Downloading FB2PDF and running it
  1. Download the modified buggy FB2PDF application tar.gz
  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/ directory) into the main experiment 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

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

License

ARMOR is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with ARMOR. If not, see http://www.gnu.org/licenses