com.SIMRacingApps.servlets

Class Data

java.lang.Object

javax.servlet.GenericServlet

javax.servlet.http.HttpServlet

com.SIMRacingApps.servlets.Data

All Implemented Interfaces:

java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

@WebServlet(description="SIMRacingApps Data Access for JSON",
            urlPatterns={"/Data","/Data/*"},
            loadOnStartup=1)
public class Data
extends javax.servlet.http.HttpServlet

This class implements the "/Data" interface for the HTTP protocol. It accepts the POST and GET methods for requesting and receiving data from the SIM.

There are 2 ways to use these methods. One is Subscribe and Publish and the other is ReST(Representational State Transfer).

Subscribe and Publish

This process uses the POST method to subscribe to the data to publish. The GET method is then used to poll the server for the published changes. Through other HTTP interfaces, you can also use Web Socket Polling, Web Socket Streaming, and Web Events to receive the published changes.

Both POST and GET must have a parameter called "sessionid", in the URL query string, with a value that will be used to identify who the subscriptions below to. Depending on the client, you may want to disable caching by adding a counter parameter that is incremented on every call to GET. To help out, the response headers are also set to disable caching. For example: http://localhost/SIMRacingApps/Data?sessionid=1234567890. I would recommend using a value that will not conflict with other clients using the server at the same time, like time of day down to the millisecond.

The body of the POST method must be formatted as a JSON string according to the following structure. This same structure will be updated with the values and returned to you when you call GET. It is important to note, that only changes are returned by GET for performance reasons. Changes means, that if any of the "names" associated with an "id" changes, then all of the "names" for that "id" are returned. Also, when the Interval has passed, all "names" with a shorter or equal Interval will also be returned so they will all be in sync with the SIM.

 {
   "(id)":  {  "(name)":  { "Name": "(datapath)",  "Format": "(formatstring)",  "UOM": "(requesteduom)",  "Interval": (milliseconds) }
          ,    "(name2)": { "Name": "(datapath2)", "Format": "(formatstring2)", "UOM": "(requesteduom2)", "Interval": (milliseconds) }  //optional
          ,... //followed with as many as you need
        }
  ,"(id2)": {  "(name)":  { "Name": "(datapath)",  "Format": "(formatstring)",  "UOM": "(requesteduom)",  "Interval": (milliseconds) }  //optional
          ,    "(name2)": { "Name": "(datapath2)", "Format": "(formatstring2)", "UOM": "(requesteduom2)", "Interval": (milliseconds) }  //optional
          ,... //followed with as many as you need
        }
  ,...
 }
 

id

An identifier to be used as you see fit. It is only used by the server to group names together.

name

Also an identifier to be used as you see fit.

datapath

A path to the SIM data you are subscribing to. For example: "/Car/REFERENCE/Description".

formatstring

A format string using the syntax of Formatter.

requesteduom

The unit of measure you would like the result in. Note: If it cannot be converted, the SIM's UOM is returned.

milliseconds

How often this particular should check for changes. Slowing these down can help performance.

POST also supports the following parameters in the query string:

• startingversion=(startingVersion) - a SIM specific counter of where to start playing the recorded file.
• endingversion=(endingVersion) - A SIM specific counter of where to stop playing the record file.
• play=(filename) - Plays the previously recorded file.
• record=(filename) - Records the current session to a file. Saves the file in SRA_DIR/webapps/SIMRacingApps/recordings.
• stop - stops playing or stops recording.

The GET method should be called at least as often as the smallest Interval of all the names in the subscribed data structure. It returns the changed data in the very same format as you subscribed to with the additional attributes added. For details about these attributes, see Data. Also, the call to POST will return this data as well. So, you want to parse the response body for both. Failure to call GET within 10 seconds of the last call will assume the client has died and delete the session cache. This should not be a problem as most practical applications will need to call GET multiple times per second. To recover, the client can call POST again.

• ValueFormatted
• Value
• Type
• UOMAbbr
• UOMDescr
• State
• StatePercent

ReST

With ReST you do not call POST, because you can only specify one data path in the URL. Instead, you call GET with the data path appended to the URL after "/Data". For example: http://localhost/SIMRacingApps/Data/Car/REFERENCE/Description. Because of this, ReST does not perform as well as Subscribe/Publish for larger data sets. It also does not guarantee the data will be in sync between the calls to GET for multiple values. Therefore, it usefulness is degraded to when Subscribe/Publish is not needed, such as, one time or infrequent calls. By default, this returns a JSON string formatted "pretty" because I see it primarily being used from the browser ad-hoc. If the data returned refers to a structure, then the ValueFormatted may actually be a JSON string. For example: http://localhost/SIMRacingApps/Data/Car/REFERENCE, will return all the data available for that car in JSON format. You can specify the following parameters in the query string to change result returned.

• lang=(lang), to the data be localized to this language instead of the servers default.
• format=(format), a format using Formatter syntax.
• uom=(uom), the unit of measure to return the result in.
• output=(one of the following. See Data for details).
  • ValueFormatted,Formatted - Returns the Value formatted with the "format" string and translated to "lang".
  • Value - Returns the raw value.
  • State - Returns the state.
  • StatePercent - Returns the percentage of the Value of the State that it is in.
  • Lang - Returns the language/locale of the request.
  • Uom - Returns the raw unit of measure code.
  • UOMAbbr - Returns the short name of the UOM.
  • UOMDescr - Returns the long name of the UOM, pluralized.
  • JSON - Returns the entire Data object as a JSON string.
  • Pretty - The default. Returns the entire Data object as a JSON string, but formatted for readability.

What data paths are available?

The paths that are available is determined by searching the following classes for methods that returns a "Data" object and either takes no arguments or all of the arguments are strings. See each class for available paths.

• SIMPlugin
• Session
• Track
• Car
• Gauge
• TeamSpeak

Since:

1.0

Author:

Jeffrey Gilliam

See Also:

Serialized Form

Copyright:

Copyright (C) 2015 - 2024 Jeffrey Gilliam

License:

Apache License 2.0

Constructor Summary

Constructors

Constructor and Description
Data() Default Constructor.

Method Summary

Modifier and Type	Method and Description
void	destroy() Gets called when the container destroys this object
void	init(javax.servlet.ServletConfig config) Initializes the servlet by getting the IP address and version information.

Methods inherited from class javax.servlet.http.HttpServlet

service

Methods inherited from class javax.servlet.GenericServlet

getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Data

public Data()

Default Constructor.

See Also:

HttpServlet()

Method Detail

init

public void init(javax.servlet.ServletConfig config)
          throws javax.servlet.ServletException

Initializes the servlet by getting the IP address and version information. It displays this information in the log and in the title bar of the server window. The loadOnStartup option is enabled, so this gets called as soon as the server starts up.

Specified by:

init in interface javax.servlet.Servlet

Overrides:

init in class javax.servlet.GenericServlet

Parameters:

config - The Servlet's configuration information.

Throws:

javax.servlet.ServletException - Thrown so the server can log the error.

destroy

public void destroy()

Gets called when the container destroys this object

Specified by:

destroy in interface javax.servlet.Servlet

Overrides:

destroy in class javax.servlet.GenericServlet