cz.zcu.fav.kiv.jsim
Class JSimHead

java.lang.Object
  cz.zcu.fav.kiv.jsim.JSimHead

All Implemented Interfaces:

JSimDisplayable, java.lang.Comparable<JSimHead>

public class JSimHead
extends java.lang.Object
implements JSimDisplayable, java.lang.Comparable<JSimHead>

The JSimHead class is an equivalent of Simula's or C-Sim's HEAD. It is a double-ended queue that can contain any number of JSimLink instances. It provides some useful statistics, too.

Since:

J-Sim version 0.1.0 (since J-Sim version 0.0.2 as JSimQueue)

Version:

J-Sim version 0.6.0

Author:

Jarda KAČER, Pavel DOMECKÝ

Field Summary

private double	creationTime The simulation time this queue was created.
private JSimLink	head The first link in the queue.
protected double	lastChange The simulation time when the last change was made.
private static java.util.logging.Logger	logger Common logger for all instances of this class.
private java.lang.String	myName The name of the queue.
private long	myNumber This queue's number.
protected JSimSimulation	myParent The simulation in which the queue is placed.
private long	noOfItems The number of links in the queue.
protected long	noOfItemsRemoved The number of links removed from the queue.
protected double	sumLwUntilLastChange The sum of time spent by all links in the queue from its creation to its last change.
protected double	sumTwRemoved The sum of time spent in the queue by all links already removed from it.
private JSimLink	tail The last link in the queue.

Constructor Summary

JSimHead(java.lang.String name, JSimSimulation parent)
Creates a new JSimHead queue belonging to a simulation and having a name.

Method Summary

long	cardinal() Returns the number of links in the queue.
void	clear() Removes all links from the queue.
int	compareTo(JSimHead h) Compares this head with another one.
javax.swing.JDialog	createDetailedInfoWindow(JSimMainWindow parentWindow) Creates a detailed info window that shows information about the queue.
protected void	decNoOfItems(double whenEntered) Decrements internal counter of links and updates statistics.
boolean	empty() Tests whether the queue is empty.
boolean	equals(java.lang.Object o) Indicates whether some other object is equal to this one.
JSimLink	first() Returns the first link in the queue.
double	getCurrentTime() Returns the current time of the simulation that this queue belongs to.
java.util.Collection<JSimPair>	getDetailedInformationArray() Returns a collection with the queue's characteristics.
java.lang.Object	getFirstData() Returns the first links's data.
java.lang.String	getFirstDataType() Returns the first link's data type.
protected JSimLink	getHead() Returns the head of the queue.
java.lang.String	getHeadName() Returns the queue's name.
long	getHeadNumber() Returns the queue's number.
java.lang.Object	getLastData() Returns the last links's data.
java.lang.String	getLastDataType() Returns the last link's data type.
double	getLw() Returns the mean length of the queue.
java.lang.String	getObjectListItemDescription() Returns a string containing basic information about the queue.
JSimSimulation	getParent() Returns the simulation that this queue is a part of.
protected JSimLink	getTail() Returns the tail of the queue.
double	getTw() Returns the mean waiting time spent in the queue by all links already removed from the queue.
double	getTwForAllLinks() Returns the mean waiting time spent in the queue by all links ever inserted to the queue.
int	hashCode() Returns a hash code value for the object.
protected void	incNoOfItems() Increments internal counter of links and updates statistics.
JSimLink	last() Returns the last link in the queue.
protected void	putAtHead(JSimLink newHead) Adds a link to the head of the queue, doing necessary adjustments.
protected void	putAtTail(JSimLink newTail) Sets a new tail of the queue, doing necessary adjustments.
protected void	setHead(JSimLink newHead) Sets a new head of the queue.
protected void	setTail(JSimLink newTail) Sets a new tail of the queue.
java.lang.String	toString() Returns a string representation of the queue.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

logger

private static final java.util.logging.Logger logger

Common logger for all instances of this class. By default, all logging information goes to a file. Only severe events go to the console, in addition to a file.

myName

private final java.lang.String myName

The name of the queue.

myNumber

private final long myNumber

This queue's number. Queue numbers are unique for a given simulation.

noOfItems

private long noOfItems

The number of links in the queue.

myParent

protected final JSimSimulation myParent

The simulation in which the queue is placed. Protected because child classes will possibly want to use it.

head

private JSimLink head

The first link in the queue.

tail

private JSimLink tail

The last link in the queue.

creationTime

private final double creationTime

The simulation time this queue was created.

sumLwUntilLastChange

protected double sumLwUntilLastChange

The sum of time spent by all links in the queue from its creation to its last change.

lastChange

protected double lastChange

The simulation time when the last change was made.

sumTwRemoved

protected double sumTwRemoved

The sum of time spent in the queue by all links already removed from it.

noOfItemsRemoved

protected long noOfItemsRemoved

The number of links removed from the queue.

Constructor Detail

JSimHead

public JSimHead(java.lang.String name,
                JSimSimulation parent)
         throws JSimInvalidParametersException,
                JSimTooManyHeadsException

Creates a new JSimHead queue belonging to a simulation and having a name. The queue is initially empty.

Parameters:

name - The name of the queue.

parent - The parent simulation.

Throws:

JSimInvalidParametersException - This exception is thrown out if the parent simulation is null.

JSimTooManyHeadsException - This exception is thrown out if no other queue can be added to the simulation specified.

Method Detail

empty

public boolean empty()

Tests whether the queue is empty.

Returns:

True if the queue is empty, false otherwise.

cardinal

public long cardinal()

Returns the number of links in the queue.

Returns:

The number of links in the queue.

first

public JSimLink first()

Returns the first link in the queue.

Returns:

The first link in the queue if the queue is not empty, null otherwise.

last

public JSimLink last()

Returns the last link in the queue.

Returns:

The last link in the queue if the queue is not empty, null otherwise.

clear

public void clear()

Removes all links from the queue. The links may survive if there is a reference to them. This is an "intelligent" removal. All links are removed one-by-one so that characteristics are properly updated.

getHeadNumber

public final long getHeadNumber()

Returns the queue's number.

Returns:

The queue's number.

getHeadName

public java.lang.String getHeadName()

Returns the queue's name.

Returns:

The queue's name.

getParent

public JSimSimulation getParent()

Returns the simulation that this queue is a part of.

Returns:

The simulation that this queue is a part of.

getFirstData

public java.lang.Object getFirstData()

Returns the first links's data. If the first link is an instance of a JSimLink subclass with user-defined content, the return value of this method depends on the creator of the subclass. If the link is used as a data wrapper (the data is specified as a constructor parameter), the wrapped data is returned.

Returns:

The first link's data if the queue is not empty, null otherwise.

getFirstDataType

public java.lang.String getFirstDataType()

Returns the first link's data type. If the first link is an instance of a JSimLink subclass with user-defined content, the return value of this method depends on the creator of the subclass. If the link is used as a data wrapper (the data is specified as a constructor parameter), the wrapped data's type is returned.

Returns:

The first link's data type if the queue is not empty, null otherwise.

getLastData

public java.lang.Object getLastData()

Returns the last links's data. If the last link is an instance of a JSimLink subclass with user-defined content, the return value of this method depends on the creator of the subclass. If the link is used as a data wrapper (the data is specified as a constructor parameter), the wrapped data is returned.

Returns:

The last link's data if the queue is not empty, null otherwise.

getLastDataType

public java.lang.String getLastDataType()

Returns the last link's data type. If the last link is an instance of a JSimLink subclass with user-defined content, the return value of this method depends on the creator of the subclass. If the link is used as a data wrapper (the data is specified as a constructor parameter), the wrapped data's type is returned.

Returns:

The last link's data type if the queue is not empty, null otherwise.

getCurrentTime

public double getCurrentTime()

Returns the current time of the simulation that this queue belongs to.

Returns:

The current time of the simulation that this queue belongs to.

getLw

public double getLw()

Returns the mean length of the queue. It makes no sense to calculate this value for a queue that has just been created. If no simulation time has passed since its creation NaN (not-a-number) will be returned.

Returns:

The mean length of the queue or NaN.

getTw

public double getTw()

Returns the mean waiting time spent in the queue by all links already removed from the queue. It makes no sense to calculate this value for a queue without any elements revoved from it. In such a case, NaN (not-a-number) will be returned.

Returns:

The mean waiting time spent in the queue by all links already removed from the queue or NaN.

getTwForAllLinks

public double getTwForAllLinks()

Returns the mean waiting time spent in the queue by all links ever inserted to the queue. Both links already removed from the queue and links just now present in the queue are counted. It makes no sense to calculate this value if no links have been inserted to the queue yet. In such a case, NaN (not-a-number) is returned. If this head is used as a FIFO (first in, first out) queue, which it usually is in queueing network simulations, the returned value is less than the value produced by getTw(). The reason for this behavior is that all links that have ever been in the queue have the same mean time spent in it and the links that currently are in the queue have not reached this time yet. So they push the overall mean time down because they are counted with the same weight as links already removed from the queue.

Returns:

The mean waiting time spent in the queue by all links ever inserted the queue or NaN.

getHead

protected final JSimLink getHead()

Returns the head of the queue. You should never use this method.

Returns:

The head of the queue.

setHead

protected final void setHead(JSimLink newHead)

Sets a new head of the queue. You should never use this method. It only updates the "head" field, it does not actually add anything to the head.

Parameters:

newHead - The new head of the queue.

putAtHead

protected final void putAtHead(JSimLink newHead)
                        throws JSimInvalidParametersException

Adds a link to the head of the queue, doing necessary adjustments. You should never use this method.

Parameters:

newHead - The new head of the queue.

Throws:

JSimInvalidParametersException - This exception is thrown out if the link that has to to become the new head is null.

getTail

protected final JSimLink getTail()

Returns the tail of the queue. You should never use this method.

Returns:

The tail of the queue.

setTail

protected final void setTail(JSimLink newTail)

Sets a new tail of the queue. You should never use this method. It only updates the "tail" field, it does not actually add anything to the tail.

Parameters:

newTail - The new tail of the queue.

putAtTail

protected final void putAtTail(JSimLink newTail)
                        throws JSimInvalidParametersException

Sets a new tail of the queue, doing necessary adjustments. You should never use this method.

Parameters:

newTail - The new tail of the queue.

Throws:

JSimInvalidParametersException - This exception is thrown out if the link that has to to become the new tail is null.

incNoOfItems

protected final void incNoOfItems()

Increments internal counter of links and updates statistics. You should never directly use this method. It is assumed that the new link has already been added to the list.

decNoOfItems

protected final void decNoOfItems(double whenEntered)

Decrements internal counter of links and updates statistics. You should never directly use this method. It is assumed that the link has already been removed from the list.

Parameters:

whenEntered - The simulation time when the link being removed entered the queue.

getObjectListItemDescription

public java.lang.String getObjectListItemDescription()

Returns a string containing basic information about the queue. The string can be displayed in a JSimMainWindowList component.

Specified by:

getObjectListItemDescription in interface JSimDisplayable

Returns:

A string containing basic information about the queue.

getDetailedInformationArray

public java.util.Collection<JSimPair> getDetailedInformationArray()

Returns a collection with the queue's characteristics. Every characteristics contains a name and a value. The collection can be displayed in a JSimGUIDetailedInfoWindow table.

Specified by:

getDetailedInformationArray in interface JSimDisplayable

Returns:

A collection of the queue's characteristics.

createDetailedInfoWindow

public javax.swing.JDialog createDetailedInfoWindow(JSimMainWindow parentWindow)

Creates a detailed info window that shows information about the queue. Returns a reference to the created window.

Specified by:

createDetailedInfoWindow in interface JSimDisplayable

Returns:

A reference to the created info window.

toString

public java.lang.String toString()

Returns a string representation of the queue. Provided information: number, name, link count.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of the queue.

compareTo

public int compareTo(JSimHead h)

Compares this head with another one. Returns a negative integer, zero, or a positive integer as this head is less than, equal to, or greater than the specified object. It is assumed that the argument is also a JSimHead. This class has a natural ordering that is fully consistent with equals(). If equals() returns true for h1 and h2, then compareTo() will return 0 for the same h1 and h2, and vice versa.

Specified by:

compareTo in interface java.lang.Comparable<JSimHead>

Returns:

Zero if the numbers of both heads are equal, a negative number if the number of this head is less than the other heads's number, and a positive number if the number of this head is greater than the other heads's number.

Throws:

java.lang.ClassCastException - This exception is thrown out when the specified object cannot be typecasted to JSimHead.

equals

public boolean equals(java.lang.Object o)

Indicates whether some other object is equal to this one. This implementation compares head numbers and their simulations' numbers which is actually equal to simple reference comparison because head numbers are unique for a given simulation and simulation numbers are unique for a given JVM instance. Unique head numbers are assured by the constructor and the JSimSimulation.getFreeQueueNumber() method. Unique simulation numbers are assured by the JSimSimulation constructor.

Overrides:

equals in class java.lang.Object

Parameters:

o - The reference object with which to compare.

Returns:

True if this object is the same as the obj argument, false otherwise.

hashCode

public int hashCode()

Returns a hash code value for the object. The hash code is computed from the head's number and its simulation's number using the algorithm described in [UJJ3/166]. This implementation of hash code computation is fully consistent with equals().

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code for this head.