org.javades.jqueues.r5.entity.jq.queue.composite.enc

Class AbstractEncapsulatorSimQueue<DJ extends SimJob,DQ extends SimQueue,J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

java.lang.Object

org.javades.jqueues.r5.entity.AbstractSimEntity

org.javades.jqueues.r5.entity.jq.AbstractSimJQ<J,Q>

org.javades.jqueues.r5.entity.jq.queue.AbstractSimQueue<J,Q>

org.javades.jqueues.r5.entity.jq.queue.composite.AbstractSimQueueComposite<DJ,DQ,J,Q>

org.javades.jqueues.r5.entity.jq.queue.composite.enc.AbstractEncapsulatorSimQueue<DJ,DQ,J,Q>

Type Parameters:

DJ - The delegate-job type.

DQ - The queue-type for delegate jobs.

J - The job type.

Q - The queue type for jobs.

All Implemented Interfaces:

SimQueueComposite<DJ,DQ,J,Q>, SimQueueSelector<J,DQ>, SimQueue<J,Q>, SimQoS<J,Q>, SimEntity, SimEntityListener, org.javades.jsimulation.r5.SimEventListResetListener

Direct Known Subclasses:

Enc, EncHS, EncJL, EncTL, EncXM

public abstract class AbstractEncapsulatorSimQueue<DJ extends SimJob,DQ extends SimQueue,J extends SimJob,Q extends AbstractEncapsulatorSimQueue>
extends AbstractSimQueueComposite<DJ,DQ,J,Q>

A SimQueueComposite encapsulating a single SimQueue (abstract implementation).

This composite queue takes as single SimQueue as argument (the encapsulated queue, or the sub-queue), and mimics that queue's interface in all its aspects (by default). Specific concrete implementations seek to (1) subtly modify the behavior of the embedded queue, and/or (2) subtly transform the view on the embedded queue.

This base class implements the case in which the behavior of the composite queue precisely matches that of the encapsulated queue (including non-standard operations and notifications). Encapsulator queues by default inherit the QoS structure from the encapsulated queue.

Encapsulator queues are said to have Encapsulator model, as opposed to e.g. LocalStart model as explained in AbstractSimQueueComposite_LocalStart. In comparison with the latter, encapsulator queues have a lot more freedom in mapping between the respective SimQueueComposite interfaces of the encapsulator and the encapsulated queue. This explains why many methods in this abstract base class are not final. Pretty much the only invariant sub-classes must stick to is a 1:1 mapping between jobs on the composite and encapsulated queues. In other words, any job present in the composite queue must also be present on the encapsulated queue and (obviously) vice versa.

The default behavior is implemented in Enc, and is as follows (sloppily erasing the distinction between real and delegate jobs):

• If a job arrives at the encapsulator, it arrives at the encapsulated queue.
• If a job is dropped on the encapsulated queue, it is dropped at the encapsulator.
• If a job is revoked on the encapsulator (after checking the interruptService flag), it is forcibly revoked from the encapsulated queue.
• If a job is auto-revoked on the encapsulator (e.g., due to AbstractSimQueue.getAutoRevocationPolicy() conditions on the composite queue), it is forcibly revoked from the encapsulated queue.
• If a job is auto-revoked on the encapsulated queue, it is auto-revoked on the encapsulator.
• If a job starts on the encapsulated queue, it starts on the encapsulator.
• If a job departs from the encapsulated queue, it departs from the encapsulator.

However, again we stress the fact that concrete sub-classes may in various ways change and/or augment this behavior. For instance, the EncHS system hides start-events from the encapsulated queue; all real jobs are thus always in the waiting area of the encapsulator. The EncXM system can map exit methods of delegate jobs on the encapsulated queue onto other exit methods on the encapsulator, e.g., jobs being dropped on the encapsulated queue appear as departures on the encapsulator.

Users of concrete sub-classes of AbstractEncapsulatorSimQueue can rely on the fact that no auto-revocation triggers are set on the encapsulated queue. As a result, such conditions may have been set already upon the supplied encapsulated queue upon construction. The encapsulator will simply "inherit" the auto-revocation conditions. However, this comes at a price: Sub-classes have complete freedom in adding additional auto-revocation conditions at the encapsulator level. Hopefully, such additional conditions are properly documented in the sub-class.

Author:

Jan de Jongh, TNO

Copyright (C) 2005-2017 Jan de Jongh, TNO

This file is covered by the LICENSE file in the root of this project.

See Also:

SimQueueComposite, Enc, EncHS, EncTL, EncJL

Nested Class Summary

Nested classes/interfaces inherited from class org.javades.jqueues.r5.entity.jq.queue.composite.AbstractSimQueueComposite

AbstractSimQueueComposite.RealDelegateJobMapper<J extends SimJob,DJ extends SimJob>

Nested classes/interfaces inherited from class org.javades.jqueues.r5.entity.AbstractSimEntity

AbstractSimEntity.Notifier, AbstractSimEntity.PreNotificationHook

Nested classes/interfaces inherited from interface org.javades.jqueues.r5.entity.jq.queue.SimQueue

SimQueue.AutoRevocationPolicy

Nested classes/interfaces inherited from interface org.javades.jqueues.r5.entity.SimEntity

SimEntity.Action, SimEntity.UnknownNotificationTypePolicy, SimEntity.UnknownOperationPolicy

Field Summary

Fields inherited from class org.javades.jqueues.r5.entity.jq.queue.composite.AbstractSimQueueComposite

realDelegateJobMapper

Fields inherited from class org.javades.jqueues.r5.entity.jq.queue.AbstractSimQueue

eventsScheduled, SANITY

Fields inherited from class org.javades.jqueues.r5.entity.AbstractSimEntity

USE_ARRAY_OPTIMIZATION

Constructor Summary

Constructors

Constructor and Description
AbstractEncapsulatorSimQueue(org.javades.jsimulation.r5.SimEventList eventList, DQ queue, DelegateSimJobFactory delegateSimJobFactory) Creates an encapsulator queue given an event list and a sub-queue, mimicking the sub-queue's behavior.

Method Summary

Modifier and Type	Method and Description
SimQueue<DJ,DQ>	getEncapsulatedQueue() Returns the encapsulated queue.
Object	getQoS() Returns the QoS value of the encapsulated queue.
Class	getQoSClass() Returns the QoS class of the encapsulated queue.
protected double	getServiceTimeForJob(J job) Calls super method.
protected void	insertJobInQueueUponArrival(J job, double time) Creates the delegate job and administers it.
protected void	insertJobInQueueUponStart(J job, double time) Performs sanity checks only.
boolean	isStartArmed() Returns the startArmed state of the encapsulated queue.
protected void	processSubQueueNotifications(List<MultiSimQueueNotificationProcessor.Notification<DJ,DQ>> notifications) Processes the pending atomic notifications from the sub-queues, one at a time (core sub-queue notification processor).
protected void	removeJobFromQueueUponDeparture(J departingJob, double time) Departure of the given (real) job.
protected void	removeJobFromQueueUponDrop(J job, double time) Drops the given (real) job.
protected void	removeJobFromQueueUponRevokation(J job, double time, boolean auto) Removes a job upon successful revocation, as determined by our super-class, or upon auto-revocation on the encapsulator (i.e., sub-class) or on the encapsulated queue.
protected void	rescheduleAfterArrival(J job, double time) Lets the delegate job arrive at the encapsulated queue.
protected void	rescheduleAfterDeparture(J departedJob, double time) Enforces the scheduled revocation on the sub-queue, if applicable.
protected void	rescheduleAfterDrop(J job, double time) Enforces the scheduled revocation on the sub-queue, if applicable.
protected void	rescheduleAfterRevokation(J job, double time, boolean auto) If present, performs the pending revocation on the applicable sub-queue, and check whether that succeeded.
protected void	rescheduleAfterStart(J job, double time) Does nothing.
protected void	rescheduleForNewServerAccessCredits(double time) Does nothing.
protected void	resetEntitySubClass() Calls super method.
protected void	setServerAccessCreditsSubClass() Copies the new server-access credits into the encapsulated queue.

Methods inherited from class org.javades.jqueues.r5.entity.jq.queue.composite.AbstractSimQueueComposite

addRealJobLocal, getCopySimQueues, getCopySubSimQueues, getDelegateJob, getDelegateJobMild, getDelegateSimJobFactory, getIndex, getIndex, getQueue, getQueue, getQueues, getRealJob, getRealJob, getSimQueueSelector, isDelegateJob, isRealJob, notifyResetEntity, notifyStateChanged, notifyUpdate, removeJobsFromQueueLocal, resetSimQueueSelector, selectFirstQueue, selectNextQueue, setDelegateSimJobFactory

Methods inherited from class org.javades.jqueues.r5.entity.jq.queue.AbstractSimQueue

arrive, autoRevoke, cancelDepartureEvent, cancelDepartureEvent, depart, departureFromEventList, drop, getAutoRevocationPolicy, getDepartureEvents, getDepartureEvents, getFirstJob, getFirstJobInServiceArea, getFirstJobInWaitingArea, getJobs, getJobsInServiceArea, getJobsInWaitingArea, getNumberOfJobs, getNumberOfJobsInServiceArea, getNumberOfJobsInWaitingArea, getServerAccessCredits, hasJobs, hasJobsInServiceArea, hasJobsInWaitingArea, hasServerAcccessCredits, isJob, isJobInServiceArea, isJobInWaitingArea, isQueueAccessVacation, queueAccessVacationDropSubClass, registerStdOutSimQueueListener, revoke, revoke, scheduleDepartureEvent, scheduleJobArrival, setAutoRevocationPolicy, setQueueAccessVacation, setServerAccessCredits, start, takeServerAccessCredit, toStringDefault, triggerPotentialNewStartArmed, unregisterStdOutSimQueueListener

Methods inherited from class org.javades.jqueues.r5.entity.AbstractSimEntity

addPendingNotification, addPendingNotification, clearAndUnlockPendingNotificationsIfLocked, delegateOperation, doAfterNotifications, doOperation, fireAndLockPendingNotifications, getEventList, getLastUpdateTime, getRegisteredDelegatedOperations, getRegisteredNotificationTypes, getRegisteredOperations, getSimEntityListeners, getUnknownNotificationTypePolicy, getUnknownOperationPolicy, isIgnoreEventListReset, notifyEventListReset, registerDelegatedOperation, registerNotificationType, registerOperation, registerPreEventHook, registerPreNotificationHook, registerPreUpdateHook, registerSimEntityListener, registerStdOutSimEntityListener, removeDelegationForOperation, resetEntity, setIgnoreEventListReset, setName, setUnknownNotificationTypePolicy, setUnknownOperationPolicy, toString, unregisterSimEntityListener, unregisterStdOutSimEntityListener, update

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.javades.jqueues.r5.entity.jq.queue.SimQueue

arrive, getAutoRevocationPolicy, getCopySimQueue, getJobs, getJobsInServiceArea, getJobsInWaitingArea, getNumberOfJobs, getNumberOfJobsInServiceArea, getNumberOfJobsInWaitingArea, getServerAccessCredits, isJob, isJobInServiceArea, isJobInWaitingArea, isQueueAccessVacation, revoke, revoke, setAutoRevocationPolicy, setQueueAccessVacation, setServerAccessCredits

Methods inherited from interface org.javades.jqueues.r5.entity.SimEntity

doAfterNotifications, doOperation, getEventList, getLastUpdateTime, getRegisteredNotificationTypes, getRegisteredOperations, getSimEntityListeners, getUnknownNotificationTypePolicy, getUnknownOperationPolicy, isIgnoreEventListReset, registerSimEntityListener, resetEntity, setIgnoreEventListReset, setName, setUnknownNotificationTypePolicy, setUnknownOperationPolicy, toStringDefault, unregisterSimEntityListener, update

Methods inherited from interface org.javades.jsimulation.r5.SimEventListResetListener

notifyEventListReset

Constructor Detail

AbstractEncapsulatorSimQueue

public AbstractEncapsulatorSimQueue(org.javades.jsimulation.r5.SimEventList eventList,
                                    DQ queue,
                                    DelegateSimJobFactory delegateSimJobFactory)

Creates an encapsulator queue given an event list and a sub-queue, mimicking the sub-queue's behavior.

This composite queue mimics the QoS behavior of the encapsulated queue, and all its operation and notification types.

Parameters:

eventList - The event list to use.

queue - The encapsulated queue.

delegateSimJobFactory - An optional factory for the delegate SimJobs.

Throws:

IllegalArgumentException - If the event list or the queue is null.

See Also:

DelegateSimJobFactory, DefaultDelegateSimJobFactory, AbstractSimEntity.getRegisteredOperations(), AbstractSimEntity.registerDelegatedOperation(org.javades.jqueues.r5.entity.SimEntityOperation, org.javades.jqueues.r5.entity.SimEntityOperation), AbstractSimEntity.getRegisteredNotificationTypes(), AbstractSimEntity.registerNotificationType(org.javades.jqueues.r5.entity.SimEntitySimpleEventType.Member, org.javades.jqueues.r5.entity.AbstractSimEntity.Notifier)

Method Detail

getEncapsulatedQueue

public final SimQueue<DJ,DQ> getEncapsulatedQueue()

Returns the encapsulated queue.

Returns:

The encapsulated queue, non-null.

getQoS

public Object getQoS()

Returns the QoS value of the encapsulated queue.

Returns:

The QoS value of the encapsulated queue.

getQoSClass

public Class getQoSClass()

Returns the QoS class of the encapsulated queue.

Returns:

The QoS class of the encapsulated queue.

resetEntitySubClass

protected void resetEntitySubClass()

Calls super method.

Overrides:

resetEntitySubClass in class AbstractSimQueueComposite<DJ extends SimJob,DQ extends SimQueue,J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

See Also:

AbstractSimQueue.removeJobFromQueueUponRevokation(J, double, boolean), AbstractSimQueue.rescheduleAfterRevokation(J, double, boolean), SimEntity.resetEntity(), SimQueueSelector.resetSimQueueSelector(), SimQueue.setServerAccessCredits(double, int), SimQueue.isStartArmed()

insertJobInQueueUponArrival

protected void insertJobInQueueUponArrival(J job,
                                           double time)

Creates the delegate job and administers it.

Specified by:

insertJobInQueueUponArrival in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

job - The job that arrived.

time - The current time (i.e., arrival time of the job).

See Also:

AbstractSimQueueComposite.addRealJobLocal(J), rescheduleAfterArrival(J, double)

rescheduleAfterArrival

protected void rescheduleAfterArrival(J job,
                                      double time)

Lets the delegate job arrive at the encapsulated queue.

Specified by:

rescheduleAfterArrival in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

job - The job that arrived (and is already present in AbstractSimQueue.getJobs()).

time - The current time (i.e., the arrival time of the job).

See Also:

SimQueue.arrive(double, J), insertJobInQueueUponArrival(J, double)

removeJobFromQueueUponDrop

protected void removeJobFromQueueUponDrop(J job,
                                          double time)

Drops the given (real) job.

A (real) job can only be dropped because of one of the following two reasons:

• Its delegate job is dropped (autonomously) on the sub-queue, see processSubQueueNotifications(java.util.List<org.javades.jqueues.r5.listener.MultiSimQueueNotificationProcessor.Notification<DJ, DQ>>). In this case, the delegate job has already left the sub-queue when we are called, hence no action is required to remove it from there. All we have to do is invoke AbstractSimQueueComposite.removeJobsFromQueueLocal(J, DJ).
• The composite queue (us) enforces dropping the job. In this case, the delegate job may still be present on the sub-queue, and we have to forcibly revoke it on the sub-queue if so. We abuse removeJobFromQueueUponRevokation(J, double, boolean) to initiate the revocation (note that we cannot directly invoke AbstractSimQueue.revoke(double, J, boolean) or AbstractSimQueue.autoRevoke(double, J) on the composite queue as that would trigger an incorrect revocation notification).

Specified by:

removeJobFromQueueUponDrop in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

job - The job that is to be dropped.

time - The current time (i.e., drop time of the job).

Throws:

IllegalStateException - If the real or delegate job does not exist.

See Also:

AbstractSimQueue.drop(J, double), rescheduleAfterDrop(J, double), removeJobFromQueueUponRevokation(J, double, boolean), AbstractSimQueueComposite.removeJobsFromQueueLocal(J, DJ), AbstractSimQueueComposite.getDelegateJob(SimJob), SimJob.getQueue()

rescheduleAfterDrop

protected void rescheduleAfterDrop(J job,
                                   double time)

Enforces the scheduled revocation on the sub-queue, if applicable.

Specified by:

rescheduleAfterDrop in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

job - The jobs that was dropped.

time - The current time (i.e., drop time of the job).

See Also:

removeJobFromQueueUponDrop(J, double), rescheduleAfterRevokation(J, double, boolean)

removeJobFromQueueUponRevokation

protected void removeJobFromQueueUponRevokation(J job,
                                                double time,
                                                boolean auto)

Removes a job upon successful revocation, as determined by our super-class, or upon auto-revocation on the encapsulator (i.e., sub-class) or on the encapsulated queue.

In case of an auto-revocation, the presence or absence of the job on the encapsulated queue determines whether auto-revocation is caused by the composite queue or by the encapsulated queue, respectively. In the latter case, all we have to do is remove the real job from our local admin.

In the former case, and in case of (plain) revocation, we have to forcibly remove the delegate job from the encapsulated queue. To that effect, this method interacts delicately with rescheduleAfterRevokation(J, double, boolean) and the MultiSimQueueNotificationProcessor on the sub-queue, through the use of a pending revocation event (a local private field).

We have to forcibly revoke the delegate job still present on the encapsulated sub-queue. Because we cannot perform the revocation here (we are not allowed to reschedule!), we defer until removeJobFromQueueUponRevokation(J, double, boolean) by raising an internal flag (in fact a newly created, though not scheduled SimJQEvent.Revocation). We have to use this method in order to remember the delegate job to be revoked, and the queue from which to revoke it, both of which are wiped from the internal administration by AbstractSimQueueComposite.removeJobsFromQueueLocal(J, DJ), which is invoked last.

Note that even though a SimJQEvent.Revocation is used internally to flag the required delegate-job revocation, it is never actually scheduled on the event list!

Specified by:

removeJobFromQueueUponRevokation in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

job - The job that is to be revoked.

time - The current time (i.e., revocation time of the job).

auto - Whether or not this applies to an auto-revocation.

Throws:

IllegalStateException - If the delegate job is not visiting the sub-queue while it should, if a pending delegate revocation has already been flagged (or been forgotten to clear), or if any other sanity check fails.

See Also:

AbstractSimQueue.revoke(double, J, boolean), AbstractSimQueue.autoRevoke(double, J), SimJQEvent.Revocation, rescheduleAfterRevokation(J, double, boolean), AbstractSimQueueComposite.getDelegateJob(SimJob), SimJob.getQueue(), AbstractSimQueueComposite.removeJobsFromQueueLocal(J, DJ)

rescheduleAfterRevokation

protected void rescheduleAfterRevokation(J job,
                                         double time,
                                         boolean auto)

If present, performs the pending revocation on the applicable sub-queue, and check whether that succeeded.

This method interacts delicately with removeJobFromQueueUponRevokation(J, double, boolean) and the MultiSimQueueNotificationProcessor on the sub-queues, through the use of a pending revocation event (a local private field).

Upon return, the pending revocation event has been reset to null.

Specified by:

rescheduleAfterRevokation in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

job - The jobs that was successfully revoked.

time - The current time (i.e., revocation time of the job).

auto - Whether or not this applies to an auto-revocation.

Throws:

IllegalStateException - If this is not an auto-revocation and no pending delegate revocation was found, or revoking the delegate job failed (as indicated by the failure to reset the pending revocation event by the sub-queue notification processor, see processSubQueueNotifications(java.util.List<org.javades.jqueues.r5.listener.MultiSimQueueNotificationProcessor.Notification<DJ, DQ>>)).

Note that even though a SimJQEvent.Revocation is used internally to flag the required delegate-job revocation, it is never actually scheduled on the event list!

See Also:

SimJQEvent.Revocation, removeJobFromQueueUponRevokation(J, double, boolean), processSubQueueNotifications(java.util.List<org.javades.jqueues.r5.listener.MultiSimQueueNotificationProcessor.Notification<DJ, DQ>>)

isStartArmed

public boolean isStartArmed()

Returns the startArmed state of the encapsulated queue.

Returns:

The startArmed state of the of the encapsulated queue.

See Also:

SimQueue.isStartArmed()

setServerAccessCreditsSubClass

protected void setServerAccessCreditsSubClass()

Copies the new server-access credits into the encapsulated queue.

Overrides:

setServerAccessCreditsSubClass in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

See Also:

AbstractSimQueue.getServerAccessCredits(), AbstractSimEntity.getLastUpdateTime(), SimQueue.setServerAccessCredits(double, int), rescheduleForNewServerAccessCredits(double)

rescheduleForNewServerAccessCredits

protected void rescheduleForNewServerAccessCredits(double time)

Does nothing.

This method does nothing (we follow the server-access credits on the encapsulated queue, and only set them upon external request).

Specified by:

rescheduleForNewServerAccessCredits in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

time - The current time (i.e., the time at which new server-access credits became available).

See Also:

setServerAccessCreditsSubClass()

insertJobInQueueUponStart

protected void insertJobInQueueUponStart(J job,
                                         double time)

Performs sanity checks only.

Specified by:

insertJobInQueueUponStart in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

job - The job that starts.

time - The current time (i.e., start time of the job).

Throws:

IllegalStateException - If sanity checks on internal consistency fail.

See Also:

AbstractSimQueue.isJob(org.javades.jqueues.r5.entity.jq.job.SimJob), AbstractSimQueue.isJobInServiceArea(org.javades.jqueues.r5.entity.jq.job.SimJob), AbstractSimQueueComposite.getDelegateJob(J), rescheduleAfterStart(J, double)

rescheduleAfterStart

protected void rescheduleAfterStart(J job,
                                    double time)

Does nothing.

This method does nothing; we are merely being notified of the start of a delegate job on the encapsulated queue, and our own notification will be dealt with by our caller, AbstractSimQueue.start(double, J).

Specified by:

rescheduleAfterStart in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

job - The job that started (and is already present in AbstractSimQueue.getJobsInServiceArea().

time - The current time (i.e., the start time of the job).

Throws:

IllegalStateException - If sanity checks on internal consistency fail.

See Also:

AbstractSimQueue.isJob(org.javades.jqueues.r5.entity.jq.job.SimJob), AbstractSimQueue.isJobInServiceArea(org.javades.jqueues.r5.entity.jq.job.SimJob), AbstractSimQueueComposite.getDelegateJob(J), insertJobInQueueUponStart(J, double)

getServiceTimeForJob

protected double getServiceTimeForJob(J job)

Calls super method.

Overrides:

getServiceTimeForJob in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

job - The job, non-null.

Returns:

The result from the super method.

removeJobFromQueueUponDeparture

protected void removeJobFromQueueUponDeparture(J departingJob,
                                               double time)

Departure of the given (real) job.

In the AbstractEncapsulatorSimQueue, a (real) job can only depart because of one of the following two reasons:

• Its delegate job departs (autonomously) on the encapsulated queue, see processSubQueueNotifications(java.util.List<org.javades.jqueues.r5.listener.MultiSimQueueNotificationProcessor.Notification<DJ, DQ>>). In this case, the delegate job has already left the sub-queue when we are called, hence no action is required to remove it from there. All we have to do is invoke AbstractSimQueueComposite.removeJobsFromQueueLocal(J, DJ).
• The composite queue (us) enforces departure the job. In this case, the delegate job may still be present on a sub-queue, and we have to forcibly revoke it on the sub-queue if so. We abuse removeJobFromQueueUponRevokation(J, double, boolean) to initiate the revocation (note that we cannot directly invoke AbstractSimQueue.revoke(double, J, boolean) or AbstractSimQueue.autoRevoke(double, J) on the composite queue as that would trigger an incorrect revocation notification).

Specified by:

removeJobFromQueueUponDeparture in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

departingJob - The job that departs.

time - The departure (current) time.

Throws:

IllegalStateException - If the real or delegate job does not exits.

See Also:

AbstractSimQueue.depart(double, J), rescheduleAfterDeparture(J, double), removeJobFromQueueUponRevokation(J, double, boolean), AbstractSimQueueComposite.removeJobsFromQueueLocal(J, DJ), AbstractSimQueueComposite.getDelegateJob(SimJob), SimJob.getQueue()

rescheduleAfterDeparture

protected void rescheduleAfterDeparture(J departedJob,
                                        double time)

Enforces the scheduled revocation on the sub-queue, if applicable.

Specified by:

rescheduleAfterDeparture in class AbstractSimQueue<J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

departedJob - The departed job.

time - The departure (current) time.

See Also:

removeJobFromQueueUponDeparture(J, double), rescheduleAfterRevokation(J, double, boolean)

processSubQueueNotifications

protected void processSubQueueNotifications(List<MultiSimQueueNotificationProcessor.Notification<DJ,DQ>> notifications)

Processes the pending atomic notifications from the sub-queues, one at a time (core sub-queue notification processor).

Core method for reacting to SimEntityListener.notifyStateChanged(double, org.javades.jqueues.r5.entity.SimEntity, java.util.List<java.util.Map<org.javades.jqueues.r5.entity.SimEntitySimpleEventType.Member, org.javades.jqueues.r5.entity.SimEntityEvent>>) notifications from all sub-queues. This method is registered as the processor for an anonymous MultiSimQueueNotificationProcessor (for all sub-queues) created upon construction, see MultiSimQueueNotificationProcessor.Processor and MultiSimQueueNotificationProcessor.setProcessor(org.javades.jqueues.r5.listener.MultiSimQueueNotificationProcessor.Processor).

This method takes one notification at a time, starting at the head of the list, removes it, and processes the notification as described below. While processing, new notifications may be added to the list; the list is processed until it is empty.

However, before processing any event, it checks for SimEntitySimpleEventType.RESET (sub-)notifications. If it finds any, the notifications list is cleared and immediate return from this method follows. A reset event, however, is subjected to rigorous sanity checks; notably, it has to be an isolated atomic event. Failure of the sanity checks will lead to an IllegalStateException.

Otherwise, this method processes the notifications as described below; the remainder of the method is encapsulated in a AbstractSimEntity.clearAndUnlockPendingNotificationsIfLocked() and AbstractSimEntity.fireAndLockPendingNotifications() pair, to make sure we create atomic notifications in case of a top-level event.

A notification consists of a (fixed) sequence of sub-notifications, see MultiSimQueueNotificationProcessor.Notification.getSubNotifications(), each of which is processed in turn as follows:

• With SimEntitySimpleEventType.RESET, impossible, see above; throws an IllegalStateException.
• With queue-access vacation related events, SimQueueSimpleEventType.QUEUE_ACCESS_VACATION, SimQueueSimpleEventType.QAV_START, SimQueueSimpleEventType.QAV_END, we do nothing (allowed for sub-class use).
• With server-access credits related events SimQueueSimpleEventType.SERVER_ACCESS_CREDITS, SimQueueSimpleEventType.REGAINED_SAC, SimQueueSimpleEventType.OUT_OF_SAC, we so nothing (allowed for sub-class use).
• We ignore start-armed related events SimQueueSimpleEventType.STA_FALSE, SimQueueSimpleEventType.STA_TRUE, as these are dealt with (if at all) by the outer loop.
• With SimJQSimpleEventType.ARRIVAL, we do nothing.
• With SimJQSimpleEventType.DROP, we drop the real job through AbstractSimQueue.drop(J, double).
• With SimJQSimpleEventType.REVOCATION, we check for the presence of a corresponding real job through AbstractSimQueueComposite.getRealJob(DJ, DQ), and throw an IllegalStateException if we found one. Revocation notifications must always be the result of the composite queue's AbstractSimQueue.revoke(double, J, boolean) operation, and at this stage, the real job has already been removed from the composite queue. Subsequently, we perform sanity checks on the pending revocation event, again throwing an IllegalStateException in case of an error. If all is well, we simply clear the pending revocation event on the composite queue.
• With SimJQSimpleEventType.AUTO_REVOCATION, we invoke AbstractSimQueue.autoRevoke(double, J) (allowed for encapsulated-queue or sub-class use).
• With SimJQSimpleEventType.START, we start the real job.
• With SimJQSimpleEventType.DEPARTURE, we make the real job depart.
• With any non-standard notification type, we pass the notification using SimJQEvent.copyForQueueAndJob(Q, J) to map between real and delegate job and between composite and encapsulated queue.

After all notifications have been processed, and the notification list is empty, we invoke AbstractSimQueue.triggerPotentialNewStartArmed(double) on the composite queue, in order to make sure we are not missing an autonomous change in SimQueue.isStartArmed() on a sub-queue. Since we do not expect any back-fire notifications from sub-queues from that method, we check again the notification list, and throw an exception if it is non-empty.

A full description of the sanity checks would make this entry uninterestingly large(r), hence we refer to the source code. Most checks are trivial checks on the allowed sub-notifications from the sub-queues and on the presence or absence of real and delegate jobs (and their expected presence or absence on a sub-queue).

Specified by:

processSubQueueNotifications in class AbstractSimQueueComposite<DJ extends SimJob,DQ extends SimQueue,J extends SimJob,Q extends AbstractEncapsulatorSimQueue>

Parameters:

notifications - The sub-queue notifications, will be modified; empty upon return.

Throws:

IllegalArgumentException - If the list is null or empty, or contains a notification from another queue than the a sub-queue, or if other sanity checks fail.

See Also:

MultiSimQueueNotificationProcessor, MultiSimQueueNotificationProcessor.Processor, MultiSimQueueNotificationProcessor.setProcessor(org.javades.jqueues.r5.listener.MultiSimQueueNotificationProcessor.Processor), SimEntitySimpleEventType.RESET, SimJQSimpleEventType.ARRIVAL, SimQueueSimpleEventType.QUEUE_ACCESS_VACATION, SimQueueSimpleEventType.QAV_START, SimQueueSimpleEventType.QAV_END, SimQueueSimpleEventType.SERVER_ACCESS_CREDITS, SimQueueSimpleEventType.OUT_OF_SAC, SimQueueSimpleEventType.REGAINED_SAC, SimQueueSimpleEventType.STA_FALSE, SimQueueSimpleEventType.STA_TRUE, SimJQSimpleEventType.DROP, SimJQSimpleEventType.REVOCATION, SimJQSimpleEventType.AUTO_REVOCATION, SimJQSimpleEventType.START, SimJQSimpleEventType.DEPARTURE, AbstractSimEntity.addPendingNotification(java.util.Map<org.javades.jqueues.r5.entity.SimEntitySimpleEventType.Member, org.javades.jqueues.r5.entity.SimEntityEvent>), SimQueue.arrive(double, J), AbstractSimQueue.start(double, J), AbstractSimQueueComposite.selectNextQueue(double, J, DQ), AbstractSimQueue.depart(double, J), AbstractSimQueue.triggerPotentialNewStartArmed(double), AbstractSimEntity.clearAndUnlockPendingNotificationsIfLocked(), AbstractSimEntity.fireAndLockPendingNotifications()