com.SIMRacingApps

Class SIMPlugin

java.lang.Object

com.SIMRacingApps.SIMPlugin

Direct Known Subclasses:

iRacingSIMPlugin

public class SIMPlugin
extends java.lang.Object

The SIMPlugin Class defines a generic interface for retrieving SIM data. SIMulators should inherit this class and override the methods for which it can provide data for. Each SIM should try to return the same set of enumerated values defined by the overridden method to allow clients to make hard coded decisions based on those. It doesn't have to do this if the data is to simply be displayed. I will have to admit, I based these on iRacing (my primary SIM), so other SIMs will have to conform.

To create a connector, you do not call "new SIMPlugin(String)" as this class should be considered abstract. Instead call the static factor method createSIMPlugin(String), where the String argument is the SIM's name. See below for supported SIMs.

Once a connector has been created, you then call run(Callback) method passing in an instance of a Callback Class that you must implement to get called when data is available.

So, to make things a little easier, I have 2 implementations for you to use out of the box. For Java Applications, see SIMPluginAWTEventDispatcher. This dispatcher allows you to register standard PropertyListener's that will receive events when data they are listening to changes. For Web Server Applications, I have implemented several J2EE Servlets for different protocols, including HTTP and Web Socket. See com.SIMRacingApps.servlets for details.

The most important SIMPlugin method is getData(String). This method takes a string that is formatted as a path to the data you want to get or change. It breaks down this path and calls the corresponding method to retrieve the data. The method the path maps to must return a Data object and be overloaded to take String arguments. In a pure Java Application, you can also get a reference to these objects through the SIMPlugin instance and call them directly. Here are the main path entry points. See the documentation for each one for more details on the data they can provide.

    //NOTE: The leading slash is optional
    
    /(method)/(args)
    /TeamSpeak/(method)/(args)
    /Session/(method)/(args)
        /Session/Track/(method)/(args)
        /Session/Car/(car)/(method)/(args)
            /Session/Car/(car)/Gauge/(gaugeType)/(method)/(args)
    
    //Also, the Car and Track can be accessed without the /Session prefix on the path as follows.
    
    /Track/(method)/(args)
    /Car/(car)/(method)/(args)
        /Car/(car)/Gauge/(gaugeType)/(method)/(args)
        
    //For direct access to the SIM's data, put the SIM name as the first argument followed by the path.
    //Refer to the SIM's documentation for available paths. It is beyond the scope of these documents to do so.
    //If you find yourself needing to use this, consider implementing a generic method, 
    //so clients do not have to be SIM specific.
    
    /iRacing/(args)
    
    //TODO: Put a link to all supported SIMs
 

• Data d = connector.getData("/Session/Car/LEADER/Lap/Completed");
• Data d = connector.getData("/Car/LEADER/Lap/Completed");
• //SIM specific, not recommended
• Data d = connector.getData("/iRacing/SessionInfo/Sessions/1/ResultsPositions/0/LapsCompleted");
• Data d = connector.getSIMData("SessionInfo","Sessions","1","ResultsPositions","0","LapsCompleted");

Since:

1.0

Author:

Jeffrey Gilliam

Copyright:

Copyright (C) 2015 - 2024 Jeffrey Gilliam

License:

Apache License 2.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SIMPlugin.Callback This interface is used to call back to your implementation as data is received.
static class	SIMPlugin.SIMPluginException This class returns the exception message thrown by the SIMPlugin Class

Method Summary

Modifier and Type	Method and Description
boolean	addCallback(java.lang.String name) Creates a callback instance from the specified name
void	close() Closes the connection to the SIM and kills any threads it may have spawned.
static SIMPlugin	createSIMPlugin(java.lang.String SIM) A static factory method for creating a SIM specific connector and returning it.
SIMPluginCallback	getCallback(java.lang.String name) Returns an instance to a callback.
Data	getData(java.lang.String path) Returns a value from the SIM.
Data	getEndingVersion() Returns the Data Version of where the playing file should stop.
Data	getPlay() Returns the name of the currently playing recorded file.
Data	getRecord() Returns the name of the file being recorded.
Session	getSession() Returns an instance to the SIM's session.
Data	getSetting(java.lang.String arg)
Data	getSetting(java.lang.String arg, java.lang.String defaultValue) Returns the value of arg from the settings.txt file.
Data	getSIMData(java.lang.String... args) This gets called when the path specifies a specific SIM should return the data.
Data	getSIMName() Returns the name of the SIM this connector is for.
Data	getStartingVersion() Returns the Data Version of where the playing file should start.
Data	getSync() Returns the sync flag.
Data	getVersion() Returns the version of the SIMRacingApps Plugin as a String in a printable format.
Data	getVolume() Returns the master volume setting as a percentage.
void	removeCallback(java.lang.String name) Removes a callback.
void	run()
void	run(SIMPlugin.Callback callback) Starts the run loop that notifies the caller when data is available through the Callback class.
Data	setEndingVersion(java.lang.String endingversion) Sets the Data Version of where the playing file should stop.
Data	setPlay(java.lang.String Filename) Sets the filename to be played back.
Data	setRecord(java.lang.String Filename) Sets the filename to record this session to.
Data	setStartingVersion(java.lang.String startingversion) Sets the Data Version of where the playing file should start.
Data	setSync(boolean sync) Sets the the sync flag.
Data	setSynce(java.lang.String sync)
Data	setVolume(double percentage) Returns the master volume setting as a percentage.
Data	setVolume(java.lang.String percentage)

Methods inherited from class java.lang.Object

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

Method Detail

createSIMPlugin

public static SIMPlugin createSIMPlugin(java.lang.String SIM)
                                 throws SIMPlugin.SIMPluginException

A static factory method for creating a SIM specific connector and returning it.

For example: SIMPlugin c = SIMPlugin.createSIMPlugin("iRacing");

Parameters:

SIM - The name of a SIM supported by a SIMPlugin class implementation in the com.SIMRacingApps.SIMPlugins package.

Returns:

A SIMPlugin

Throws:

SIMPlugin.SIMPluginException - If there's a problem creating a SIMPlugin instance for this SIM.

close

public void close()

Closes the connection to the SIM and kills any threads it may have spawned.

addCallback

public boolean addCallback(java.lang.String name)

Creates a callback instance from the specified name

Parameters:

name - The callback class name relative to com.SIMRacingApps.SIMPluginCallbacks.

Returns:

true if callback was loaded, false if not.

getCallback

public SIMPluginCallback getCallback(java.lang.String name)

Returns an instance to a callback. If the callback is not loaded, it returns null.

Parameters:

name - The callback name as it is named in the list of callbacks.

Returns:

an instance to the callback or null if not loaded.

removeCallback

public void removeCallback(java.lang.String name)

Removes a callback. If it is not loaded, silently ignores the call.

Parameters:

name - The callback name as it is named in the list of callbacks.

getSIMName

public Data getSIMName()

Returns the name of the SIM this connector is for.

PATH = /SIMName

Returns:

The SIM name in a Data container.

getPlay

public Data getPlay()

Returns the name of the currently playing recorded file.

Returns:

The filename that is playing in a Data container.

setPlay

public Data setPlay(java.lang.String Filename)

Sets the filename to be played back.

Parameters:

Filename - The complete path to the file to play.

Returns:

The filename in a Data container.

getRecord

public Data getRecord()

Returns the name of the file being recorded.

Returns:

The filename in a Data container.

setRecord

public Data setRecord(java.lang.String Filename)

Sets the filename to record this session to. If it is not a fully qualified path to a file, then it will be saved in the userpath/recordings folder.

Parameters:

Filename - The complete path to the file to record to.

Returns:

The filename in a Data container.

getStartingVersion

public Data getStartingVersion()

Returns the Data Version of where the playing file should start.

Returns:

The starting version in a Data container.

setStartingVersion

public Data setStartingVersion(java.lang.String startingversion)

Sets the Data Version of where the playing file should start. This is passed to the SIM, so the format will be SIM specific.

Parameters:

startingversion - The starting version in the format specified by the SIM.

Returns:

The starting version in a Data container.

getEndingVersion

public Data getEndingVersion()

Returns the Data Version of where the playing file should stop. This is passed to the SIM, so the format will be SIM specific.

Returns:

The ending version.

setEndingVersion

public Data setEndingVersion(java.lang.String endingversion)

Sets the Data Version of where the playing file should stop.

Parameters:

endingversion - The ending version in the format specified by the SIM.

Returns:

The ending version in a Data container.

getSetting

public Data getSetting(java.lang.String arg,
                       java.lang.String defaultValue)

Returns the value of arg from the settings.txt file.

Parameters:

arg - The name of the setting value to return.

defaultValue - (Optional) The value to return if the arg is not defined. Defaults to empty string.

Returns:

The value of arg or the defaultValue if not found

getSetting

public Data getSetting(java.lang.String arg)

getSync

public Data getSync()

Returns the sync flag. The sync flag is used to slow down the playing file to real-time. Turn sync off, to read as fast as you can.

Returns:

The sync flag

setSync

public Data setSync(boolean sync)

Sets the the sync flag. The sync flag is used to slow down the playing file to real-time. Turn sync off, to read as fast as you can.

Parameters:

sync - Y or N

Returns:

The sync flag in a Data container.

setSynce

public Data setSynce(java.lang.String sync)

getVolume

public Data getVolume()

Returns the master volume setting as a percentage.

PATH = /Volume

Returns:

The master volume as a percentage in a Data container.

setVolume

public Data setVolume(double percentage)

Returns the master volume setting as a percentage.

PATH = /Volume/(PERCENTAGE)

Parameters:

percentage - The new volume as a percentage. Range 0.0 to 100.0.

Returns:

The master volume as a percentage in a Data container.

setVolume

public Data setVolume(java.lang.String percentage)

getData

public Data getData(java.lang.String path)
             throws SIMPlugin.SIMPluginException

Returns a value from the SIM. The path argument, is formatted like a URL with slashes as separators. A leading slash is optional.

The first argument is tested to see if it matches a public method on this class that takes the same number of String arguments, then calls it. If it's a "get", the "get" is optional, but "set", "decrement", and "increment" are required. If the first argument matches the name of the SIM, all the arguments are passed to the SIM version of getSIMData(String...). It is not recommended to call the SIM version directly as this will tie your client to that SIM. Although you will have to use it if the API is missing something you need, but consider enhancing the generic API instead.

For Examples see SIMPlugin.

Parameters:

path - The path to the requested value with arguments separated by slashes in a RESTfull syntax.

Returns:

null if return value is void, else the value in a Data container. If the path was invalid, then it returns an error message in a Data container with the State set to ERROR.

Throws:

SIMPlugin.SIMPluginException - for other syntax or runtime errors

run

public void run(SIMPlugin.Callback callback)

Starts the run loop that notifies the caller when data is available through the Callback class. Each caller must provide an instance Callback class to process the data. Note: If you don't call this in a new Thread, it will not return until your Callback class tells it to exit.

Parameters:

callback - (Optional) An instance a callback implementation to process the data

run

public void run()

getSession

public Session getSession()

Returns an instance to the SIM's session. Each SIM should override this method and return a SIM specific session instance.

Returns:

A session as defined by Session

getVersion

public Data getVersion()

Returns the version of the SIMRacingApps Plugin as a String in a printable format.

PATH = /Version

Returns:

The Server Version for this SIM

getSIMData

public Data getSIMData(java.lang.String... args)

This gets called when the path specifies a specific SIM should return the data. Each SIM should override this and return the requested data

Parameters:

args - An array of String arguments as specified by the SIM.

Returns:

The value in a Data container.