Package com.amalgamasimulation.discreterate

Class Conveyor<T>

java.lang.Object

com.amalgamasimulation.discreterate.FlowElement<T>

com.amalgamasimulation.discreterate.Conveyor<T>

Type Parameters:

T - type (class or interface) whose instances represent materials

All Implemented Interfaces:

IAbstractConveyor<T>

public final class Conveyor<T>
extends FlowElement<T>
implements IAbstractConveyor<T>

A Conveyor is a flow element that transports material from one point in space to another point at a given speed.

Multiple inflow connections are supported. At most one outflow connection can be specified for a Conveyor.

The physical path of material transportation inside the Conveyor is represented by an instance of a Polyline.

A Conveyor is composed of several parts called 'conveyor segments' (see ConveyorSegment. Multiple inflow connections are supported, each inflow connection delivers material to the starting point of some conveyor segment.

Material is delivered by a conveyor segment in a FIFO fashion: the first portion of a material to enter the segment of a Conveyor will be the first portion to be exported from that segment.

The delivery of material from entry to exit is not instantaneous. After material enters a Conveyor, it will take some time to deliver it to the Conveyor's output. This delivery duration (i.e. time required to deliver the material) depends on the 'logical length' of the path of material inside the Conveyor and the speed at which material is being transported within the Conveyor. The logical length is measured in so-called 'logical pixels'. A 'logical pixel' is a measure of distance, and its correspondence to some 'real' measurement units (like meters, inches, etc.) is arbitrary, lies beyond the realm of a Conveyor and is not specified explicitly for a Conveyor. Note that the 'speed' of the Conveyor is also measured in 'logical pixels' per unit of model time.

The Conveyor handles a situation when it can supply material at a higher rate than the downstream flow element can accept. In this case, its Conveyor.DownstreamInflowRateShortagePolicy is applied. The policy is only set in the constructor and cannot be changed later.

Author:

Alexander Morozov

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Conveyor.Builder<T>	Helper class to create a Conveyor instance.
static enum	Conveyor.DownstreamInflowRateShortagePolicy	Defines the behavior of a Conveyor when the current rate of its currently exported ConveyorRateRecord exceeds the rate at which material can be imported by the downstream FlowElement.
static interface	Conveyor.MaxSpeedBuilder<T>	Helper interface to build a Conveyor instance.
static interface	Conveyor.PerformanceBuilder<T>	Helper interface to build a Conveyor instance.
static interface	Conveyor.PolicyBuilder<T>	Helper interface to build a Conveyor instance.
static interface	Conveyor.PolylineBuilder<T>	Helper interface to build a Conveyor instance.

Method Summary

Modifier and Type	Method	Description
void	addEmptyHandler(Consumer<Conveyor<T>> handler)	Adds an action that will be executed every time this Conveyor becomes empty.
void	addInflowRateChangedHandler(BiConsumer<Conveyor<T>,FlowConnection<T>> handler)	Adds an action that will be executed every time the inflow rate changes.
void	addOutflowRateChangedHandler(Consumer<Conveyor<T>> handler)	Adds an action that will be executed every time the outflow rate changes.
void	addSpeedChangedHandler(Consumer<Conveyor<T>> handler)	Adds an action that will be executed every time the speed changes.
static <T> Conveyor.PolylineBuilder<T>	builder(FlowEnvironment<T> flowEnvironment)	Returns a builder object to create a new instance of a Conveyor.
void	connectInputFlowWithLogicalOffset(FlowElement<T> sourceFlowElement, double logicalOffset)	Connects the sourceFlowElement (as a source of material) to this Conveyor.
void	connectInputFlowWithRelativeOffset(FlowElement<T> sourceFlowElement, double relativeOffset)	Connects the sourceFlowElement (as a source of material) to this Conveyor.
FlowConnection<T>	connectToElement(FlowElement<T> dest)	Connects the output of this flow element to the input of the dest flow element.
double	getContentsAmount()	Returns the total quantity of all materials inside this flow element.
double	getContentsAmount(T material)	Returns the current quantity of the specified material inside this flow element.
Accumulator<T>	getContentsDescriptor()	Returns all materials contained inside this flow element as an instance of Accumulator.
double	getInflowRate()	Returns the current flow rate of all materials at the input of this flow element.
Accumulator<T>	getInflowRateDescriptor()	Returns an Accumulator instance that describes the flow rate at the input of this flow element.
double	getLogicalLength()	Returns the length of this Conveyor in logical pixels.
double	getLogicalOffsetForConnection(FlowConnection<T> inflowConnection)	Returns the logical offset of the input inflowConnection.
double	getMaxSpeed()	Returns the max speed of material transportation inside this Conveyor.
double	getOutflowRate()	Returns the current flow rate at the output of this flow element.
Accumulator<T>	getOutflowRateDescriptor()	Returns an Accumulator instance that describes the flow rate at the output of this flow element.
Accumulator<T>	getOutflowRateProportions(FlowConnection<T> outflowConnection)	Returns an Accumulator instance that contains flow rate proportions of materials exported through the outflowConnection outflow connection.
double	getPerformance()	Returns the internal flow rate limit of this Conveyor.
Polyline	getPolyline()	Returns the Polyline that describes the physical layout of this Conveyor.
Collection<ConveyorRateRecord<T>>	getRateRecords()	Returns a Collection of ConveyorRateRecord instances that represent the material mix portions on this Conveyor.
Conveyor.DownstreamInflowRateShortagePolicy	getRateShortagePolicy()	Returns the Conveyor.DownstreamInflowRateShortagePolicy of this Conveyor.
double	getRelativeOffsetForConnection(FlowConnection<T> inflowConnection)	Returns the relative offset of the input inflowConnection.
double	getSpeed()	Returns the current speed of material transportation inside this Conveyor.
double	getTotalInflowAmount()	Returns the total amount of all materials that have entered this flow element.
double	getTotalInflowAmount(T element)	Returns the total amount of the specified material that has entered this flow element.
Accumulator<T>	getTotalInflowDescriptor()	Returns an Accumulator instance that contains the total quantity of each material that has entered this flow element.
double	getTotalOutflowAmount()	Returns the total quantity of materials that have left this flow element.
double	getTotalOutflowAmount(T element)	Returns the total quantity of the specified material that has left this flow element.
Accumulator<T>	getTotalOutflowDescriptor()	Returns an Accumulator instance that holds the total amounts of each material that has left this flow element.
boolean	isStopped()	Indicates that this Conveyor is stopped.
void	removeEmptyHandler(Consumer<Conveyor<T>> handler)	Removes a previously added empty Conveyor action.
void	removeInflowRateChangedHandler(BiConsumer<Conveyor<T>,FlowConnection<T>> handler)	Removes the previously added inflow rate change handler.
void	removeOutflowRateChangedHandler(Consumer<Conveyor<T>> handler)	Removes the previously added outflow rate change handler.
void	removeSpeedChangedHandler(Consumer<Conveyor<T>> handler)	Removes the previously added speed change handler.
void	setSpeed(double speed)	Sets the new current speed of material transportation inside this Conveyor.
void	startConveyor()	Starts this Conveyor.
void	stopConveyor()	Stops this Conveyor.

Methods inherited from class com.amalgamasimulation.discreterate.FlowElement

addInflowElementConnectedHandler, addInflowElementDisconnectedHandler, addOutflowElementConnectedHandler, addOutflowElementDisconnectedHandler, disconnectFrom, getFlowEnvironment, getInflowConnections, getName, getOutflowConnections, inflowConnectionExists, isConnectedWith, outflowConnectionExists, removeInflowElementConnectedHandler, removeInflowElementDisconnectedHandler, removeOutflowElementConnectedHandler, removeOutflowElementDisconnectedHandler, toString

Methods inherited from class java.lang.Object

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

Method Details

builder

public static <T> Conveyor.PolylineBuilder<T> builder(FlowEnvironment<T> flowEnvironment)

Returns a builder object to create a new instance of a Conveyor.

Parameters:

flowEnvironment - FlowEnvironment which a new Conveyor instance will belong to

Returns:

new Conveyor builder object

getLogicalLength

public double getLogicalLength()

Returns the length of this Conveyor in logical pixels.

Specified by:

getLogicalLength in interface IAbstractConveyor<T>

Returns:

length of this Conveyor

connectInputFlowWithRelativeOffset

public void connectInputFlowWithRelativeOffset(FlowElement<T> sourceFlowElement,
 double relativeOffset)

Connects the sourceFlowElement (as a source of material) to this Conveyor.

The 'connection point', i.e. the exact location along the Conveyor where the material coming from the sourceFlowElement will be accepted by the Conveyor is set by relativeOffset (a number between 0 and 1).

This method can only be called before the Conveyor's FlowEnvironment has been initialized.

Specified by:

connectInputFlowWithRelativeOffset in interface IAbstractConveyor<T>

Parameters:

sourceFlowElement - flow element that acts as a source of material

relativeOffset - a number in the half-open interval [0..1) (0 - allowed, 1 - not allowed) that defines the point of incoming connection, where 0 means 'the beginning of the Conveyor'

Throws:

IllegalStateException - if the FlowEnvironment of this Conveyor has already been initialized

IllegalArgumentException - if relativeOffset is not in the half-open interval [0..1)

See Also:

• connectInputFlowWithLogicalOffset(FlowElement, double)
• getRelativeOffsetForConnection(FlowConnection)

connectInputFlowWithLogicalOffset

public void connectInputFlowWithLogicalOffset(FlowElement<T> sourceFlowElement,
 double logicalOffset)

Connects the sourceFlowElement (as a source of material) to this Conveyor.

The 'connection point', i.e. the exact location along the Conveyor where the material coming from the sourceFlowElement will be accepted by the Conveyor is set by logicalOffset (a number between 0 and the length of the Conveyor).

This method can only be called before the Conveyor's FlowEnvironment has been initialized.

Specified by:

connectInputFlowWithLogicalOffset in interface IAbstractConveyor<T>

Parameters:

sourceFlowElement - flow element that acts as a source of material

logicalOffset - a number in the half-open interval [0..length of the Conveyor) (0 - allowed, 'length of the Conveyor' - not allowed), where 0 means 'the beginning of the Conveyor'

Throws:

IllegalStateException - if the FlowEnvironment of this Conveyor has already been initialized

IllegalArgumentException - if logicalOffset is not in the half-open interval [0..length of the Conveyor)

See Also:

• connectInputFlowWithRelativeOffset(FlowElement, double)

getPolyline

public Polyline getPolyline()

Returns the Polyline that describes the physical layout of this Conveyor.

Specified by:

getPolyline in interface IAbstractConveyor<T>

Returns:

Polyline

setSpeed

public void setSpeed(double speed)

Sets the new current speed of material transportation inside this Conveyor.

Specified by:

setSpeed in interface IAbstractConveyor<T>

Parameters:

speed - new current speed of this Conveyor

getMaxSpeed

public double getMaxSpeed()

Returns the max speed of material transportation inside this Conveyor.

The max speed is only set upon the creation of a Conveyor and cannot be changed later.

Specified by:

getMaxSpeed in interface IAbstractConveyor<T>

Returns:

max speed of this Conveyor

See Also:

• getSpeed()
• builder(FlowEnvironment)

getSpeed

public double getSpeed()

Returns the current speed of material transportation inside this Conveyor.

The speed of material transportation is the same along the whole length of a Conveyor. However, the rate of material flow inside a Conveyor may be different in its different inner points.

Specified by:

getSpeed in interface IAbstractConveyor<T>

Returns:

current speed of this Conveyor

See Also:

• getMaxSpeed()
• setSpeed(double)
• getRateRecords()
• getPerformance()

getPerformance

public double getPerformance()

Returns the internal flow rate limit of this Conveyor.

Specified by:

getPerformance in interface IAbstractConveyor<T>

Returns:

max flow rate of material inside this Conveyor

getRelativeOffsetForConnection

public double getRelativeOffsetForConnection(FlowConnection<T> inflowConnection)

Returns the relative offset of the input inflowConnection.

'Relative offset' denotes the location along the Conveyor where the material coming from the inflowConnection will be accepted by the Conveyor. Relative offset is a number between 0 and 1, where 0 means 'the beginning of the Conveyor'.

Specified by:

getRelativeOffsetForConnection in interface IAbstractConveyor<T>

Parameters:

inflowConnection - input flow connection

Returns:

relative offset of the input inflowConnection (a value between 0 and 1)

Throws:

IllegalArgumentException - if inflowConnection is not related to this flow element

See Also:

• getLogicalOffsetForConnection(FlowConnection)
• connectInputFlowWithRelativeOffset(FlowElement, double)

getLogicalOffsetForConnection

public double getLogicalOffsetForConnection(FlowConnection<T> inflowConnection)

Returns the logical offset of the input inflowConnection.

'Logical offset' denotes the location along the Conveyor where the material coming from the inflowConnection will be accepted by the Conveyor. Logical offset is a number between 0 and 'Conveyor's length', where 0 means 'the beginning of the Conveyor'.

Specified by:

getLogicalOffsetForConnection in interface IAbstractConveyor<T>

Parameters:

inflowConnection - input flow connection

Returns:

logical offset of the input inflowConnection (a value between 0 and the length of the Conveyor)

Throws:

IllegalArgumentException - if inflowConnection is not related to this flow element

See Also:

• getRelativeOffsetForConnection(FlowConnection)
• connectInputFlowWithLogicalOffset(FlowElement, double)

stopConveyor

public void stopConveyor()

Stops this Conveyor. This method is idempotent.

When the Conveyor is stopped, all material inside the Conveyor stops moving. The current rate at any point of the Conveyor becomes 0. The current inflow and outflow rates are also set to 0. All material inside a stopped Conveyor remains at its place.

If this method is called when the effective speed of the Conveyor is already 0 due to its inability to export materials (for instance, the downstream flow element is full, etc.), then a subsequent call to startConveyor() will be required to restart the Conveyor.

Specified by:

stopConveyor in interface IAbstractConveyor<T>

See Also:

• startConveyor()

startConveyor

public void startConveyor()

Starts this Conveyor. This method is idempotent.

Specified by:

startConveyor in interface IAbstractConveyor<T>

See Also:

• stopConveyor()

isStopped

public boolean isStopped()

Indicates that this Conveyor is stopped.

Specified by:

isStopped in interface IAbstractConveyor<T>

Returns:

true if the Conveyor is stopped, false otherwise

getRateShortagePolicy

public Conveyor.DownstreamInflowRateShortagePolicy getRateShortagePolicy()

Returns the Conveyor.DownstreamInflowRateShortagePolicy of this Conveyor.

Specified by:

getRateShortagePolicy in interface IAbstractConveyor<T>

Returns:

Conveyor.DownstreamInflowRateShortagePolicy of this Conveyor

getRateRecords

public Collection<ConveyorRateRecord<T>> getRateRecords()

Returns a Collection of ConveyorRateRecord instances that represent the material mix portions on this Conveyor. The order of elements in the returned Collection instance is unspecified.

Specified by:

getRateRecords in interface IAbstractConveyor<T>

Returns:

Collection of Conveyor's ConveyorRateRecords

addEmptyHandler

public void addEmptyHandler(Consumer<Conveyor<T>> handler)

Adds an action that will be executed every time this Conveyor becomes empty.

Parameters:

handler - action that will be executed every time this Conveyor becomes empty

See Also:

• removeEmptyHandler(Consumer)

removeEmptyHandler

public void removeEmptyHandler(Consumer<Conveyor<T>> handler)

Removes a previously added empty Conveyor action.

Parameters:

handler - an empty Conveyor action added by the addEmptyHandler(Consumer) method

addInflowRateChangedHandler

public void addInflowRateChangedHandler(BiConsumer<Conveyor<T>,FlowConnection<T>> handler)

Adds an action that will be executed every time the inflow rate changes.

BiConsumer has two parameters:
- Сonveyor
- FlowConnection - input connection in which the rate has changed

Parameters:

handler - action that will be executed every time the inflow rate changes

See Also:

• removeInflowRateChangedHandler(BiConsumer)

removeInflowRateChangedHandler

public void removeInflowRateChangedHandler(BiConsumer<Conveyor<T>,FlowConnection<T>> handler)

Removes the previously added inflow rate change handler.

Parameters:

handler - previously added inflow rate change handler

See Also:

• addInflowRateChangedHandler(BiConsumer)

addOutflowRateChangedHandler

public void addOutflowRateChangedHandler(Consumer<Conveyor<T>> handler)

Adds an action that will be executed every time the outflow rate changes.

Parameters:

handler - action that will be executed every time the outflow rate changes

See Also:

• removeOutflowRateChangedHandler(Consumer)

removeOutflowRateChangedHandler

public void removeOutflowRateChangedHandler(Consumer<Conveyor<T>> handler)

Removes the previously added outflow rate change handler.

Parameters:

handler - previously added outflow rate change handler

See Also:

• addOutflowRateChangedHandler(Consumer)

connectToElement

public FlowConnection<T> connectToElement(FlowElement<T> dest)

Description copied from class: FlowElement

Connects the output of this flow element to the input of the dest flow element.

Overrides:

connectToElement in class FlowElement<T>

Parameters:

dest - flow element to connect to

Returns:

a new FlowConnection, with this flow element as its source and dest flow element as its destination

See Also:

• FlowElement.disconnectFrom(element)

getContentsAmount

public double getContentsAmount()

Description copied from class: FlowElement

Returns the total quantity of all materials inside this flow element.

Specified by:

getContentsAmount in class FlowElement<T>

Returns:

current sum of all material quantities inside this flow element

See Also:

• FlowElement.getContentsAmount(material)
• FlowElement.getContentsDescriptor()

getContentsAmount

public double getContentsAmount(T material)

Description copied from class: FlowElement

Returns the current quantity of the specified material inside this flow element.

Specified by:

getContentsAmount in class FlowElement<T>

Parameters:

material - material

Returns:

current quantity of the specified material inside this flow element

See Also:

• FlowElement.getContentsAmount()
• FlowElement.getContentsDescriptor()

getContentsDescriptor

public Accumulator<T> getContentsDescriptor()

Description copied from class: FlowElement

Returns all materials contained inside this flow element as an instance of Accumulator.

Each element of the Accumulator matches the amount of the corresponding material inside this flow element. The sum of amounts of materials in the Accumulator instance is equal to the value returned by the FlowElement.getContentsAmount() method.

Specified by:

getContentsDescriptor in class FlowElement<T>

Returns:

Accumulator containing all materials inside the flow element

See Also:

• FlowElement.getContentsAmount()
• FlowElement.getContentsAmount(material)

getInflowRate

public double getInflowRate()

Description copied from class: FlowElement

Returns the current flow rate of all materials at the input of this flow element.

Specified by:

getInflowRate in class FlowElement<T>

Returns:

current flow rate of all materials at this flow element's input

See Also:

• FlowElement.getInflowRateDescriptor()

getInflowRateDescriptor

public Accumulator<T> getInflowRateDescriptor()

Description copied from class: FlowElement

Returns an Accumulator instance that describes the flow rate at the input of this flow element.

The returned Accumulator instance contains the respective rates of all materials currently entering the flow element. The sum of values in the Accumulator is equal to 1.

Specified by:

getInflowRateDescriptor in class FlowElement<T>

Returns:

descriptor of the current inflow rate

See Also:

• FlowElement.getInflowRate()

getOutflowRate

public double getOutflowRate()

Description copied from class: FlowElement

Returns the current flow rate at the output of this flow element.

Specified by:

getOutflowRate in class FlowElement<T>

Returns:

current flow rate at the output of this flow element

See Also:

• FlowElement.getOutflowRateDescriptor()

getOutflowRateDescriptor

public Accumulator<T> getOutflowRateDescriptor()

Description copied from class: FlowElement

Returns an Accumulator instance that describes the flow rate at the output of this flow element.

The returned Accumulator instance contains the respective rates of all materials currently leaving the flow element. The sum of values in the Accumulator is equal to 1.

Specified by:

getOutflowRateDescriptor in class FlowElement<T>

Returns:

descriptor of the current outflow rate

See Also:

• FlowElement.getOutflowRate()

getOutflowRateProportions

public Accumulator<T> getOutflowRateProportions(FlowConnection<T> outflowConnection)

Description copied from class: FlowElement

Returns an Accumulator instance that contains flow rate proportions of materials exported through the outflowConnection outflow connection.

Each element of the returned Accumulator corresponds to a material in the current material flow of outflowConnection. The value of each element in the Accumulator is the ratio of the rate of that material's partial flow to the overall flow rate of outflowConnection. The sum of values in the Accumulator is equal to 1.

Specified by:

getOutflowRateProportions in class FlowElement<T>

Parameters:

outflowConnection - an outflow connection

Returns:

material proportions in the outflow connection

getTotalInflowAmount

public double getTotalInflowAmount()

Description copied from class: FlowElement

Returns the total amount of all materials that have entered this flow element.

Specified by:

getTotalInflowAmount in class FlowElement<T>

Returns:

total amount of all arrived materials

getTotalInflowAmount

public double getTotalInflowAmount(T element)

Description copied from class: FlowElement

Returns the total amount of the specified material that has entered this flow element.

Specified by:

getTotalInflowAmount in class FlowElement<T>

Parameters:

element - material

Returns:

total amount of the specified material that has arrived to this flow element

See Also:

• FlowElement.getTotalInflowAmount()
• FlowElement.getTotalInflowDescriptor()

getTotalInflowDescriptor

public Accumulator<T> getTotalInflowDescriptor()

Description copied from class: FlowElement

Returns an Accumulator instance that contains the total quantity of each material that has entered this flow element.

The values of each element in the returned Accumulator match the quantities of the respective materials that have entered the flow element. The sum of values in the Accumulator is equal to the value returned by the FlowElement.getTotalInflowAmount() method.

Specified by:

getTotalInflowDescriptor in class FlowElement<T>

Returns:

Accumulator containing total amounts of materials that have entered this flow element

See Also:

• FlowElement.getTotalInflowAmount()
• FlowElement.getTotalInflowAmount(material)

getTotalOutflowAmount

public double getTotalOutflowAmount()

Description copied from class: FlowElement

Returns the total quantity of materials that have left this flow element.

Specified by:

getTotalOutflowAmount in class FlowElement<T>

Returns:

total quantity of exported materials

See Also:

• FlowElement.getTotalOutflowAmount(material)
• FlowElement.getTotalOutflowDescriptor()

getTotalOutflowAmount

public double getTotalOutflowAmount(T element)

Description copied from class: FlowElement

Returns the total quantity of the specified material that has left this flow element.

Specified by:

getTotalOutflowAmount in class FlowElement<T>

Parameters:

element - material

Returns:

total quantity of the specified material that has left this flow element

See Also:

• FlowElement.getTotalOutflowAmount()
• FlowElement.getTotalOutflowDescriptor()

getTotalOutflowDescriptor

public Accumulator<T> getTotalOutflowDescriptor()

Description copied from class: FlowElement

Returns an Accumulator instance that holds the total amounts of each material that has left this flow element.

The values of each element in the returned Accumulator match the quantities of the respective materials that have left the flow element. The sum of values in the Accumulator is equal to the value returned by the FlowElement.getTotalOutflowAmount() method.

Specified by:

getTotalOutflowDescriptor in class FlowElement<T>

Returns:

Accumulator containing total amounts of materials that have left this flow element

See Also:

• FlowElement.getTotalOutflowAmount()
• FlowElement.getTotalOutflowAmount(material)

addSpeedChangedHandler

public void addSpeedChangedHandler(Consumer<Conveyor<T>> handler)

Adds an action that will be executed every time the speed changes.

Parameters:

handler - action that will be executed every time the speed changes

See Also:

• removeOutflowRateChangedHandler(Consumer)

removeSpeedChangedHandler

public void removeSpeedChangedHandler(Consumer<Conveyor<T>> handler)

Removes the previously added speed change handler.

Parameters:

handler - previously added speed change handler

See Also:

• addSpeedChangedHandler(Consumer)