doc/org.eclipse.tracecompass.incubator.trace.server.doc.dev/doc/Developer-Guide.mediawiki - tracecompass.incubator/org.eclipse.tracecompass.incubator - Git at Google


 = Trace Server =

 The Trace Server is a prototype implementation of the [https://theia-ide.github.io/trace-server-protocol/ 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<T>''' or annotate a POJO's constructor with '''@JsonCreator''' and '''@JsonProperty'''.

	= Trace Server =

	The Trace Server is a prototype implementation of the [https://theia-ide.github.io/trace-server-protocol/ 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<T>''' or annotate a POJO's constructor with '''@JsonCreator''' and '''@JsonProperty'''.