com.SIMRacingApps.SIMPluginCallbacks

Class SIMPluginCallback

java.lang.Object

com.SIMRacingApps.SIMPluginCallbacks.SIMPluginCallback

All Implemented Interfaces:

SIMPlugin.Callback

Direct Known Subclasses:

Flags, MyCallback, PitCountDown, PitSpeedLimit, Post, Shift, ShiftLight

public class SIMPluginCallback
extends java.lang.Object
implements SIMPlugin.Callback

This class is the abstract base class for all SIMPluginCallback classes. By implementing this class, you can hook into the event loop and get data from the SIM. Here are the specifics of how to develop your plug-in for the SIMRacingApps Server. Create a new class com.SIMRacingApps.SIMCallbacks.{YourNameOrCompany}.{YourPluginClass} in the com.SIMRacingApps.SIMCallbacks.{YourNameOrCompany} package that extends SIMPluginCallback. There is a Template plug-in folder in the SIMPluginCallbacks folder that you can copy and rename. NOTE: Each subclass can define methods that return Data objects and if a Data Url maps to a method on the class, it will call it. Example: /SIMRacingApps/SIMPluginCallback/Sounds/PitCountDown/setVolume/50 will call the setVolume method and pass it 50. If you know Java, you will probably know how to compile your source code. But just in case you don't, here's an example how. Of course, your specific server version may be different.

    {pathToJDK}\bin\javac -cp "%USERPROFILE%"\Documents\SIMRacingApps\SIMRacingAppsServer_1.0_Build_BETA-2016.01.09.exe" *.java
 

For testing, put the .class file(s) generated in the "Documents\SIMRacingApps\com\SIMRacingApps\SIMPluginCallbacks\{YourNameOrCompany}" folder. Add the plug-in classes to the settings.txt file's "simplugins" entry. Each plug-in should be separated by a semicolon. The SIMRacingApps Server will load your plug-in upon startup of the server.

 settings.txt
    simplugins = YourNameOrCompany.YourPluginClass;Name1.DoSomething;Name2.DoneIt
 

When testing, if the plug-in is already built into the SIMRacingAppsServer, you will have to alter the classpath to look for your new .class files to load before the built in ones. To do that, do not run the SIMRacingAppsServer.exe directly. Instead, use the following example command, on how to use it as a library and put your stuff first in the path.

   {pathToJRE}\bin\java -cp "%USERPROFILE%"\Documents\SIMRacingApps\com\SIMRacingApps\SIMPluginCallbacks\{YourNameOrCompany}:%USERPROFILE%"\Documents\SIMRacingApps\SIMRacingAppsServer_1.0_Build_BETA-2016.01.09.exe" com.SIMRacingApps.Server

For distribution, create a jar file with your .class file(s). We are going to use a .sra extension instead of .jar for uploading to the SIMRacingApps Server through the menu.

  Example:
    jar cvf YourPlugin_v1.0.sra -C "%USERPROFILE%\Documents\SIMRacingApps" com/SIMRacingApps/SIMPluginCallbacks/{YourNameOrCompany}
 

Distribute the .sra file with instructions to upload it to SIMRacingApps through the main menu. Also provide instructions on how to enable your plug-in by adding it to the settings.txt->plugins variable. For distribution with a Java App that uses the SIMRacingAppsServer.exe as a jar file, just add the .sra file to the classpath. If you would like your plug-in distributed as part of SIMRacingApps, please send me a request to do so at support@simracingapps.com.

Since:

1.0

Author:

Jeffrey Gilliam

Copyright:

Copyright (C) 2015 - 2024 Jeffrey Gilliam

License:

Apache License 2.0

Constructor Summary

Constructors

Constructor and Description
SIMPluginCallback(SIMPlugin SIMPlugin, java.lang.String name) Constructor.

Method Summary

Modifier and Type	Method and Description
boolean	DataReady(SIMPlugin SIMPlugin, java.lang.Integer ips) This method is called every time the SIM has new data available.
void	destroy() Called when the SIMPlugin is destroyed.
boolean	ProcessData(SIMPlugin SIMPlugin, java.util.Map<java.lang.String,Data> data) ProcessData is called from within the dedicated thread for this plug-in every time there is data available in the queue it pops it off the queue and passes it to this method.
boolean	Waiting(SIMPlugin SIMPlugin) Waiting() is called every second if the SIM is not providing any data.

Methods inherited from class java.lang.Object

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

Constructor Detail

SIMPluginCallback

public SIMPluginCallback(SIMPlugin SIMPlugin,
                         java.lang.String name)
                  throws SIMPlugin.SIMPluginException

Constructor. Provides you with an instance of the SIM. You will need to override this constructor with SIMPlugin as a parameter and call super(SIMPlugin). Use the constructor to initialize your plug-in.

Parameters:

SIMPlugin - An instance of the current SIM.

name - The name of the plug-in so you can find it's thread in a debugger and show it in the logger messages.

Throws:

SIMPlugin.SIMPluginException - If there's a problem constructing your plug-in.

Method Detail

destroy

public void destroy()

Called when the SIMPlugin is destroyed. If you override this method, be sure to call super.destroy() first.

DataReady

public boolean DataReady(SIMPlugin SIMPlugin,
                         java.lang.Integer ips)

This method is called every time the SIM has new data available. By default this method push the data into the queue. You should not need to override this method. It will not block if the queue is full. I do this so your plug-in gets data that is very close to real-time. If it takes to look to process the queue, then you will simply get the next available data.

Specified by:

DataReady in interface SIMPlugin.Callback

Parameters:

SIMPlugin - An instance of the current SIM.

ips - Iterations per second.

Returns:

true to stay alive, false to stop the server.

Waiting

public boolean Waiting(SIMPlugin SIMPlugin)

Waiting() is called every second if the SIM is not providing any data.

Specified by:

Waiting in interface SIMPlugin.Callback

Parameters:

SIMPlugin - An instance of the current SIM.

Returns:

true to stay alive, false to stop the server.

ProcessData

public boolean ProcessData(SIMPlugin SIMPlugin,
                           java.util.Map<java.lang.String,Data> data)

ProcessData is called from within the dedicated thread for this plug-in every time there is data available in the queue it pops it off the queue and passes it to this method. A should override this method to implement your plug-in's functionality. If this method takes too long to process the data in the queue, you could miss data that the SIM is sending. Design accordingly. There's no way to even guarantee that you will get every update from the SIM. At this point in the design, ProcessData will get called on the same frequency as the SIM (typically 16ms). At some point, I may change it to only get called if the subscribed to data changes. NOTE: If you find you need to use the SIMPlugin argument, inclose it in a synchronized block. You are in a separate thread, so this will block the main thread. Do not keep it locked very long.

     //When calling the SIMPlugin from this method, you must synchronize on it first. It is not thread safe.
     Data d;
     synchronized (SIMPlugin) {
         //do not spend much time in here, we are blocking the main thread 
         //Get the data and get out of the synchronized block 
         d = SIMPlugin.getData("/Session/IsGreenFlag");
         d = SIMPlugin.getSession().getIsGreenFlag();
     }
     //do something with the data
 

Parameters:

SIMPlugin - A reference to the SIMPlugin instance.

data - The Data objects added to the queue.

Returns:

true to keep the plug-in alive, false to kill it.