View source for Lyo/TRSReferenceApplication

&nbsp;The Guided Tour walks you through the following tasks:<br> 

== Examine how the TRS toolkit helps create a TRS provider via JAX-RS  ==

#Open the file '''org.eclipse.lyo.rio.trs.resources.BaseResource.java'''. Notice '''@Path("/trs/"+TRSConstants.TRS_TERM_BASE)''' at the top of the class.&nbsp;This is a JAX-RS annotation that assigns a relative path (from the jax-rs servlet context) for the Base Resource RESTful endpoint. There are various constants and vocabularies defined in the toolkit to abstract the terms and namespaces from TRS provider implementers.[[Image:BaseResource.png]] 
#In the reference application, the Base Resource is paged so that, according to the specification, a '''GET&nbsp;'''on the base resources will do a redirect to the first page of base resources. This is what happens in the '''getBase()''' endpoint'''. ''' 
#The other method, '''getBasePage(page)''', returns the Base resource at the given page. The class '''org.eclipse.lyo.core.trs.Base&nbsp;'''(and '''org.eclipse.lyo.core.trs.Page''' in the 2.0 release) is provided by the TRS toolkit. It is basically a simple java bean that has been annotated with various OSLC4J annotations to allow the OSLC4J marshalling to create the proper RDF document for the JAX-RS configured serialization. 
#Both methods have additional annotations such as '''@GET''', which identifies the type of HTTP traffic it can handle, as well as an '''@Produces''' that identifies the return type the method can handle. In all cases, the REST endpoints can return Turtle, RDF XML, XML, or JSON. JAX-RS dynamically returns the correct format based on the HTTP request that is received. 
#Open the file '''org.eclipse.lyo.rio.trs.resources.TRSResource.java''' 
#In similar fashion it also has an '''@Path''' annotation that identifies the root of the RESTful service for the Tracked Resource Set. 
#The reference application utilizes the segmented Changelog concept from the TRS Specification. The method '''getTrackedResourceSet()''' returns a tracked resource set with the most recent segment of the changelog. 
#The other method in this class, '''getChangeLog(page)''', returns the segmented portion of the change as requested by the HTTP request

<br> 

=== Trying it out  ===

#Ensure that the reference application is running. If it is not, in the Project Explorer view, in the org.eclipse.lyo.rio.trs project, right-click Launch TRS Reference App.launch and click Run As -&gt; Launch TRS Reference App. 
#The TRS Reference Application includes an index.html file that contains links to the various capabilities provided by the application. To open the page, point your browser at http://&lt;hostname&gt;:8082/org.eclipse.lyo.rio.trs (e.g. http://localhost:8082/org.eclipse.lyo.rio.trs) 
#The first section of the page provides links to the Base and Tracked Resource Set as implemented by the BaseResource and TRSResource classes we observed earlier. Navigate to the Base Resources link. You'll see the Base Resources document in XML form. The format and syntax has been handled by the TRS toolkit's annotated beans and the OSLC4J serializers. 
#Navigate to the Tracked Resource Set link. The change log contained in the Tracked Resource Set should contain a rdf:nil to represent no changes have been made to the resources. 
#Return to the index page and click '''Create Change Request'''. 
#Type in a title and a description, and then click '''Submit Bug'''. Make note of the change request number. 
#Go back to the Tracked Resource Set page and refresh if necessary. Notice an entry in the change log section of the Tracked Resource Set containing a Creation event. If you repeat the creation event more than 3 times, you'll notice the change log being segmented with a previous element containing a URI to return the previous segment of the change log.

<br> 

== Examine how the TRS toolkit helps create a TRS provider via generic Servlet  ==

#Open the file '''org.eclipse.lyo.rio.trs/src/main/webapp/WEB-INF/web.xml'''. Notice the servlet mapping for the relative path '''/restx/trs/base/'''. This maps the Base resource RESTful endpoint to the servlet class '''org.eclipse.lyo.rio.trs.servlet.BaseGeneric'''. 
#Open the file '''org.eclipse.lyo.rio.trs.servlet.BaseGeneric'''. It has an overridden '''doGet '''method, which implements the root of the RESTful service for the Base Resource. 
#In the reference application, the Base Resource is paged so that, according to the specification, a get on the base resources will do a redirect to the first page of base resources. If the path for the Get request contains the page number, it returns the response corresponding to the Base resource at the given page. In a simple servlet implementation, we serialize the Base resource to the response stream using '''OSLC4JMarshaller'''. All implementations of the Base end point handles RDF XML and the 2.0 version adds support for text/turtle.&nbsp; The reference application can be extended to support various other media types based on the HTTP request. 
#Similary, the file '''web.xml''' also contains the servlet mapping for two other endpoints for Tracked Resource Set and Change Log. 
#The servlet mapping for the relative path '''/restx/trs/''' maps the Tracked Resource Set RESTful endpoint to the servlet class '''org.eclipse.lyo.rio.trs.servlet.TRSGeneric'''. 
#Open the file '''org.eclipse.lyo.rio.trs.servlet.TRSGeneric'''. It has an overridden '''doGet '''method, which implements the root of the RESTful service for the Tracked Resource Set. 
#The reference application is utilizing the segmented Changelog concept from the TRS Specification. The method '''toGet()''' populates a '''TrackedResourceSet''' (a simple java bean provided by the toolkit for representing a tracked resource set) with the most recent segment of the changelog. It then serializes the TrackedResourceSet object to the response stream using OSLC4JMarshaller. 
#In a similar fashion, the Changelog endpoint, which is mapped to the the relative path '''/restx/trs/changelog/''', is implemented in the class '''org.eclipse.lyo.rio.trs.servlet.ChangeLogGeneric.java'''.

<br> 

=== Trying it out  ===

#Ensure that the reference application is running. If it is not, in the Project Explorer view, in the org.eclipse.lyo.rio.trs project, right-click Launch TRS Reference App.launch and click Run As -&gt; Launch TRS Reference App. 
#The TRS Reference Application includes an index.html file that contains links to the various capabilities provided by the application. To open the page, point your browser at http://&lt;hostname&gt;:8082/org.eclipse.lyo.rio.trs (e.g. http://localhost:8082/org.eclipse.lyo.rio.trs) 
#The first section of the page provides link "Generic Base Resources" to the Base and "Generic Tracked Resource Set" to Tracked Resource Set as implemented by the BaseGeneric and TRSGeneric classes we observed earlier. Navigate to the Generic Base Resources link. You'll see the Base Resources document in XML form. 
#Navigate to the '''Generic Tracked Resource Set''' link. The change log contained in the Tracked Resource Set should contain an rdf:nil entry to represent no changes have been made to the resources. 
#Return to the index page and click '''Create Change Request'''. 
#Type in a title and a description, and then click '''Submit Bug'''. Make note of the change request number. 
#Go back to the Tracked Resource Set page and refresh if necessary. Notice an entry in the change log section of the Tracked Resource Set containing a Creation event. If you repeat the creation event more than 3 times, you'll notice the change log being segmented with a previous element containing a URI to return the previous segment of the change log.

<br> 

== Change Log Considerations ==

=== Generating Change Log Events ===

There are several ways to generate the change events that populate the change log.  If accessing the resource server's code is possible then it may be easiest to simply alter the code where resources are created, modified, and deleted.  The reference application does this in certain cases.  For example, open the '''ChangeRequestResource.java''' file in the '''org.eclipse.lyo.rio.trs.resources''' package and browse to the deleteChangeRequest() method.  This method handles deleting a resource as well as updating the change log.  The method call to insertEventTypeToChangeLog handles creating a deletion event and inserting it into the change log.

Another, perhaps cleaner way, to achieve the same result is to use the Java listener pattern. Open the '''ChangeRequestListener.java''' file in the '''org.eclipse.lyo.rio.trs.cm''' package.  A new class can implement this ChangeRequestListener interface and override the changeRequestAltered method to be alerted to alterations of underlying resources.  For example, open the '''Persistence.java''' class in the '''org.eclipse.lyo.rio.trs''' package and look at the addListner() method.  The newly created listener can be registered with a method such as this.  Then when alterations occur the listeners can be updated.  Navigate to the addChangeRequest() method and notice that after several operations are performed to create a new resource and save it to disk that the notifyListener method is called.  notifyListener will call all registered listeners and they can react how they wish to the resource alterations.  In this case a change event could be created and inserted into the change log.

A final approach, which is often useful if direct access to the resource server's code is not available is a polling mechanism.  The server with the TRS endpoint can periodically poll the resource server for changes and then generate change events based on what it discovers between polling intervals.  It should be noted that this approach assumes the resource server has a query mechanism of some sort.  Using a timestamp query parameter if available is recommended.

=== When to Generate Change Log Events ===

There are three types of change events: creation, modification, and deletion.  Creation and deletion events are fairly straightforward, they correspond to when an underlying resource is created or deleted respectively.  When to create modification events is not as clear. The server should not report unnecessary change events although it might happen, for example, if changes occur while the base is being computed. If a server knows that a resource will change twice, it can safely emit a single change event to cover both. If a server knows that it will be changing a set of resources, it can safely batch up the change events until it has changed all of them.

=== Persisting and Pruning the Change Log<br>  ===

The change log keeps track of recent modifications to change request resources.&nbsp; When a resource is created, modified, or deleted a change event is created.&nbsp; It is recommended that a resource server persist these events so that the change log may be restored if the resource server needs to be restarted. In order to keep the change log from growing without bounds, it should be pruned periodically.&nbsp; <br> 

Both persisting the change log, and pruning it, are considered best practices as they allow consumers to optimize updates. Instead of examining the entire base for details, consumers can processes a smaller set of data in the change log. Persisting the change log allows this optimization to take place even across server resets. Pruning the log allows a system administrator to control how far back in time consumers may read events in the change log before having to parse the base resource.&nbsp; A history of seven days is recommended as a starting point.&nbsp; However, the administrator should choose a prune time based on how frequently change events are created and how far back in time consumers typically need to search in order to stay in synch with the resource server.<br> 

Once both the Base and Change Log resources are initialized the cutoffEvent property should be set in the Base resource.&nbsp; The cutoffEvent property consists of a URL which points to the most recent change event that exists in both the Base and Change Log.&nbsp; Clients can examine this property to quickly determine what change events exist in the Change Log. 

<br> 

=== Example Implementation (2.0 only)<br>  ===

#Open the file '''org.eclipse.lyo.rio.trs.util.TRSObject.java''' file.<br> 
#Navigate to the '''loadChangeEvents''' method and read the method comment.<br> 
#The method starts by making a call to '''FileUtil.'''''fileload'' which loads any existing change events from file into memory.&nbsp; It should be noted that in a production environment any calls to the '''FileUtil''' class would likely be replaced with calls to a true database. <br> 
#The first for loop examines all change events and sorts them according to their order property.&nbsp; The second for loop makes&nbsp; calls to '''isPrunningNecessary'''() to determine if the current change event being processed should be removed due to its age.&nbsp; The reference application only performs pruning at server startup. In a production system, where a server may remaining for multiple days or weeks without reset, pruning should take place more frequently.<br> 
#If events are pruned, the method saves the pruned list back to disk.<br> 
#Navigate to the '''initialize'''() method and jump to the bottom of the method.&nbsp; Note the call to '''setcutOffEventInner '''and its corresponding comment.&nbsp; This call updates the cutoffEvent property of the base resource, allowing existing clients a mechanism for quickly determing what data the change log contains.&nbsp; The server is now initialized. 
#After initialization the reference application continues to maintain the change log.&nbsp; Navigate to the '''insertEventTypeToChangeLog''' method in the '''TRSResource.java&nbsp;'''file.<br> 
#This method is called whenever a new change event is created in order to insert it into the change log.&nbsp; 
#Note at the bottom of the file how the call to '''FileUtil.save''' persists the new change event so it is available if the server is restarted.

<br>

== Run the TRS compliance test suite to validate the TRS Reference Application's TRS provider  ==

#In the Project Explorer view, expand the '''org.eclipse.lyo.testsuite.trs project''' and navigate to the src/main/resources/config.properties file. The configTrsEndpoint property specifies the location of the TRS resource to be validated by the compliance test suite. The tests also examine the base resource, which is discovered by examining the TRS' trs:base property. 
#Edit the values to point to the location of the TRS Reference Application that you are running. 
#In the '''org.eclipse.lyo.testsuite.trs''' project, right-click Launch All JUnits.launch and click '''Run As -&gt; Launch All JUnits'''.

The TRS compliance JUnit test suite runs and validates the contents of the Base Resources and the Tracked Resource Set of the reference app. The results of the JUnit test are displayed in the JUnit view.<br> 

It should be noted that additional tests exist in the Rio repository. These can be examined by loading the '''org.eclipse.lyo.rio.trs.tests''' project in the same way the '''org.eclipse.lyo.rio.trs '''was loaded. To run these tests, start the reference application and then navigate to '''org.eclipse.lyo.rio.trs.tests/src/main/resources''' and open the config.properties file. This file controls the content and headers that are sent to the resource server, which is the reference application by default. To run these tests again your own server, alter the contents of this file using the comments in the file for reference. A launch file exists in the '''org.eclipse.lyo.rio.trs.tests''' project to assist in running the tests.<br><br> 

[[Lyo/TRSSDK|Return to the main TRS SDK page.]]