org.instantreality.InstantIO
Class BufferedInSlot

java.lang.Object
  org.instantreality.InstantIO.Slot
      org.instantreality.InstantIO.InSlot
          org.instantreality.InstantIO.BufferedInSlot

public class BufferedInSlot
extends InSlot

InSlot that buffers values.

Usually, InSlots do not buffer values, i.e. when a new data value is written into the InSlot before the old data value has been received by the application, the old data value gets lost. This is ok under many circumstances, but sometimes it is important to get all data values (e.g. when receiving button press and release events). For this reason, the BufferedInSlot class exists.

When you create a BufferedInSlot object, you have to specify the maximum number of data values that get buffered by the BufferedInSlot. When the BufferedInSlot receives a new data value, it adds it to the buffer. When you call the pop method, the BufferedInSlot removes the oldest value from the buffer and returns it. When more values are written into the BufferedInSlot than the maximum number, the new data values overwrite the oldest data values stored in the buffer.

Besides buffering data values, BufferedInSlots do not differ from normal InSlots, they behave exactly the same way. To replace a normal InSlot by a BufferedInSlot, you just have to change the code that creates the Inslot.

Author:

Patrick Dähne

See Also:

InSlot

Nested Class Summary

Nested classes/interfaces inherited from class org.instantreality.InstantIO.InSlot

InSlot.Listener

Field Summary

Fields inherited from class org.instantreality.InstantIO.Slot

In, Out

Constructor Summary

BufferedInSlot(java.lang.Class type, int numValues)
Creates a new BufferedInSlot object.

BufferedInSlot(java.lang.Class type, java.lang.String description, int numValues)
Creates a new BufferedInSlot object.

Method Summary

boolean	empty() Returns if data is available on the BufferedInSlot.
java.lang.Object	pop() Removes the oldest data value from the buffer and returns it.
Data	popData() Removes the oldest data value from the buffer and returns it.
java.lang.Object	top() Returns the oldest data value without removing it from the buffer.
Data	topData() Returns the oldest data value without removing it from the buffer.

Methods inherited from class org.instantreality.InstantIO.InSlot

addListener, connect, disconnect, getDirection, isConnected, newData, removeListener, startInSlot, stopInSlot

Methods inherited from class org.instantreality.InstantIO.Slot

getDescription, getType

Methods inherited from class java.lang.Object

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

Constructor Detail

BufferedInSlot

public BufferedInSlot(java.lang.Class type,
                      int numValues)

Creates a new BufferedInSlot object.

The following example demonstrates how to create a BufferedInSlot that receives boolean values and buffers up to 10 data values:

 BufferedInSlot inSlot = new BufferedInSlot(Boolean.class, 10);
 

Parameters:

type - The type of data that can be written into this InSlot. InSlots can only connect to OutSlots that have the same type of data. To use basic Java types (e.g. boolean, int or float) you have to use the wrapper classes provided by Java (e.g. Boolean, Integer or Float).

numValues - The maximum number of values that are buffered by this InSlot.

BufferedInSlot

public BufferedInSlot(java.lang.Class type,
                      java.lang.String description,
                      int numValues)

Creates a new BufferedInSlot object.

The following example demonstrates how to create a BufferedInSlot that receives boolean values that represent button press events and buffers up to 10 data values:

 BufferedInSlot inSlot = new BufferedInSlot(Boolean.class, "Used to receive button press events", 10);
 

Parameters:

type - The type of data that can be written into this InSlot. InSlots can only connect to OutSlots that have the same type of data. To use basic Java types (e.g. boolean, int or float) you have to use the wrapper classes provided by Java (e.g. Boolean, Integer or Float).

description - The description of this InSlot. The description is not used by the system in any way. It primarily serves documentation purposes. Some user interfaces that allow to manage the system print the description alongside with the InSlot.

numValues - The maximum number of values that are buffered by this InSlot.

Method Detail

empty

public boolean empty()

Returns if data is available on the BufferedInSlot.

All methods that receive data values (top, topData, pop, popData) block when no data is available until data is received from an OutSlot. By using this method, you can prevent this blocking by checking if data is actually available.

The following example demonstrates how to use the empty method when you have to poll for new data values on a BufferedInSlot that receives boolean values:

 BufferedInSlot inSlot = ...;
 while (inSlot.empty() == false)
 {
   Boolean b = (Boolean) inSlot.pop();
   // do something with the boolean value
 }
 

Overrides:

empty in class InSlot

Returns:

false when data is available, true otherwise.

top

public java.lang.Object top()
                     throws java.lang.InterruptedException

Returns the oldest data value without removing it from the buffer.

This method blocks when no data is available until data is received from an OutSlot. By using the empty method you can check if data is available before calling this method.

This method just returns the data value, but not the time when the data value has been created. When you need to get a timestamp, use the topData method instead of this method.

To remove the data value from the buffer, you can call the pop or popData methods.

The following example demonstrates how to use the top method to get the oldest data value from a BufferedInSlot that receives boolean values:

 BufferedInSlot inSlot = ...;
 Boolean b = (Boolean) inSlot.top();
 // do something with the boolean value
 

Overrides:

top in class InSlot

Returns:

The oldest data value from the buffer.

Throws:

java.lang.InterruptedException - when the thread blocked in the top method got interrupted

See Also:

empty, topData, pop, popData

topData

public Data topData()
             throws java.lang.InterruptedException

Returns the oldest data value without removing it from the buffer.

This method blocks when no data is available until data is received from an OutSlot. By using the empty method you can check if data is available before calling this method.

This method returns a Data object that contains the oldest data value and the time when it has been created. When you do not need the timestamp, you can call the top method that returns the data value directly.

To remove the data value from the buffer, you can call the pop or popData methods.

The following example demonstrates how to use the topData method to get the oldest data value and its timestamp from a BufferedInSlot that receives boolean values:

 BufferedInSlot inSlot = ...;
 Data data = inSlot.topData();
 Boolean b = (Boolean) data.getValue();
 long timeStamp = data.getTimeStamp();
 // do something with the boolean value and the timestamp
 

Overrides:

topData in class InSlot

Returns:

A Data object that contains the oldest data value and the time when it has been created.

Throws:

java.lang.InterruptedException - when the thread blocked in the topData method got interrupted

See Also:

empty, top, pop, popData

pop

public java.lang.Object pop()
                     throws java.lang.InterruptedException

Removes the oldest data value from the buffer and returns it.

This method blocks when no data is available until data is received from an OutSlot. By using the empty method you can check if data is available before calling this method.

This method just returns the data value, but not the time when the data value has been created. When you need to get a timestamp, use the popData method instead of this method.

To get the data value without removing it from the InSlot, use the top or topData methods.

The following example demonstrates how to use the pop method to get and remove the oldest data value from a BufferedInSlot that receives boolean values:

 BufferedInSlot inSlot = ...;
 Boolean b = (Boolean) inSlot.pop();
 // do something with the boolean value
 

Overrides:

pop in class InSlot

Returns:

The oldest data value.

Throws:

java.lang.InterruptedException - when the thread blocked in the pop method got interrupted

See Also:

empty, popData, top, topData

popData

public Data popData()
             throws java.lang.InterruptedException

Removes the oldest data value from the buffer and returns it. This method blocks when no data is available until data is received from an OutSlot. By using the empty method you can check if data is available before calling this method.

This method returns a Data object that contains the oldest data value and the time when it has been created. When you do not need the timestamp, you can call the pop method that returns the data value directly.

The following example demonstrates how to use the popData method to get and remove the oldest data value and its timestamp from a BufferedInSlot that receives boolean values:

 BufferedInSlot inSlot = ...;
 Data data = inSlot.popData();
 Boolean b = (Boolean) data.getValue();
 long timeStamp = data.getTimeStamp();
 // do something with the boolean value and the timestamp
 

Overrides:

popData in class InSlot

Returns:

A Data object that contains the oldest data value and the time when it has been created.

Throws:

java.lang.InterruptedException - when the thread blocked in the popData method got interrupted

See Also:

empty, pop, top, topData