lejos.util
Class NXTDataLogger

java.lang.Object
  lejos.util.NXTDataLogger

All Implemented Interfaces:

Logger

public class NXTDataLogger
extends Object
implements Logger

Logger class for the NXT that supports real time and deferred (cached) data logging of the primitive datatypes.

This class communicates with lejos.pc.charting.DataLogger via Bluetooth or USB which is used by the NXT Charting Logger tool.

When instantiated, the NXTDataLogger starts out in cached mode (startCachingLog()) as default. Cache mode uses a growable ring buffer that consumes (if needed) up to all available memory during a logging run.

Hints for real-time logging efficiency:

• Try to keep your datatypes the same across writeLog() method calls to avoid the protocol overhead that is incurred when switching datatypes. For instance, every time you change between writeLog(int) and writeLog(long), a synchronization message must be sent to change the datatype on the receiver (lejos.pc.charting.DataLogger).
• Use the the writeLog() method with the smallest datatype that fits your data. Less data means better throughput overall. Note that this implementation always use 4 bytes for datatypes boolean, short, int, and float and 8 bytes for long and double.

Author:

Kirk P. Thompson

Constructor Summary

NXTDataLogger()
Default constructor establishes a data logger instance in cache mode.

Method Summary

void	finishLine() Finish the row and start a new one.
void	sendCache(DataOutputStream out, DataInputStream in) Sends the log cache.
void	sendCache(NXTConnection connection) Sends the log cache using passed NXTConnection to retrieve the data streams.
void	setColumns(LogColumn[] columnDefs) Set the data set header information for the data log and chart series.
void	startCachingLog() Sets caching (deferred) logging.
void	startRealtimeLog(DataOutputStream out, DataInputStream in) Start a realtime logging session using passed data streams.
void	startRealtimeLog(NXTConnection connection) Start a realtime logging session using passed NXTConnection to retrieve the data streams.
void	stopLogging() Stop the logging session and close down the connection and data streams.
void	writeComment(String comment) Log a text comment.
void	writeLog(boolean datapoint) Write a boolean value as an int 1 (true) or 0 (false) to the log.
void	writeLog(byte datapoint) Write a byte value to the log.
void	writeLog(double datapoint) Write an double to the log.
void	writeLog(float datapoint) Write an float to the log.
void	writeLog(int datapoint) Write an int to the log.
void	writeLog(long datapoint) Write an long to the log.
void	writeLog(short datapoint) Write a short value to the log.

Methods inherited from class java.lang.Object

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

Constructor Detail

NXTDataLogger

public NXTDataLogger()

Default constructor establishes a data logger instance in cache mode.

See Also:

startCachingLog(), startRealtimeLog(NXTConnection)

Method Detail

startRealtimeLog

public void startRealtimeLog(DataOutputStream out,
                             DataInputStream in)
                      throws IOException

Start a realtime logging session using passed data streams. The setColumns() method must be called after this method is called and before the first writeLog() method is called.

The use of this method is mutually exclusive with startCachingLog() and will reset internal state to realtime mode.

Specified by:

startRealtimeLog in interface Logger

Parameters:

out - A valid DataOutputStream

in - A valid DataInputStream

Throws:

IOException - if the data streams are not valid

See Also:

stopLogging(), startRealtimeLog(NXTConnection), setColumns(lejos.util.LogColumn[])

startRealtimeLog

public void startRealtimeLog(NXTConnection connection)
                      throws IOException

Start a realtime logging session using passed NXTConnection to retrieve the data streams. The connection must already be established. The setColumns() method must be called after this method is called and before the first writeLog() method is called.

The use of this method is mutually exclusive with startCachingLog() and will reset internal state to realtime mode.

Specified by:

startRealtimeLog in interface Logger

Parameters:

connection - A connected NXTConnection instance

Throws:

IOException - if the data streams are not valid

See Also:

stopLogging(), startRealtimeLog(DataOutputStream, DataInputStream), setColumns(lejos.util.LogColumn[])

stopLogging

public void stopLogging()

Stop the logging session and close down the connection and data streams. After this method is called, you must call one of the logging mode start methods to begin a new logging session.

Specified by:

stopLogging in interface Logger

See Also:

startRealtimeLog(NXTConnection), startCachingLog()

startCachingLog

public void startCachingLog()

Sets caching (deferred) logging. This is the default mode at instantiation. The setColumns() method must be called after this method is called and before the first writeLog() method is called.

The use of this method is mutually exclusive with the startRealtimeLog() methods and will reset internal state to caching mode.

Specified by:

startCachingLog in interface Logger

See Also:

stopLogging(), sendCache(NXTConnection), startRealtimeLog(NXTConnection)

sendCache

public void sendCache(DataOutputStream out,
                      DataInputStream in)
               throws IOException

Sends the log cache. Valid only for caching (deferred) logging using startCachingLog().

Specified by:

sendCache in interface Logger

Parameters:

out - A valid DataOutputStream

in - A valid DataInputStream

Throws:

IOException - if the data streams are not valid

IllegalStateException - if startCachingLog() has not been called

sendCache

public void sendCache(NXTConnection connection)
               throws IOException

Sends the log cache using passed NXTConnection to retrieve the data streams. The connection must already be established. Valid only for caching (deferred) logging using startCachingLog().

Specified by:

sendCache in interface Logger

Parameters:

connection - A connected NXTConnection instance

Throws:

IOException - if the data streams are not valid

IllegalStateException - if startCachingLog() has not been called

finishLine

public void finishLine()

Finish the row and start a new one.

The Column count is set by calling setColumns() and you must ensure that you call the appropriate writeLog() method the same number of times as that column count before this method is called.

Specified by:

finishLine in interface Logger

Throws:

IllegalStateException - if all the columns defined with setColumns() per row have not been logged.

See Also:

setColumns(lejos.util.LogColumn[])

writeLog

public void writeLog(boolean datapoint)

Write a boolean value as an int 1 (true) or 0 (false) to the log. In realtime logging mode, if an IOException occurs, the connection and data streams are silently closed down and no exception is thrown from this method.

Specified by:

writeLog in interface Logger

Parameters:

datapoint - The boolean value to log.

Throws:

IllegalStateException - if the column datatype for the column position this method was called for does not match the datatype that was set in setColumns(), the column position exceeds the total column count (i.e. finishLine() was not called after last column logged), or the column definitions have not been set with setColumns().

OutOfMemoryError - if in cache mode and memory is exhausted.

See Also:

setColumns(lejos.util.LogColumn[]), finishLine()

writeLog

public void writeLog(byte datapoint)

Write a byte value to the log. In realtime logging mode, if an IOException occurs, the connection and data streams are silently closed down and no exception is thrown from this method.

Specified by:

writeLog in interface Logger

Parameters:

datapoint - The byte value to log.

Throws:

IllegalStateException - if the column datatype for the column position this method was called for does not match the datatype that was set in setColumns(), the column position exceeds the total column count (i.e. finishLine() was not called after last column logged), or the column definitions have not been set with setColumns().

OutOfMemoryError - if in cache mode and memory is exhausted.

See Also:

setColumns(lejos.util.LogColumn[]), finishLine()

writeLog

public void writeLog(short datapoint)

Write a short value to the log. In realtime logging mode, if an IOException occurs, the connection and data streams are silently closed down and no exception is thrown from this method.

Specified by:

writeLog in interface Logger

Parameters:

datapoint - The short value to log.

Throws:

IllegalStateException - if the column datatype for the column position this method was called for does not match the datatype that was set in setColumns(), the column position exceeds the total column count (i.e. finishLine() was not called after last column logged), or the column definitions have not been set with setColumns().

OutOfMemoryError - if in cache mode and memory is exhausted.

See Also:

setColumns(lejos.util.LogColumn[]), finishLine()

writeLog

public void writeLog(int datapoint)

Write an int to the log. In realtime logging mode, if an IOException occurs, the connection and data streams are silently closed down and no exception is thrown from this method.

Specified by:

writeLog in interface Logger

Parameters:

datapoint - The int value to log.

Throws:

IllegalStateException - if the column datatype for the column position this method was called for does not match the datatype that was set in setColumns(), the column position exceeds the total column count (i.e. finishLine() was not called after last column logged), or the column definitions have not been set with setColumns().

See Also:

setColumns(lejos.util.LogColumn[]), finishLine()

writeLog

public void writeLog(long datapoint)

Write an long to the log. In realtime logging mode, if an IOException occurs, the connection and data streams are silently closed down and no exception is thrown from this method.

Specified by:

writeLog in interface Logger

Parameters:

datapoint - The long value to log.

Throws:

IllegalStateException - if the column datatype for the column position this method was called for does not match the datatype that was set in setColumns(), the column position exceeds the total column count (i.e. finishLine() was not called after last column logged), or the column definitions have not been set with setColumns().

See Also:

setColumns(lejos.util.LogColumn[]), finishLine()

writeLog

public void writeLog(float datapoint)

Write an float to the log. In realtime logging mode, if an IOException occurs, the connection and data streams are silently closed down and no exception is thrown from this method.

Specified by:

writeLog in interface Logger

Parameters:

datapoint - The float value to log.

Throws:

IllegalStateException - if the column datatype for the column position this method was called for does not match the datatype that was set in setColumns(), the column position exceeds the total column count (i.e. finishLine() was not called after last column logged), or the column definitions have not been set with setColumns().

See Also:

setColumns(lejos.util.LogColumn[]), finishLine()

writeLog

public void writeLog(double datapoint)

Write an double to the log. In realtime logging mode, if an IOException occurs, the connection and data streams are silently closed down and no exception is thrown from this method.

Specified by:

writeLog in interface Logger

Parameters:

datapoint - The double value to log.

Throws:

IllegalStateException - if the column datatype for the column position this method was called for does not match the datatype that was set in setColumns(), the column position exceeds the total column count (i.e. finishLine() was not called after last column logged), or the column definitions have not been set with setColumns().

See Also:

setColumns(lejos.util.LogColumn[]), finishLine()

writeComment

public void writeComment(String comment)

Log a text comment. Displayed as event marker on domain axis of NXJChartingLogger chart and after the current line in the log. Ignored in cache mode. Only one comment per line. (i.e. before finishLine() is called)

Specified by:

writeComment in interface Logger

Parameters:

comment - The comment

setColumns

public void setColumns(LogColumn[] columnDefs)

Set the data set header information for the data log and chart series. The first column in the data log is always a system timestamp (element 0) so your first writeLog() item would be column 1, element 2 is column 2, so on and so forth. The items per log row must match the number of headers you define in this method.

This method must be called after the startCachingLog() or either of the startRealtimeLog() methods is called or an IllegalStateException will be thrown in the writeLog() methods.

The number and datatype of writeLog() calls per log row must match the number of columns and the datatypes you define here. You must end each log row with finishLine() or an IllegalStateException will be thrown on the next writeLog() call. If using the NXT ChartingLogger tool, the chart will only reflect the new data sent after this call since the series are redefined.

In realtime mode, if headers are set during logging with the writeLog() methods, the log will reflect the changes from that point on. In cached mode, if headers are set during logging with the writeLog() methods, an UnsupportedOperationException is thrown.

If length of the passed array is zero or if length > 255, the method does nothing and returns immediately.

Specified by:

setColumns in interface Logger

Parameters:

columnDefs - The array of LogColumn instances to use for the data log column definitions

Throws:

UnsupportedOperationException - if setColumns is called more than once in cached mode.

See Also:

LogColumn, finishLine(), startCachingLog(), startRealtimeLog(NXTConnection)