org.instantreality.InstantIO
Class InSlot

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

Direct Known Subclasses:

BufferedInSlot

public class InSlot
extends Slot

Allows to receive data values from other software components.

For each kind of information you want to receive from other software components, you have to create an InSlot. InSlots have a type and an optional description that you have to specify when creating an InSlot object.

The type specifies the Java class type of the data you want to receive. You cannot receive basic Java data types (boolean, int, float etc.), just objects, so you have to use the corresponding wrapper classes (Boolean, Integer, Float, etc.) when you need to receive basic Java data types.

The description simply is a human-readable string that can be used to describe more in detail the purpose of the InSlot. It is not used by the system, but is displayed in user interfaces used to configure the system.

Before you can actually receive data values from the InSlot, you have to connect it to one or more OutSlots. You can do this manually by calling the connect method of either the InSlot or the OutSlots, but usually you add the InSlot to a Namespace object. When you add an InSlot to a Namespace, you have to specify a label. Namespaces automatically connect InSlots and OutSlots contained in the Namespace that fulfill the following constraints:

1. They have the same data type,
2. and they have the same label, or there is a route defined in the Namespace that maps the OutSlot label to the InSlot label.

An InSlot can be added to as many different Namespaces as necessary.

When you do not need to receive values from the InSlot anymore, you simply disconnect it from the OutSlots by calling the disconnect method or by removing it from all Namespaces.

The following code snippet demonstrates how to receive button press events from other software components. These events are boolean values, so we create an InSlot with the type "Boolean". Then we add it under the label "Button" to the root namespace (the Root singleton) and start receiving values by using the pop method:

 InSlot inSlot = new InSlot(Boolean.class);
 Root.the().addInSlot("Button", inSlot);
 ...
 while (loop == true)
 {
   ...
   Boolean value = (Boolean) inSlot.pop();
   ...
 }
 ...
 Root.the().removeInSlot("Button", inSlot);
 

Sometimes it is important not only to receive the data value, but also the timestamp when the data value has been created. For this purpose, you can use the popData method instead of pop. This method returns a Data object that simply encapsulates a data value and a timestamp. The timestamp is a long value that contains the number of milliseconds since midnight January 1., 1970 UTC. The following code snippet demonstrates how to use the popData method:

 Data data = inSlot.popData();
 Boolean value = (Boolean) data.getValue();
 long timeStamp = data.getTimeStamp();
 

Please keep in mind that the InSlot does not buffer data values. When a new data value is received before the current data value has been read by the application, the current data value gets overwritten by the new value. Under many circumstances, this behaviour is ok, but when you need to receive all data values, you have to use a BufferedInSlot.

Author:

Patrick Dähne

See Also:

OutSlot, Namespace, Root, BufferedInSlot, Data

Nested Class Summary

static interface

InSlot.Listener Allows to receive information about the status of an InSlot.

Field Summary

Fields inherited from class org.instantreality.InstantIO.Slot

In, Out

Constructor Summary

InSlot(java.lang.Class type)
Creates a new InSlot object with a type.

InSlot(java.lang.Class type, java.lang.String description)
Creates a new InSlot object with a type and a description.

Method Summary

void	addListener(InSlot.Listener listener) Adds a Listener to the InSlot.
void	connect(OutSlot outSlot) Connects an OutSlot to this InSlot.
void	disconnect(OutSlot outSlot) Disconnects an OutSlot from this InSlot.
boolean	empty() Returns if data is available on the InSlot.
int	getDirection() Returns the direction of the Slot.
boolean	isConnected() Returns if the InSlot is connected to an OutSlot.
protected void	newData() Calls the newData method of all listeners.
java.lang.Object	pop() Removes the current data value from the Inslot and returns it.
Data	popData() Removes the current data value from the Inslot and returns it.
void	removeListener(InSlot.Listener listener) Removes a Listener from the InSlot.
protected void	startInSlot() Calls the startInSlot method of all listeners.
protected void	stopInSlot() Calls the stopInSlot method of all listeners.
java.lang.Object	top() Returns the current data value without removing it from the InSlot.
Data	topData() Returns the current data value without removing it from the InSlot.

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

InSlot

public InSlot(java.lang.Class type)

Creates a new InSlot object with a type.

The following example demonstrates how to create an InSlot that receives boolean values:

 InSlot inSlot = new InSlot(Boolean.class);
 

Parameters:

type - The type of data that can be received from 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).

InSlot

public InSlot(java.lang.Class type,
              java.lang.String description)

Creates a new InSlot object with a type and a description.

The following example demonstrates how to create an InSlot that receives boolean values that represent button press events:

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

Parameters:

type - The type of data that can be received from 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.

Method Detail

getDirection

public final int getDirection()

Returns the direction of the Slot. For InSlots, this is always the constant Slot.In.

The following example demonstrates how to determine if a given Slot is an InSlot or an OutSlot:

 Slot slot = ...;
 switch (slot.getDirection())
 {
 case Slot.In:
   // We have an InSlot
   break;
 case Slot.Out:
   // We have an OutSlot
   break;
 }
 

Specified by:

getDirection in class Slot

Returns:

The direction

isConnected

public boolean isConnected()

Returns if the InSlot is connected to an OutSlot. When an InSlot is not connected to an OutSlot, it is not necessary to receive values from it. This information can be used to improve performance of applications.

Instead of using this method, you can also implement a the InSlot.Listener interface and add an instance of this interface to the InSlot by using the addListener method.

The following example demonstrates how to check if an InSlot is connected to any OutSlot:

 InSlot inSlot = ...;
 if (inSlot.isConnected() == true)
 {
   // The inslot is connected to at least one outslot
 }
 else
 {
   // The inslot is not connected to any outslot
 }
 

Returns:

true when the InSlot is connected to an OutSlot, false otherwise.

addListener

public final void addListener(InSlot.Listener listener)

Adds a Listener to the InSlot. After calling this methods, the listener receives status information from the InSlot.

Listeners can be used to receive notifications when the status of an InSlot changes, i.e. when the first OutSlot connects to the InSlot, the last OutSlot disconnects from the InSlot, or new data is available on the InSlot. Instead of implementing the Listener interface, you can also create a descendant of the InSlot class and override the startInSlot, stopInSlot and newData methods.

Parameters:

listener - The listener.

See Also:

removeListener(org.instantreality.InstantIO.InSlot.Listener), startInSlot(), stopInSlot(), newData()

removeListener

public final void removeListener(InSlot.Listener listener)

Removes a Listener from the InSlot. After calling this method, the listener does not receive status notifications any more.

Parameters:

listener - The Listener.

See Also:

addListener(org.instantreality.InstantIO.InSlot.Listener)

empty

public boolean empty()

Returns if data is available on the InSlot.

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 an InSlot that receives boolean values:

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

Returns:

false when data is available, true otherwise.

top

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

Returns the current data value without removing it from the InSlot.

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 InSlot, you can call the pop or popData methods.

Do not modify the data value you receive when calling this method, because data values do not get copied, instead all InSlots receive a reference to the same data value! The wrapper classes for basic Java data types as well as the String class and most data types defined in this package are constant, i.e. they cannot be changed after creating them, which automatically ensures the correct behaviour when receiving them from InSlots.

The following example demonstrates how to use the top method to get the current data value from an InSlot that receives boolean values:

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

Returns:

The current data value.

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 current data value without removing it from the InSlot.

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 objects that contains the current 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 InSlot, you can call the pop or popData methods.

Do not modify the data value you receive when calling this method, because data values do not get copied, instead all InSlots receive a reference to the same data value! The wrapper classes for basic Java data types as well as the String class and most data types defined in this package are constant, i.e. they cannot be changed after creating them, which automatically ensures the correct behaviour when receiving them from InSlots.

The following example demonstrates how to use the topData method to get the current data value and its timestamp from an InSlot that receives boolean values:

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

Returns:

A Data object that contains the current 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 current data value from the Inslot 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.

Do not modify the data value you receive when calling this method, because data values do not get copied, instead all InSlots receive a reference to the same data value! The wrapper classes for basic Java data types as well as the String class and most data types defined in this package are constant, i.e. they cannot be changed after creating them, which automatically ensures the correct behaviour when receiving them from InSlots.

The following example demonstrates how to use the pop method to get and remove the current data value from an InSlot that receives boolean values:

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

Returns:

The current 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 current data value from the Inslot 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 objects that contains the current 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.

Do not modify the data value you receive when calling this method, because data values do not get copied, instead all InSlots receive a reference to the same data value! The wrapper classes for basic Java data types as well as the String class and most data types defined in this package are constant, i.e. they cannot be changed after creating them, which automatically ensures the correct behaviour when receiving them from InSlots.

The following example demonstrates how to use the popData method to get and remove the current data value and its timestamp from an InSlot that receives boolean values:

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

Returns:

A Data object that contains the current 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

connect

public void connect(OutSlot outSlot)

Connects an OutSlot to this InSlot. Usually, you do not connect OutSlots and InSlots manually. They get connected automatically when you add them to a Namespace. This method just exists for rare special circumstances where it might be helpful to connect slots manually.

It is only possible to connect OutSlots and InSlots that have the same data type. When they to not have the same data type, the connect method silently fails.

It is possible to add the same OutSlot more than once to an InSlot. Nevertheless, just one connection is created. For each call to the connect method, there has to be a corresponding call to the disconnect method. The slots do not get disconnected until the last call to the disconnect method.

The following example demonstrates how to create a boolean OutSlot and a boolean InSlot, how to connect them, and how to disconnect them later on:

 OutSlot outSlot = new OutSlot(Boolean.class);
 InSlot inSlot = new InSlot(Boolean.class);
 
 // Connect the OutSlot and the InSlot
 inSlot.connect(outSlot);
 
 ...
 
 // Disconnect the OutSlot and the InSlot
 inSlot.disconnect(outSlot);
 

Parameters:

outSlot - The OutSlot.

See Also:

disconnect(org.instantreality.InstantIO.OutSlot)

disconnect

public void disconnect(OutSlot outSlot)

Disconnects an OutSlot from this InSlot. Usually, you do not disconnect OutSlots and InSlots manually. They get disconnected automatically when you remove them from a Namespace. This method just exists for rare special circumstances where it might be helpful to disconnect slots manually.

It is possible to add the same OutSlot more than once to an InSlot. Nevertheless, just one connection is created. For each call to the connect method, there has to be a corresponding call to the disconnect method. The slots do not get disconnected until the last call to the disconnect method.

When you try to disconnect slots that are actually not connected, the disconnect method silently fails.

The following example demonstrates how to create a boolean OutSlot and a boolean InSlot, how to connect them, and how to disconnect them later on:

 OutSlot outSlot = new OutSlot(Boolean.class);
 InSlot inSlot = new InSlot(Boolean.class);
 
 // Connect the OutSlot and the InSlot
 inSlot.connect(outSlot);
 
 ...
 
 // Disconnect the OutSlot and the InSlot
 inSlot.disconnect(outSlot);
 

Parameters:

outSlot - The OutSlot.

See Also:

connect(org.instantreality.InstantIO.OutSlot)

startInSlot

protected void startInSlot()

Calls the startInSlot method of all listeners. Descendants of the InSlot class can override this method when they need to be notified when the first OutSlot connects to the InSlot. This method should not block, and it should not perform lengthy calculations. It is just meant to make a short notification.

Important: Descendants that override this method must call the original method (via super.startInSlot), otherwise the listeners do not get a notification when the first OutSlot connects to the InSlot. I.e., your implementation of the startInSlot method should look like this:

 protected void startInSlot()
 {
   super.startInSlot();
   // Add your code here
 }
 

Also keep in mind that this method does not get called by the main thread of your application, but from other threads created in the device management system. For this reason, you have to ensure that your implementation of this method is thread-safe!

See Also:

InSlot.Listener, InSlot.Listener.startInSlot(org.instantreality.InstantIO.InSlot)

stopInSlot

protected void stopInSlot()

Calls the stopInSlot method of all listeners. Descendants of the InSlot class can override this method when they need to be notified when the last OutSlot disconnects from the InSlot. This method should not block, and it should not perform lengthy calculations. It is just meant to make a short notification.

Important: Descendants that override this method must call the original method (via super.stopInSlot), otherwise the listeners do not get a notification when the last OutSlot disconnects from the InSlot. I.e., your implementation of the stopInSlot method should look like this:

 protected void stopInSlot()
 {
   super.stopInSlot();
   // Add your code here
 }
 

Also keep in mind that this method does not get called by the main thread of your application, but from other threads created in the device management system. For this reason, you have to ensure that your implementation of this method is thread-safe!

See Also:

InSlot.Listener, InSlot.Listener.stopInSlot(org.instantreality.InstantIO.InSlot)

newData

protected void newData()

Calls the newData method of all listeners. Descendants of the InSlot class can override this method when they need to be notified when new data is available for receival. This method should not block, and it should not perform lengthy calculations. It is just meant to perform a short notification.

Important: Descendants that override this method must call the original method (via super.newData), otherwise the listeners do not get a notification when new data is available. I.e., your implementation of the newData method should look like this:

 protected void newData()
 {
   super.newData();
   // Add your code here
 }
 

Also keep in mind that this method does not get called by the main thread of your application, but from other threads created in the device management system. For this reason, you have to ensure that your implementation of this method is thread-safe!

See Also:

InSlot.Listener, InSlot.Listener.newData(org.instantreality.InstantIO.InSlot)