Trace Service API

#Quick guide

Getting Trace Data: Get a TraceHelper

To obtain the current data of the trace service, you should subscribe to the "traceChanged" event and its payload.data will contain the most recent TraceHelper. More details in the following sequence diagram:

Once you obtain the trace helper, you can get the data formatted in different forms. More details below. ####Note: isValid() method will be available after sprint #5.

###0. Your class must have an event aggregator In order to subscribe to Aurelia event system, you should an Event Aggregator defined in your class. You could inject it or receive it from another class.

###1. Import and instantiate the Trace Model In this class, we consolidated all structures used in our API. You will need this library to obtain the events that are published by the trace service.

import {TraceModel} from '../traceService/trace-model';
export class YourClass{
   constructor(){
       this.traceModel = new TraceModel();
   }
}

Similar to the event aggregator, you could inject it or receive it from another class.

###2. Subscribe to trace changes and obtain a Trace Helper in the following snippet, traceChangedEvent contains the name of the trace changed event. Once you subscribed, payload.data returns the latest trace helper.

let traceChangedEvent = this.traceModel.traceEvents.changed.event;
        this.eventAggregator.subscribe( traceChangedEvent, payload =>{
            let traceHelper = payload.data;
            // do something
        });

###4. List of helper methods

####4.1 Variables and their values Let's look this example:

let a= false;
let b = 0;
while(b< 5){
    b++;
    let  c=b;
}

The trace helper (payload.data), offers the following methods:

    let variables= traceHelper.getVariables();
    let values = traceHelper.getValues();

Their format is as follows: #####getVariables() After execution, each variable definition is logged in the following structure:

    variables = [
{"id":"a","range":{"start":{"row":0,"column":4},"end":{"row":0,"column":12}}},
{"id":"b","range":{"start":{"row":1,"column":4},"end":{"row":1,"column":9}}},
{"id":"c","range":{"start":{"row":4,"column":9},"end":{"row":4,"column":12}}}
];

where "id" is the identifier of that variable and "range" is the location in Ace's range format.

#####getValues()

    values = [
{"id":"a","value":"false","range":{"start":{"row":0,"column":4},"end":{"row":0,"column":12}}},{"id":"b","value":"0","range":{"start":{"row":1,"column":4},"end":{"row":1,"column":9}}},
{"id":"c","value":"1","range":{"start":{"row":4,"column":9},"end":{"row":4,"column":12}}},
{"id":"c","value":"2","range":{"start":{"row":4,"column":9},"end":{"row":4,"column":12}}},
{"id":"c","value":"3","range":{"start":{"row":4,"column":9},"end":{"row":4,"column":12}}},
{"id":"c","value":"4","range":{"start":{"row":4,"column":9},"end":{"row":4,"column":12}}},
{"id":"c","value":"5","range":{"start":{"row":4,"column":9},"end":{"row":4,"column":12}}}
];

Similar to getVariables(), the "id" and "range" contain the same information. Now, value contains the value at point in time during the execution of the code. Furthermore, the values array is sorted by execution time in ascending order.

#####4.X More to come based on feedback #Trace Service Execution Flow This is the whole picture of how Trace Service works:

the client sends the source code text as input (we will discuss other parameters later). Then, the service will add log calls to that code and run it. Once it ends it will return the results. In the snippet, when the source code changes, the method publishes the event "traceChanged" with the trace output as payload.

We have the following events for the service:

Normally, you will expect an output like the one above. However, long code or problems such as infinite loops/recursion and runtime errors could happen, so we can keep your inform of what is going on. These are the events the service handles:

#API Documentation

trace-helper.js class

===== Public Method(s) =====================================

2. getLineValues(Integer lineNumber, Map valueTable): Array

• Usage: get all the values of the "lineNumber" stored in an array
• Parameter Information: none.
• Function Dependencies: getValues(Map esprimaRange, Map valueTable): Array
• Class Dependencies: none.

3. getValues(Map esprimaRange, Map valueTable): Array

• Usage: get all the values within the "esprimaRange" stored in an array
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: none.

4. getValuesWithType(Map esprimaRange, Map valueTable): Map

• Usage: get all the values with the type within the "esprimaRange" stored in a map
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: none.