adaptive-caching-framework

diff --git a/framework/autonomicmanager/README.md b/framework/autonomicmanager/README.md
index 6592296..3809956 100644
--- a/framework/autonomicmanager/README.md
+++ b/framework/autonomicmanager/README.md
@@ -1,52 +1,58 @@
 APL Cache
 =========
-#todo presentation
 
-#todo describe the features
+APL is an automated solution to application-level caching. APL can be incorporated into web applications so that it can monitor and choose content to be cached according to changing usage patterns. It consists of two complementary asynchronous parts: (a) a reactive model applying, responsible for monitoring traces of the application execution and caching method calls (previously identified as caching opportunities) at runtime; and (b) a proactive model building, which analyzes on the background the behavior of the application, taking into account application-specific information, and finds cacheable opportunities. Figure above presents an overview of the dynamics of our approach, indicating the activities that comprise its running cycle. These asynchronous parts involve performing three different activities: (1) data tracking, (2) data mining and (3) cache management.
 
-#todo put the image of the architecture
+![Overview](http://inf.ufrgs.br/~jmamertz/resources/images/ProposedSolution.png)
 
-Requirements
+Features
 ------------
-If you are using Gradle/Maven, see example below:
-
-##### Gradle
-In your `build.gradle`:
-```groovy
-	allprojects {
-		repositories {
-			maven { url "https://jitpack.io" }
-		}
-	}
-	
-	dependencies {
-		compile 'com.github.jhonnymertz:java-wkhtmltopdf-wrapper:1.0.2-RELEASE'
-	}
-```
+- Declarative configuration
+- Enable and disable features by configuration or at runtime
+- Automatic identification of cacheable methods
+- Automated caching of cacheable methods
+
+APL Cache is implemented in Java, thus can be used with Java web applications. We adopted a set of technologies that provide an appropriate infrastructure for the framework. Used technologies are highlighted in the above figure, which presents the APL Cache architecture, with its modules and communication among them.
+
+![Architecture](http://inf.ufrgs.br/~jmamertz/resources/images/APLCacheArchitecture.png)
+
+Required Tools
+--------------
+- AOP-enabled compilation
+- Maven 3
+- Java 8
+
+###### Optional
+- To store application traces: MongoDB or Redis
+- To cache data: Redis or Memcached
+
+Build and Dependency
+--------------------
 
-##### Maven
-In your `pom.xml`:
+Go to the framework folder and build the `pom.xml` with Maven: `mvn clean install`
+
+If your project is maven-based, in your `pom.xml`:
 ```xml
-	<dependencies>
-		<dependency>
-				<groupId>com.github.jhonnymertz</groupId>
-				<artifactId>java-wkhtmltopdf-wrapper</artifactId>
-				<version>1.0.2-RELEASE</version>
-		</dependency>
-	</dependencies>
-
-	<repositories>
-		<repository>
-				<id>jitpack.io</id>
-				<url>https://jitpack.io</url>
-		</repository>
-	</repositories>
+<dependencies>
+    <dependency>
+        <groupId>br.ufrgs.inf.prosoft.adaptivecaching</groupId>
+        <artifactId>autonomicmanager</artifactId>
+        <version>0.4.0-SNAPSHOT</version>
+    </dependency>
+</dependencies>
 ```
 
+Otherwise, you can also get the `.jar` produced by maven can be just added to the classpath.
+
 Usage
-------------
+-----
+
+###### Application example
+
+In order to have a practice reference, consider the project `toyexample`. It should be found along with the source of the framework.
+
+Create a file adaptivecaching.properties under the resources folder of your application to specify the configuration desired.
 
-Create a file adaptivecaching.properties under resources folder
 ```
 #Cache config
 #Redis:
@@ -71,40 +77,54 @@ adaptivecaching.monitoring.db.address=localhost
 #adaptivecaching.monitoring.db.address=localhost
 ```
 
-Then, create a configuration class, on the root package of the system:
+Then, create a configuration class which consists of `@AdaptiveCaching` and `@ComponentScan` annotations, on the root package of the system:
+
 ```
-//working config: mongodb, accumulation
+//mongodb as log database
+//ehcache as cache
 @AdaptiveCaching(cacheProvider = CacheProviderType.EHCACHE, logRepository = RepositoryType.MONGODB,
     modelling = Modelling.ACCUMULATION, analyzerEnabled = false, enabled = true, disableMonitoringAfterAnalysis = true,
     clearMonitoringDataOnStart = true, traceAsync = false, tracerEnabled = true)
-
-//Jhonny: workaround below. a better solution involve filter by serialization methods in aspect to avoid it
-@ComponentScan(allowed = "org.springframework.samples.petclinic", denied = "org.springframework.samples.petclinic.model")
+```
+```
+@ComponentScan(allowed = "my.package", denied = "my.package.not")
 public class Configuration {
 }
 ```
 
-Available annotations
----------
-@AdaptiveCaching
-		cacheProvider = CacheProviderType.EHCACHE, logRepository = RepositoryType.MONGODB,
-    modelling = Modelling.ACCUMULATION, analyzerEnabled = false, enabled = true, disableMonitoringAfterAnalysis = true,
-    clearMonitoringDataOnStart = true, traceAsync = false, tracerEnabled = true
-
-@ComponentScan
-		allowed = "org.springframework.samples.petclinic", denied = "org.springframework.samples.petclinic.model"
-
+Available customizations are:
+- Modelling: FULLEXPLORATION, ACCUMULATION, PARTIALEXPLORATION;
+- RepositoryType: MONGODB, TEXTFILE, MEMORY, CONSOLE, REDIS;
+- CacheProviderType: MEMCACHED, REDIS, EHCACHE, GUAVA, CAFFEINE;
+
+###### Available annotations and default params
+
+`@AdaptiveCaching`
+- cacheProvider = CacheProviderType.EHCACHE
+- logRepository = RepositoryType.MONGODB
+- modelling = Modelling.ACCUMULATION
+- analyzerEnabled = false
+- enabled = true
+- disableMonitoringAfterAnalysis = true
+- clearMonitoringDataOnStart = true
+- traceAsync = false
+- tracerEnabled = true
+
+`@ComponentScan`
+- allowed = "my.package"
+- denied = "my.package.model"
+
+The framework also provides means for developers to make customizations using hints, indicating possible locations of cacheable methods, which can improve the set of caching candidates as well as exclude methods that should not be cached, thus saving the time of tracking them.
+These indications are done by using the annotations: `@Uncacheable` and `@Cacheable`.
 		
-Customizations
----------
+Inner workings
+--------------
 
-Repository - Repository
-Caching - CacheManager interface
-		
-Snapshots
----------
+To collect data to be analyzed and manage cacheable methods, we intercept method executions using aspect-oriented programming (AOP), more specifically the AspectJ implementation. AOP provides an easy way to weave code at specified points, without changing the base code. APL Cache store method calls with a generic representation of application traces. To compare input and output data of method calls and ensure that structurally equivalent objects have the same representation, objects are loaded and compared by using implementations of the `equals` and `hashCode` methods. Saving actions are performed in an execution thread separate from the one that is processing the request, minimizing response delays.
+
+Available solutions of caching components were also adopted. They provide APIs to manipulate data and access metadata information about the cache, such as statistics and configurations. Our framework is decoupled of particular caching components, and thus supports the most popular distributed cache systems and libraries, which can be configured through property files and annotations. APL Cache automates the decision of what to cache, but such caching components allow us to collect metadata about the cache and also easily manipulate cached content.
 
-Snapshots built from the `master` branch are available through jitpack using version `1.1.0-SNAPSHOT`
+The collected data are analyzed offline, separately from the web application, to prevent impact in the application performance---it can even run on a dedicated machine. To evaluate shared execution traces (accessed by multiple users), we obtain the user session, which is an application-specific information thus taken into account only in application-level caching. Our framework provides a set of alternative implementations to obtain this information from the most popular web frameworks, such as Java EE and the Spring Framework. In case alternative ways of managing user sessions are adopted, developers should implement interfaces provided by our framework.
 
 License
 ------------

diff --git a/framework/toyexample/pom.xml b/framework/toyexample/pom.xml
new file mode 100644
index 0000000..c82a929
--- /dev/null
+++ b/framework/toyexample/pom.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>br.ufrgs.inf.prosoft.adaptivecaching</groupId>
+    <artifactId>system</artifactId>
+    <version>0.1.0-SNAPSHOT</version>
+
+    <properties>
+        <aspectj.version>1.8.9</aspectj.version>
+        <java.version>1.8</java.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>br.ufrgs.inf.prosoft.adaptivecaching</groupId>
+            <artifactId>autonomicmanager</artifactId>
+            <version>0.3.0-SNAPSHOT</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.3</version>
+                <configuration>
+                    <source>${java.version}</source>
+                    <target>${java.version}</target>
+                    <useIncrementalCompilation>false</useIncrementalCompilation>
+                </configuration>
+            </plugin>
+
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>aspectj-maven-plugin</artifactId>
+                <version>1.7</version>
+                <configuration>
+                    <showWeaveInfo>false</showWeaveInfo>
+                    <complianceLevel>${java.version}</complianceLevel>
+                    <source>${java.version}</source>
+                    <target>${java.version}</target>
+                    <Xlint>ignore</Xlint>
+                    <encoding>UTF-8</encoding>
+                    <verbose>false</verbose>
+                    <aspectLibraries>
+                        <aspectLibrary>
+                            <groupId>br.ufrgs.inf.prosoft.adaptivecaching</groupId>
+                            <artifactId>autonomicmanager</artifactId>
+                        </aspectLibrary>
+                    </aspectLibraries>
+                </configuration>
+                <executions>
+                    <execution>
+                        <phase>process-sources</phase>
+                        <goals>
+                            <goal>compile</goal>
+                            <goal>test-compile</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.aspectj</groupId>
+                        <artifactId>aspectjtools</artifactId>
+                        <version>${aspectj.version}</version>
+                    </dependency>
+                </dependencies>
+            </plugin>
+
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+                <version>1.2.1</version>
+                <configuration>
+                    <mainClass>Main</mainClass>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>
\ No newline at end of file

diff --git a/framework/toyexample/src/main/java/asd/Lala.java b/framework/toyexample/src/main/java/asd/Lala.java
new file mode 100644
index 0000000..77217cf
--- /dev/null
+++ b/framework/toyexample/src/main/java/asd/Lala.java
@@ -0,0 +1,12 @@
+package asd;
+
+/**
+ * Created by jhonnymertz on 22/09/15.
+ */
+public class Lala {
+
+    public Integer lala2(){
+        System.out.println("lala2");
+        return 2;
+    }
+}

diff --git a/framework/toyexample/src/main/java/Main.java b/framework/toyexample/src/main/java/Main.java
new file mode 100644
index 0000000..5ee2484
--- /dev/null
+++ b/framework/toyexample/src/main/java/Main.java
@@ -0,0 +1,15 @@
+import asd.Lala;
+import br.ufrgs.inf.prosoft.adaptivecaching.configuration.annotation.AdaptiveCaching;
+import br.ufrgs.inf.prosoft.adaptivecaching.configuration.annotation.ComponentScan;
+import br.ufrgs.inf.prosoft.adaptivecaching.configuration.annotation.types.RepositoryType;
+
+@AdaptiveCaching(logRepository = RepositoryType.CONSOLE)
+@ComponentScan(allowed = "asd")
+public class Main {
+
+    public static void main(String[] args) {
+        new Lala().lala2();
+        new Lala().lala2();
+        //new Foo().redirected("asd");
+    }
+}

diff --git a/framework/toyexample/src/main/resources/adaptivecaching.properties b/framework/toyexample/src/main/resources/adaptivecaching.properties
new file mode 100644
index 0000000..17d1aa1
--- /dev/null
+++ b/framework/toyexample/src/main/resources/adaptivecaching.properties
@@ -0,0 +1,23 @@
+#Example of configuration
+
+#Cache config
+#Redis:
+adaptivecaching.cache.url=localhost
+adaptivecaching.cache.port=6379
+
+#Logging
+adaptivecaching.cache.logging=DEBUG
+adaptivecaching.monitoring.logging=DEBUG
+
+#Repository config:
+##MongoDB:
+adaptivecaching.monitoring.db.scheme=yourdb
+adaptivecaching.monitoring.db.name=logTrace
+adaptivecaching.monitoring.db.port=27017
+adaptivecaching.monitoring.db.address=localhost
+
+##Redis:
+#adaptivecaching.monitoring.db.scheme=yourdb
+#adaptivecaching.monitoring.db.name=logTrace
+#adaptivecaching.monitoring.db.port=27017
+#adaptivecaching.monitoring.db.address=localhost
\ No newline at end of file

diff --git a/README.md b/README.md
index a7a9e3c..f383150 100644
--- a/README.md
+++ b/README.md
@@ -1,89 +1,91 @@
 Seamless and adaptive application-level caching
 =========
 
-#todo describe application-level caching
+Meeting performance and scalability requirements while delivering services is a critical issue in web applications. Recently, latency and cost of Internet-based services are encouraging the use of application-level caching to continue satisfying users' demands and improve the scalability and availability of origin servers. Application-level caching, in which developers manually control cached content, has been adopted when traditional forms of caching are insufficient to meet such requirements. Despite its popularity, this level of caching is typically addressed in an ad-hoc way, given that it depends on specific details of the application. Furthermore, it forces application developers to reason about a crosscutting concern, which is unrelated to the application business logic. As a result, application-level caching is a time-consuming and error-prone task, becoming a common source of bugs. Among all the issues involved with application-level caching, the decision of what should be cached must frequently be adjusted to cope with the application evolution and usage, making it a challenging task.
+
+Application-level caching is mainly characterized by caching techniques employed along with the application code, i.e. business, presentation and data logic. Therefore, it is not tied up to a specific caching location (server-side, proxy or client-side), because it can be conceived at the server-side, to speed up a Java-based application that produces HTML pages sent to users, as well as at the client-side, as a JavaScript-based application that executes part of its logic directly on the client's browser. In both situations, developers can reason about caching and implement a caching logic to satisfy their needs.
 
 Identifying cacheable methods automatically
 ---------
 
-Evaluation...
+###### Evaluation setup
 
-- Three application setups NO, DEV, AP
+- Three applications
+- Three application setups each: NO, DEV, AP
 - Three randomized simulation of execution for each application
 
-#TODO describe simulations
+Simulations were performed using three different caching configurations: (i) no application-level caching (NO), (ii) application-level caching manually designed and implemented by developers (DEV); and (iii) our approach (AP).
 
 Required Tools
 ---------
-- Jmeter (http://jmeter.apache.org/)
-- Mysql (https://www.mysql.com/)
+- [Jmeter] (http://jmeter.apache.org/)
+- MySQL
 - Java 8
 - Maven 3
 
 Applications
 ---------
-#todo describe available apps
-
-Application setup
----------
-[Shopizer] (https://github.com/shopizer-ecommerce/shopizer):
--- Instalar Elasticsearch (https://www.elastic.co/);
--- Base de dados
-
-- Criar schema SALESMANAGER
-- Configurar arquivo database.properties
-- Popular base de dados
--- No arquivo shopizer-properties.xml
---- <prop key="POPULATE_TEST_DATA">true</prop>
---- 7 categories, 6 products, addresses USA, one customer, one admin, shipping info
-
-
-
-◦ Acesso via web
-
-▪ /shop → Páginas da loja
-
-▪ /admin → Administração com login: admin:password
 
+To prevent application bias in our results, we selected applications with different sizes (6.3--111.3 KLOC) and domains.
 
+Our evaluation was performed with three open-source web applications:
+- [Cloud Store] (http://www.cloudscale-project.eu/)
+- [Spring petclinic] (https://github.com/SpringSource/spring-petclinic/)
+- [Shopizer] (https://github.com/shopizer-ecommerce/shopizer)
 
+Application's setup
+-------------------
 
+###### Requirements
 
-Petclinic - https://github.com/spring-projects/spring-petclinic
-
-Criar schema petclinic na base de dados - na primeira inicialização, a base será populada com dados básicos para o funcionamento automaticamente
-Configurar base de dados no arquivo pom.xml
-
-Access
-http://localhost:9966/petclinic/
-
+- Java 8
+- Maven 3
+- Mysql database
 
+[Shopizer] (https://github.com/shopizer-ecommerce/shopizer):
 
-• CloudStore (https://github.com/CloudScale-Project/CloudStore
+This application requires the installation of Elasticsearch (https://www.elastic.co/) to run properly.
 
-◦ Restaurar base de dados do arquivo DEV/database/rds-tpcw-dump-latest.sql
+Installation and configuration:
+- Create schema `SALESMANAGER` on the database
+- Configure the file `database.properties` with your database info
+- Database population: in the file `shopizer-properties.xml` there is the tag `<prop key="POPULATE_TEST_DATA">true</prop>`. Such configuration will provide 7 categories, 6 products, addresses USA, one customer, one admin, shipping info in the database in the first initialization of the system.
+- Compilar e rodar a aplicação: `mvn clean install tomcat7:run-war -DskipTests`
 
-▪ O dump contém 10000 books e está disponível no link: download
+Use the urls above to access system's features
+- /shop → Páginas da loja
+- /admin → Administração com login: admin:password
 
-◦ Configurar base de dados no arquivo
+[Petclinic] (https://github.com/spring-projects/spring-petclinic)
 
-src/main/resources/database/database.hibernate.properties
+Installation and configuration:
+- Create schema `perclinic` on the database
+- Configure database on the file `pom.xml`
+- Populate database: on the first initialization it will be populated automatically
+- Compilar e rodar a aplicação: `mvn clean install tomcat7:run-war -DskipTests`
+- Url to access the system: http://localhost:9966/petclinic/
 
+[CloudStore] (https://github.com/CloudScale-Project/CloudStore
 
-Execução
----------
-mvn clean install tomcat7:run-war -DskipTests
+Installation and configuration:
+- Restore the [dump](https://github.com/CloudScale-Project/CloudStore) located in `DEV/database/rds-tpcw-dump-latest.sql`, such dump has 10000 books
+- Configure database on file `src/main/resources/database/database.hibernate.properties`
+- Compilar e rodar a aplicação: `mvn clean install tomcat7:run-war -DskipTests`
+- Url to access the system: http://localhost:9966/cloudstore/
 
 Simulations
 -----------
 
-Com a aplicação em execução, o Jmeter deve ser aberto e carregado com o sumation setup desejado.
+Our simulation emulated client sessions to exercise applications and evaluate decision criteria. Simulations consisted of 50 simultaneous users constantly navigating through the application, at a limit of 1000 requests per user.
+
+Each emulated client navigates from an application page to another, randomly selecting the next page from those accessible from the current page. The navigation process starts on the application home page. Emulated clients thus follow the same navigation rules of a real user.
+
+After run the application, JMeter is used to simulate load. Thus, open Jmeter, load the simulation setup according to the application that should be evaluated.
 
 Metrics
 -----------
 
-- [throughput] A execução é simples e após o termino da simulação a ferramenta irá informar o throughput.
-
-- [hit ratio] Após a execução da simulação, rodar o jconsole e acessar o atributo referente ao
+To assess performance, we used two metrics: throughput (number of requests handled per second) and hit ratio, because they are well-known in the context of web applications and cache performance tests.
 
-EhCache → Estatistics → Hits.
\ No newline at end of file
+- Throughput is obtained from Jmeter reports
+- Hit ratio must be acquired from `jconsole` after the end of the simulation. The hit ratio will be showed at EhCache → Estatistics → Hits
\ No newline at end of file