edu.nrao.sss.electronics
Class SignalPipe

java.lang.Object
  edu.nrao.sss.electronics.SignalPipe

All Implemented Interfaces:

SignalProcessor, SignalSource

public class SignalPipe
extends Object
implements SignalSource, SignalProcessor

A connector for moving a signal from one device to another.

A pipe has two ends, one for input and one for output. The input of a pipe may be either unconnected or connected to a signal source. The output may likewise be either unconnected or connected to a signal processor.

Executing a pipe is the same as executing its output processor, provided it has one. Executing a pipe with a disconnected output does nothing. Executing a pipe with a disconnected input does whatever the processor connected to its output does when it has no signal.

The connections of a pipe are normally forged in such a way that they may be unconnected and then reconnected to the same devices, or to different devices. Via the static factory methods, however, a pipe may be constructed with one of its ends welded to a device. A welded connection is permanent and may not be disconnected or connected to another device. Devices tend to create their pipes so that they are welded to themselves. Clients of these devices then connect their outputs to the inputs of other devices.

Version Info:

$Revision: 1269 $

$Date: 2008-05-05 14:39:39 -0600 (Mon, 05 May 2008) $

$Author: dharland $ (last person to modify)

Since:

2007-10-25

Author:

David M. Harland

Constructor Summary

SignalPipe()
Creates a new unnamed pipe that is not connected on either of its ends.

SignalPipe(String pipeName)
Creates a new named pipe that is not connected on either of its ends.

Method Summary

boolean	canConnectInputTo(SignalSource source) Returns true if the input of this pipe may be connected to source.
boolean	canConnectOutputTo(SignalProcessor processor) Returns true if the output of this pipe may be connected to processor.
boolean	connectInputTo(SignalSource source) Attempts to connect the input of this pipe to source and returns true if successful.
boolean	connectOutputTo(SignalProcessor processor) Attempts to connect the output of this pipe to processor and returns true if successful.
boolean	disconnectInput() Attempts to disconnect the input of this pipe and returns true if successful.
boolean	disconnectOutput() Attempts to disconnect the output of this pipe and returns true if successful.
void	execute() Executes the processor connected to the output of this pipe, if any.
void	executeFromStartOfChainUpTo(SignalProcessor firstUnexecutedDevice) Retreats upstream from this processor to the source of the stream and executes that device(s), telling it to stop execution at firstUnexecutedDevice.
void	executeUpTo(SignalProcessor firstUnexecutedDevice) Executes this device and all downstream devices up to, but not including, the firstUnexecutedDevice.
String	getName() Returns the name of this pipe.
Signal	getSignal() Returns the signal of the source connected to the input of this pipe.
static SignalPipe	makeAndWeldInputTo(SignalSource source) Creates a new pipe, welds its input to source, and returns it.
static SignalPipe	makeAndWeldOutputTo(SignalProcessor processor) Creates a new pipe, welds its output to processor, and returns it.
void	setName(String newName) Sets a new name for this pipe.

Methods inherited from class java.lang.Object

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

Constructor Detail

SignalPipe

public SignalPipe()

Creates a new unnamed pipe that is not connected on either of its ends.

SignalPipe

public SignalPipe(String pipeName)

Creates a new named pipe that is not connected on either of its ends.

Parameters:

pipeName - an optional name for this pipe. If this value is null a default name will be used in its place.

Method Detail

makeAndWeldInputTo

public static SignalPipe makeAndWeldInputTo(SignalSource source)

Creates a new pipe, welds its input to source, and returns it. If source is a pipe whose output is welded to another processor, the returned pipe will be null.

Parameters:

source - a source to be welded to the input of the returned pipe.

Returns:

a new pipe whose input is welded to source, or null if the weld could not be made.

makeAndWeldOutputTo

public static SignalPipe makeAndWeldOutputTo(SignalProcessor processor)

Creates a new pipe, welds its output to processor, and returns it. If processor is a pipe whose input is welded to another source, the returned pipe will be null.

Parameters:

processor - a processor to be welded to the output of the returned pipe.

Returns:

a new pipe whose output is welded to processor, or null if the weld could not be made.

setName

public void setName(String newName)

Sets a new name for this pipe. Clients are not required to name their pipes.

If newName is null or the empty string (""), the request to change the name will be denied and the current name will remain in place.

Parameters:

newName - the new name of this pipe.

getName

public String getName()

Returns the name of this pipe. The returned value will be either a client-specified name or a default name. It will never be null.

Returns:

the name of this pipe.

canConnectInputTo

public boolean canConnectInputTo(SignalSource source)

Returns true if the input of this pipe may be connected to source.

This method will return true if, and only if,

1. the input of this pipe is not welded to another source, and
2. source is not a pipe whose output is welded to another processor.

Parameters:

source - the device to be tested for connectability to input of this pipe.

Returns:

true if the input of this pipe may be connected to source.

connectInputTo

public boolean connectInputTo(SignalSource source)

Attempts to connect the input of this pipe to source and returns true if successful. If the attempt was unsuccessful, this pipe will be in the same state it was in just prior to the call to this method.

Parameters:

source - the source to which the input of this pipe should be connected.

Returns:

true if the attempt to connect was successful.

disconnectInput

public boolean disconnectInput()

Attempts to disconnect the input of this pipe and returns true if successful. The attempt will be unsuccessful if the input of this pipe is welded to its device. If the attempt was unsuccessful, this pipe will be in the same state it was in just prior to the call to this method.

Returns:

true if the attempt to disconnect was successful.

canConnectOutputTo

public boolean canConnectOutputTo(SignalProcessor processor)

Returns true if the output of this pipe may be connected to processor.

This method will return true if, and only if,

1. the output of this pipe is not welded to another processor, and
2. processor is not a pipe whose input is welded to another source.

Parameters:

processor - the device to be tested for connectability to the output of this pipe.

Returns:

true if the input of this pipe may be connected to source.

connectOutputTo

public boolean connectOutputTo(SignalProcessor processor)

Attempts to connect the output of this pipe to processor and returns true if successful. If the attempt was unsuccessful, this pipe will be in the same state it was in just prior to the call to this method.

Parameters:

processor - the processor to which the output of this pipe should be connected.

Returns:

true if the attempt to connect was successful.

disconnectOutput

public boolean disconnectOutput()

Attempts to disconnect the output of this pipe and returns true if successful. The attempt will be unsuccessful if the output of this pipe is welded to its device. If the attempt was unsuccessful, this pipe will be in the same state it was in just prior to the call to this method.

Returns:

true if the attempt to disconnect was successful.

getSignal

public Signal getSignal()

Returns the signal of the source connected to the input of this pipe. If nothing is connected to this pipe, or if the connected source has a null signal, null will be returned.

Specified by:

getSignal in interface SignalSource

Returns:

the signal provided by this device.

execute

public void execute()

Executes the processor connected to the output of this pipe, if any.

Specified by:

execute in interface SignalProcessor

executeUpTo

public void executeUpTo(SignalProcessor firstUnexecutedDevice)

Description copied from interface: SignalProcessor

Executes this device and all downstream devices up to, but not including, the firstUnexecutedDevice. See SignalProcessor.execute() for more information about the linking of processors.

Specified by:

executeUpTo in interface SignalProcessor

Parameters:

firstUnexecutedDevice - the first device downstream that is not to be executed. If all downstream devices should be executed you may use a null value here or call SignalProcessor.execute().

executeFromStartOfChainUpTo

public void executeFromStartOfChainUpTo(SignalProcessor firstUnexecutedDevice)

Description copied from interface: SignalProcessor

Retreats upstream from this processor to the source of the stream and executes that device(s), telling it to stop execution at firstUnexecutedDevice.

Specified by:

executeFromStartOfChainUpTo in interface SignalProcessor

Parameters:

firstUnexecutedDevice - the first device in a chain of processors that is not to be executed. If all devices should be executed you may use a null value here. The first unexecuted device should be downstream of this device.