lejos.util
Interface Logger

All Known Implementing Classes:

NXTDataLogger

public interface Logger

Defines the [minimum] required functionality for a data logger implementation.

Author:

Kirk P. Thompson

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 to the data log.
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.

Method Detail

startRealtimeLog

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.

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

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.

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[])

startCachingLog

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.

See Also:

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

sendCache

void sendCache(DataOutputStream out,
               DataInputStream in)
               throws IOException

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

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

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().

Parameters:

connection - A connected NXTConnection instance

Throws:

IOException - if the data streams are not valid

IllegalStateException - if startCachingLog() has not been called

setColumns

void setColumns(LogColumn[] columnDefs)
                throws IllegalArgumentException

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.

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.

IllegalArgumentException

See Also:

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

writeComment

void writeComment(String comment)

Log a text comment to the data log. Ignored in cache mode. Only one comment per line. (i.e. before finishLine() is called)

Parameters:

comment - The comment

writeLog

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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()

finishLine

void finishLine()
                throws IllegalStateException

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.

Throws:

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

See Also:

setColumns(lejos.util.LogColumn[])

stopLogging

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.

See Also:

startRealtimeLog(NXTConnection), startCachingLog()