org.sunspotworld.demo.util
Class Spotlet

java.lang.Object
  javax.microedition.midlet.MIDlet
      org.sunspotworld.demo.util.Spotlet

All Implemented Interfaces:

com.sun.spot.peripheral.ota.IOTACommandServerListener, com.sun.spot.util.IBootloaderListenerCallback

Direct Known Subclasses:

TelemetryMain

public abstract class Spotlet
extends javax.microedition.midlet.MIDlet
implements com.sun.spot.peripheral.ota.IOTACommandServerListener, com.sun.spot.util.IBootloaderListenerCallback

Start of a framework for robust SPOT applications. Provides simple lifecycle management of application code by handling any fatal errors the application causes. The application main class should extend Spotlet and implement the following methods: (only run is necessary)

• initialize() - do any initialization needed by the Spot application.
• run() - the Spot application code to run.
• reinitialize() - reinitialize the world before re-running the Spot application. Called after an error has terminated the applications run method.
• quit() - if the Spot application is running have it stop.
• cleanup() - cleanup any resources used by the Spot application.

Other methods specify how many times to retry the application after errors, whether to run a OTACommandServer for over-the-air deployment of new code, etc.

Author:

Ron Goldman
Date: April 18, 2006

Constructor Summary

Spotlet()
Creates a new instance of Spotlet

Method Summary

void	cleanup() Cleanup any resources used by the Spot application.
protected void	destroyApp(boolean arg0) Only called if startApp throws any exception other than MIDletStateChangeException.
boolean	firstRun() Indicate if this is the first time the application has been run.
long	getCurrentRunTime() Return the elapsed time for the current call to the application's run method.
java.lang.Throwable	getLastError() Return the last Error or Exception thrown by the application.
long	getLastRunTime() Return the elapsed time for the previous call to the application's run method.
int	getNumberRetries() Return the number of times to retry the application after an error.
int	getNumberRuns() Return the number of times the application has been run.
long	getTimeBetweenRetries() Return the time in milliseconds to wait before retrying the application after an error.
long	getTotalRunTime() Return the total time that this application has been running.
void	initialize() Do any initialization needed by the Spot application.
static void	pause(long time) Pause for a specified time.
protected void	pauseApp() This will never be called by the Squawk VM.
void	postFlash() Called by OTACommandServer after flashing a new application.
void	preFlash() Called by OTACommandServer before flashing a new application.
void	prepareToExit() Callback from USB serial listener indicating that application should quit and control be passed to the system bootloader.
void	quit() If the Spot application is running have it stop.
void	reinitialize() Reinitialize the world before re-running the Spot application.
abstract void	run() The Spot application code to run as defined by a subclass of Spotlet.
void	setBlinkLEDs(boolean blink) Set whether the LEDs should be blinked between retries of the application and when done.
void	setListenForBootloader(boolean monitor) Set whether or not to monitor for OTA download requests or bootloader commands over the USB connection.
void	setNumberRetries(int num) Set the number of times to retry the application after an error.
void	setTimeBetweenRetries(long time) Set the time in milliseconds to wait before retrying the application after an error.
protected void	startApp() MIDlet call to start our application.

Methods inherited from class javax.microedition.midlet.MIDlet

getAppProperty, notifyDestroyed, notifyPaused, resumeRequest

Methods inherited from class java.lang.Object

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

Constructor Detail

Spotlet

public Spotlet()

Creates a new instance of Spotlet

Method Detail

initialize

public void initialize()

Do any initialization needed by the Spot application. Can be defined by a subclass of Spotlet.

run

public abstract void run()

The Spot application code to run as defined by a subclass of Spotlet.

reinitialize

public void reinitialize()

Reinitialize the world before re-running the Spot application. Called after an error has terminated the applications run method. Can be defined by a subclass of Spotlet.

quit

public void quit()

If the Spot application is running have it stop. Can be defined by a subclass of Spotlet.

cleanup

public void cleanup()

Cleanup any resources used by the Spot application. Can be defined by a subclass of Spotlet.

getNumberRuns

public int getNumberRuns()

Return the number of times the application has been run.

Returns:

the number of times the application's run method has been called

firstRun

public boolean firstRun()

Indicate if this is the first time the application has been run.

Returns:

true if this is the first time that the application's run method has been called

getLastError

public java.lang.Throwable getLastError()

Return the last Error or Exception thrown by the application.

Returns:

the last Error or Exception thrown by the application, null if none thrown.

getNumberRetries

public int getNumberRetries()

Return the number of times to retry the application after an error. Default value is -1 which means retry forever.

Returns:

the number of times to retry the application, -1 = retry forever

setNumberRetries

public void setNumberRetries(int num)

Set the number of times to retry the application after an error.

Parameters:

num - the number of times to retry the application, -1 = retry forever

getTimeBetweenRetries

public long getTimeBetweenRetries()

Return the time in milliseconds to wait before retrying the application after an error. Default value is 0.

Returns:

the time to wait before retrying the application

setTimeBetweenRetries

public void setTimeBetweenRetries(long time)

Set the time in milliseconds to wait before retrying the application after an error.

Parameters:

time - the time in milliseconds to wait before retrying the application

setBlinkLEDs

public void setBlinkLEDs(boolean blink)

Set whether the LEDs should be blinked between retries of the application and when done. They will blink:

• green before each call to initialize() or reinitialize()
• red after any errors are thrown by initialize(), reinitialize(), run() or cleanup()
• blue if quitting because of an OTA download or bootloader command

Default action is to blink the LEDs.

Parameters:

blink - if true blink the LEDs

setListenForBootloader

public void setListenForBootloader(boolean monitor)

Set whether or not to monitor for OTA download requests or bootloader commands over the USB connection. Default action is to monitor requests.

Parameters:

monitor - if true spawn threads to listen for download/bootloader requests

getCurrentRunTime

public long getCurrentRunTime()

Return the elapsed time for the current call to the application's run method. If the run method is not running, return the time it took the last time it was called.

Returns:

the time in milliseconds since the run method was called

getLastRunTime

public long getLastRunTime()

Return the elapsed time for the previous call to the application's run method. If the run method is not running, return the time it took the last time it was called.

Returns:

the time in milliseconds since the run method was called

getTotalRunTime

public long getTotalRunTime()

Return the total time that this application has been running.

Returns:

the time in milliseconds since the Spot started running this application.

pause

public static void pause(long time)

Pause for a specified time.

Parameters:

time - the number of milliseconds to pause

prepareToExit

public void prepareToExit()

Callback from USB serial listener indicating that application should quit and control be passed to the system bootloader.

Specified by:

prepareToExit in interface com.sun.spot.util.IBootloaderListenerCallback

preFlash

public void preFlash()

Called by OTACommandServer before flashing a new application.

Specified by:

preFlash in interface com.sun.spot.peripheral.ota.IOTACommandServerListener

postFlash

public void postFlash()

Called by OTACommandServer after flashing a new application.

Specified by:

postFlash in interface com.sun.spot.peripheral.ota.IOTACommandServerListener

startApp

protected void startApp()
                 throws javax.microedition.midlet.MIDletStateChangeException

MIDlet call to start our application.

Specified by:

startApp in class javax.microedition.midlet.MIDlet

Throws:

javax.microedition.midlet.MIDletStateChangeException

pauseApp

protected void pauseApp()

This will never be called by the Squawk VM.

Specified by:

pauseApp in class javax.microedition.midlet.MIDlet

destroyApp

protected void destroyApp(boolean arg0)
                   throws javax.microedition.midlet.MIDletStateChangeException

Only called if startApp throws any exception other than MIDletStateChangeException.

Specified by:

destroyApp in class javax.microedition.midlet.MIDlet

Throws:

javax.microedition.midlet.MIDletStateChangeException