org.instantreality.InstantIO
Class OutSlot

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

public class OutSlot
extends Slot

Allows to send data values to other software components.

For each kind of information you want to send to other software components, you have to create an OutSlot. OutSlots have a type, and a optional description that you have to specify when creating an OutSlot object.

The type specifies the Java class type of the data you want to send. 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 send 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 OutSlot. It is not used by the system, but is displayed in user interfaces used to configure the system.

Before you can actually send data values via the OutSlot, you have to connect it to one or more InSlots. You can do this manually by calling the connect method of either the OutSlot or the InSlots, but usually you add the OutSlot to a Namespace object. When you add an OutSlot to a Namespace, you have to specify a label. Namespaces automatically connect OutSlots and InSlots 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 OutSlot can be added to as many different Namespaces as necessary.

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

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

 OutSlot outSlot = new OutSlot(Boolean.class);
 Root.the().addOutSlot("Button", outSlot);
 ...
 while (loop == true)
 {
   ...
   Boolean value = ...;
   outSlot.push(value);
   ...
 }
 ...
 Root.the().removeOutSlot("Button", outSlot);
 

Sometimes it is important not only to send the data value, but also the timestamp when the data value has been created (by default, the timestamp of each data value is set to the current system time when it is pushed into the OutSlot). For this purpose, you can use a variant of the push method that takes a Data object as an argument. Data objects simply encapsulate 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 push method with Data objects:

 ...
 Boolean value = ...;
 long timeStamp = ...;
 Data data = new Data(value, timeStamp);
 outSlot.push(data);
 ...
 

Author:

Patrick Dähne

See Also:

InSlot, Namespace, Root, Data

Nested Class Summary

static interface

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

Field Summary

Fields inherited from class org.instantreality.InstantIO.Slot

In, Out

Constructor Summary

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

OutSlot(java.lang.Class type, Data defaultValue)
Creates a new OutSlot object with a type and a default value.

OutSlot(java.lang.Class type, java.lang.Object defaultValue)
Creates a new OutSlot object with a type and a default value.

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

OutSlot(java.lang.Class type, java.lang.String description, Data defaultValue)
Creates a new OutSlot object with a type, a description and a default value.

OutSlot(java.lang.Class type, java.lang.String description, java.lang.Object defaultValue)
Creates a new OutSlot object with a type, a description and a default value.

Method Summary

void	addListener(OutSlot.Listener listener) Adds a Listener to the OutSlot.
void	connect(InSlot inSlot) Connects an InSlot to this OutSlot.
void	disconnect(InSlot inSlot) Disconnects an InSlot from this OutSlot.
int	getDirection() Returns the direction of the Slot.
Data	getValue() Returns the last data value written into this OutSlot.
void	invalidateValue() Makes the current value of the OutSlot invalid.
boolean	isConnected() Returns if the OutSlot is connected to an InSlot.
void	push(Data data) Writes a new data value into the OutSlot.
void	push(java.lang.Object value) Writes a new data value into the OutSlot.
void	removeListener(OutSlot.Listener listener) Removes a Listener from the OutSlot.
protected void	startOutSlot() Calls the startOutSlot method of all listeners.
protected void	stopOutSlot() Calls the stopOutSlot method of all listeners.

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

OutSlot

public OutSlot(java.lang.Class type)

Creates a new OutSlot object with a type.

The following example demonstrates how to create an OutSlot that sends boolean values:

 OutSlot outSlot = new OutSlot(Boolean.class);
 

Parameters:

type - The type of data that can be written into this OutSlot. OutSlots can only connect to InSlots 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).

OutSlot

public OutSlot(java.lang.Class type,
               java.lang.Object defaultValue)

Creates a new OutSlot object with a type and a default value.

The default value gets returned by the getValue method when you call it before writing a value into the OutSlot.

The following example demonstrates how to create an OutSlot that sends boolean values and has a default value of "true":

 OutSlot outSlot = new OutSlot(Boolean.class, Boolean.TRUE);
 

Parameters:

type - The type of data that can be written into this OutSlot. OutSlots can only connect to InSlots 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).

defaultValue - The initial value of this OutSlot.

OutSlot

public OutSlot(java.lang.Class type,
               Data defaultValue)

Creates a new OutSlot object with a type and a default value.

The default value gets returned by the getValue method when you call it before writing a value into the OutSlot.

The following example demonstrates how to create an OutSlot that sends boolean values and has a default value of "true":

 Boolean value = Boolean.TRUE;
 long timeStamp = System.currentTimeMillis();
 Data data = new Data(value, timeStamp);
 OutSlot outSlot = new OutSlot(Boolean.class, data);
 

Parameters:

type - The type of data that can be written into this OutSlot. OutSlots can only connect to InSlots 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).

defaultValue - The initial value of this OutSlot.

OutSlot

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

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

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

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

Parameters:

type - The type of data that can be written into this OutSlot. OutSlots can only connect to InSlots 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 OutSlot. 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 OutSlot.

OutSlot

public OutSlot(java.lang.Class type,
               java.lang.String description,
               java.lang.Object defaultValue)

Creates a new OutSlot object with a type, a description and a default value.

The default value gets returned by the getValue method when you call it before writing a value into the OutSlot.

The following example demonstrates how to create an OutSlot that sends boolean values that represent button press events and has a default value of "true":

 OutSlot outSlot = new OutSlot(Boolean.class, "Used to send button press events", Boolean.TRUE);
 

Parameters:

type - The type of data that can be written into this OutSlot. OutSlots can only connect to InSlots 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 OutSlot. 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 OutSlot.

defaultValue - The initial value of this OutSlot.

OutSlot

public OutSlot(java.lang.Class type,
               java.lang.String description,
               Data defaultValue)

Creates a new OutSlot object with a type, a description and a default value.

The default value gets returned by the getValue method when you call it before writing a value into the OutSlot.

The following example demonstrates how to create an OutSlot that sends boolean values that represent button press events and has a default value of "true":

 Boolean value = Boolean.TRUE;
 long timeStamp = System.currentTimeMillis();
 Data data = new Data(value, timeStamp);
 OutSlot outSlot = new OutSlot(Boolean.class, "Used to send button press events", data);
 

Parameters:

type - The type of data that can be written into this OutSlot. OutSlots can only connect to InSlots 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 OutSlot. 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 OutSlot.

defaultValue - The initial value of this OutSlot.

Method Detail

getDirection

public final int getDirection()

Returns the direction of the Slot. For OutSlots, this is always the constant Slot.Out.

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

getValue

public Data getValue()

Returns the last data value written into this OutSlot. By using this method, you can check if a new value you want to write into the OutSlot actually differs from the one written previously. In this case, in many cases you can skip writing the new value into the OutSlot. This allows to conserve resources (especially when sending data values via the network).

In the following example we send new boolean values only when they actually differ from the value sent before:

 OutSlot outSlot = ...;
 boolean value = ...;
 if (outSlot.getValue().getValue().booleanValue() != value)
   outSlot.push(new Boolean(value));
 

Returns:

The last data value written into the OutSlot.

isConnected

public boolean isConnected()

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

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

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

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

Returns:

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

addListener

public final void addListener(OutSlot.Listener listener)

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

Listeners can be used to receive notifications when the status of an OutSlot changes, i.e. when the first InSlot connects to the OutSlot, or the last InSlot disconnects from the OutSlot. Instead of implementing the Listener interface, you can also create a descendant of the OutSlot class and override the startOutSlot and stopOutSlot methods.

Parameters:

listener - The listener.

See Also:

removeListener(org.instantreality.InstantIO.OutSlot.Listener), startOutSlot(), stopOutSlot()

removeListener

public final void removeListener(OutSlot.Listener listener)

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

Parameters:

listener - The Listener.

See Also:

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

push

public void push(java.lang.Object value)

Writes a new data value into the OutSlot. The data value is sent to all InSlots the OutSlot is currently connected to.

When using this method, all data values automatically get a timestamp that contains the current system time. When you need to specify the timestamp manually, you can use another variant of the push method that takes a Data object.

Do not modify the data value after 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 pushing them into OutSlots.

The following example demonstrates how to send boolean values via an OutSlot:

 OutSlot outSlot = ...;
 boolean value = ...;
 outSlot.push(new Boolean(value));
 

Parameters:

value - The new data value.

See Also:

push(Data)

push

public void push(Data data)

Writes a new data value into the OutSlot. The data value is sent to all InSlots the OutSlot is currently connected to.

Do not modify the data value after 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 pushing them into OutSlots.

The following example demonstrates how to send boolean values via an OutSlot:

 OutSlot outSlot = ...;
 Boolean value = ...;
 long timeStamp = ...;
 Data data = new Data(value, timeStamp);
 outSlot.push(data);
 

Parameters:

data - The new data value.

See Also:

push(java.lang.Object)

invalidateValue

public final void invalidateValue()

Makes the current value of the OutSlot invalid. The current value is the last data value written into the OutSlot. By default, the current value is invalid until the first data value is written into the OutSlot.

connect

public void connect(InSlot inSlot)

Connects an InSlot to this OutSlot. Usually, you do not connect InSlots and OutSlots 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 InSlot more than once to an OutSlot. 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 of 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
 outSlot.connect(inSlot);
 
 ...
 
 // Disconnect the OutSlot and the InSlot
 outSlot.disconnect(inSlot);
 

Parameters:

inSlot - The InSlot.

See Also:

disconnect(org.instantreality.InstantIO.InSlot)

disconnect

public void disconnect(InSlot inSlot)

Disconnects an InSlot from this OutSlot. Usually, you do not disconnect InSlots and OutSlots 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 InSlot more than once to an OutSlot. 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
 outSlot.connect(inSlot);
 
 ...
 
 // Disconnect the OutSlot and the InSlot
 outSlot.disconnect(inSlot);
 

Parameters:

inSlot - The InSlot.

See Also:

connect(org.instantreality.InstantIO.InSlot)

startOutSlot

protected void startOutSlot()

Calls the startOutSlot method of all listeners. Descendants of the OutSlot class can override this method when they need to be notified when the first InSlot connects to the OutSlot. 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.startOutSlot), otherwise the listeners do not get a notification when the first InSlot connects to the OutSlot. I.e., your implementation of the startOutSlot method should look like this:

 protected void startOutSlot()
 {
   super.startOutSlot();
   // 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:

OutSlot.Listener, OutSlot.Listener.startOutSlot(org.instantreality.InstantIO.OutSlot)

stopOutSlot

protected void stopOutSlot()

Calls the stopOutSlot method of all listeners. Descendants of the OutSlot class can override this method when they need to be notified when the last InSlot disconnects from the OutSlot. 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.stopOutSlot), otherwise the listeners do not get a notification when the last InSlot disconnects from the OutSlot. I.e., your implementation of the stopOutSlot method should look like this:

 protected void stopOutSlot()
 {
   super.stopOutSlot();
   // 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:

OutSlot.Listener, OutSlot.Listener.stopOutSlot(org.instantreality.InstantIO.OutSlot)