Skip to content
This repository has been archived by the owner on Mar 20, 2024. It is now read-only.

Latest commit

 

History

History
72 lines (50 loc) · 3.82 KB

Developer-Guide.mediawiki

File metadata and controls

72 lines (50 loc) · 3.82 KB
Raw

Table of Contents

Trace Server

The Trace Server is a prototype implementation of the Trace Server Protocol. It was built to decouple the front-end and back-end of Trace Compass and allow visualization of traces which are stored and analyzed on a remote machine.

Starting the Trace Server

From Eclipse

Open traceserver.product and launch it as an Eclipse application.

From the Command Line

  • Build the incubator from the command line:
   mvn clean install

  • The built product should be found at:
   trace-server/org.eclipse.tracecompass.incubator.trace.server.product/target/products/traceserver/linux/gtk/x86_64/trace-compass-server/tracecompass-server

Failure to start

  • Try resetting the product run configuration in Eclipse.

Querying the Trace Server

The Trace Server is ready to query once the following line is logged: 

   Server:app thread - org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.id.0: Started @1970ms

The Trace Server can be queried via any http client (curl, Postman, Jersey client). By default it's url will be: 

   http://localhost:8080

Architecture

The Trace Server combines an Eclipse RCP with the backend program from Trace Compass and a Jetty server / servlet engine which runs the Jersey services which expose the relevant Trace Compass APIs as a REST protocol.

Available Services

The current implementation of the Server exposes 5 services:

  • Trace Manager Service: to import and open and manage traces on the server's file system
  • Experiment Manager Service: to combine traces into experiments
  • Data Provider Service: to expose data provider APIs to access analysis results
  • XML Manager Service: to extend the server's features from XML analysis and views on the server's file system

Extension model

Being built on Eclipse RCP, the Trace Server supports the same extension mechanism as Trace Compass.

Developing the Trace Server

Adding a Service

To add a service, it just needs to be registered programmatically in the WebApplication.

Adding a new data model

To serialize data from Java objects, these are the following options:

Serialize an entire POJO

Just encapsulate the POJO in a Response, and it will most likely be directly serializable to JSON. However anything that is accessible via a getter will be serialized. This can be a problem if that represents a large volume of data, or if the objects returned by the getter are not serializable.

The following exceptions may indicate that a data type cannot be serialized: 

   com.fasterxml.jackson.databind.JsonMappingException

Annotate a POJO

If the POJO to serialize is editable, javax.xml.bind.annotation and com.fasterxml.jackson.annotation annotations are supported.

Implement a serializer

Finally, if a packaged type requires custom serialization, we recommend implementing a com.fasterxml.jackson.databind.ser.std.StdSerializer and registering it to the data type in the web application.

Testing a Trace Server Feature

The simplest way to test a new feature is to write a test extending: 

   org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests.utils.RestServerTest

which handles launching a trace server, and provides a client targeted at this server, as well as utilities to load traces and clean up after.

Deserializing data

Typically one has to be able to read returned data to ensure that it is correct.

Most TraceCompass POJOs will not be readable out of the box as immutability was a key design decision, and Jersey deserializers require a default constructor and setters. The alternative is to implement a com.fasterxml.jackson.databind.deser.std.StdDeserializer or annotate a POJO's constructor with @JsonCreator and @JsonProperty.