org.javades.jqueues.r5.entity

Interface SimEntity

All Superinterfaces:

org.javades.jsimulation.r5.SimEventListResetListener

All Known Subinterfaces:

SimJob<J,Q>, SimJobQoS<J,Q,P>, SimQueue<J,Q>, SimQueueComposite<DJ,DQ,J,Q>, SimQueueOrJobQoS<J,Q,P>, SimQueueQoS<J,Q,P>, SimQueueWithGate<J,Q>

All Known Implementing Classes:

AbstractClassicSimQueue, AbstractCollectorSimQueue, AbstractEgalitarianProcessorSharingSimQueue, AbstractEncapsulatorSimQueue, AbstractFeedbackSimQueue, AbstractNonPreemptiveWorkConservingSimQueue, AbstractParallelSimQueues, AbstractPreemptiveSimQueue, AbstractPreemptiveSimQueueQoS, AbstractProcessorSharingSimQueue, AbstractServerlessSimQueue, AbstractSimEntity, AbstractSimJob, AbstractSimJQ, AbstractSimQueue, AbstractSimQueueComposite, AbstractSimQueueComposite_LocalStart, AbstractSimQueueQoS, ALIMIT, ARevCol, Col, CompositeExample.TestDelegateSimJob, CTandem2, CUPS, DefaultExampleSimJob, DefaultExampleSimJobQoS, DefaultSelfListeningSimJob, DefaultSelfListeningSimJobQoS, DefaultSimJob, DefaultSimJobQoS, DefaultVisitsLoggingSimJob, DefaultVisitsLoggingSimJobQoS, DELAY, DepCol, DLIMIT, DROP, DropCol, Enc, EncHS, EncJL, EncJLExample.TestDelegateSimJob, EncTL, EncTLExample.TestDelegateSimJob, EncXM, FB, FB_p, FB_v, FCFS, FCFS_B, FCFS_B_c, FCFS_c, GATE, HOL, HOL_PS, IC, IS, IS_CST, Jackson, JRQ, JSQ, LCFS, LCFS_B, LeakyBucket, LJF, NoBuffer_c, P_LCFS, Par, Pattern, PQ, PS, RANDOM, SINK, SJF, SocPS, SRTF, SUR, Tandem, WUR, ZERO

public interface SimEntity
extends org.javades.jsimulation.r5.SimEventListResetListener

A simulation entity like SimJob or SimQueue.

A SimEntity is an entity relevant to event-list scheduling in a queueing system simulation. Usually, it is either a queue (SimQueue) or a job (SimJob). However, the interface does not a priori assume this. What SimEntitys have in common is the event list they are attached to, the fact that they have a name, that they support operations, and their obligation to propagate state changes (notifications) to (registered) listeners.

Objects implementing this interface take care of (at the very least)

• holding the underlying event list (SimEventList), which may be null,
• registering as a SimEventListResetListener to a non-null SimEventList, obeying resets on the SimEventList, and propagating reset events on the SimEventList to SimEntityListeners through resetEntity() (which, effectively, describes the RESET operation),
• naming, through setName(java.lang.String) and toStringDefault(),
• registration and maintenance of SimEntityOperations, and supporting them through doOperation(double, Req) with flexible error handling for unknown operations,
• registration, maintenance and error handling of (types of) notifications implemented as SimEntitySimpleEventType.Member,
• maintaining listeners (SimEntityListener) to notifications,
• notifying listeners upon updates and state changes, see SimEntityListener.notifyUpdate(double, org.javades.jqueues.r5.entity.SimEntity) and 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>>), respectively,
• supporting (deferred) actions to take immediately after notifying listeners (supported because, as by contract of SimEntity and SimEntityListener, listeners are not allowed to initiate state-changing operations on the entity),
• implementing updates and maintaining the time of the last update with getLastUpdateTime() (effectively, the UPDATE notification).

Note that the contracts of SimEntityOperation, SimEntitySimpleEventType, SimEntityEvent and SimEntityListener are part of the formal interface of a SimEntity.

For an implementation starting point, see AbstractSimEntity.

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:

SimEntityOperation, SimEntitySimpleEventType, SimEntityEvent, SimEntityListener, SimJob, SimQueue, AbstractSimEntity

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	SimEntity.Action An action for use in doAfterNotifications(org.javades.jqueues.r5.entity.SimEntity.Action).
static class	SimEntity.UnknownNotificationTypePolicy Possible courses of action when an unknown notification is to be published.
static class	SimEntity.UnknownOperationPolicy Possible courses of action when an unknown operation is offered to doOperation(double, Req).

Method Summary

Modifier and Type	Method and Description
void	doAfterNotifications(SimEntity.Action action) Registers an SimEntity.Action to be taken once this entity has finished issuing notifications, or takes the action immediately if this entity is not notifying listeners.
<O extends SimEntityOperation,Req extends SimEntityOperation.Request,Rep extends SimEntityOperation.Reply> Rep	doOperation(double time, Req request) Performs the given operation, identified by an operation request, at this entity at given time.
org.javades.jsimulation.r5.SimEventList	getEventList() Gets the underlying event list of this SimEntity.
double	getLastUpdateTime() Gets the time of the last update of this entity.
Set<SimEntitySimpleEventType.Member>	getRegisteredNotificationTypes() Gets the registered notification types of this entity.
Set<SimEntityOperation>	getRegisteredOperations() Gets the registered operations of this entity.
Set<SimEntityListener>	getSimEntityListeners() Gets the listeners to this entity.
SimEntity.UnknownNotificationTypePolicy	getUnknownNotificationTypePolicy() Returns the policy for unknown notifications types.
SimEntity.UnknownOperationPolicy	getUnknownOperationPolicy() Returns the policy for unknown operations.
boolean	isIgnoreEventListReset() Returns whether this entity ignores event-list resets.
void	registerSimEntityListener(SimEntityListener listener) Registers a listener to event notifications related to this entity.
void	resetEntity() Puts the entity into its "known" initial state.
void	setIgnoreEventListReset(boolean ignoreEventListReset) Sets whether this entity ignores future event-list resets.
void	setName(String name) Sets the name of this SimEntity, to be returned by subsequent calls to Object.toString ().
void	setUnknownNotificationTypePolicy(SimEntity.UnknownNotificationTypePolicy unknownNotificationTypePolicy) Sets the policy for unknown notifications types.
void	setUnknownOperationPolicy(SimEntity.UnknownOperationPolicy unknownOperationPolicy) Sets the policy for unknown operations.
String	toStringDefault() Returns a default name for this SimEntity.
void	unregisterSimEntityListener(SimEntityListener listener) Unregisters a listener to event notifications related to this entity.
void	update(double time) Updates this entity.

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

notifyEventListReset

Method Detail

getEventList

org.javades.jsimulation.r5.SimEventList getEventList()

Gets the underlying event list of this SimEntity.

The event list is passed upon construction of the object, and cannot be changed afterwards. It may be null.

If the event list is non-null, implementations must register at it as a SimEventListResetListener, and propagate any reset of the event list through resetEntity().

Returns:

The underlying event list of this SimEntity.

toStringDefault

String toStringDefault()

Returns a default name for this SimEntity.

The naming framework of an entity is as follows:

• The name of an entity never affects its functional behavior, nor that of other entities, apart from generated output for diagnostics, presentation or debugging.
• It is recommended to not make Object.toString () implementations final; users should always have the option to give useful (to them) names to entities by using the conventional approach of overriding Object.toString ().
• Implementations should use Object.toString () for String representations of an entity (following Java conventions).
• It is recommended that default implementations (see, for instance,AbstractSimEntity.toString()) of Object.toString return
  • the String set by setName(java.lang.String), or, if not set,
  • the String returned by toStringDefault() as set (and often made final by the implementation class(es), or, if not set,
  • the String returned by Object.toString().
• This approach ensures that users of an entity can easily set the name of an individual entity through setName(java.lang.String) or by overriding (if still possible) Object.toString(). At the same time, if a user chooses to not care about naming, a type-specific (typically "short") meaningful description String of the entity is used.

In other words, the string is to be returned by (concrete) implementations of toStringDefault() acts as a fallback return value for Object.toString () in case the user did not set an instance-specific name through setName(java.lang.String).

Implementations are recommended to not make this method final unless the class itself is final. The recommendation same holds for Object.toString ().

Returns:

A default name for this SimEntity.

See Also:

setName(java.lang.String), Object.toString()

setName

void setName(String name)

Sets the name of this SimEntity, to be returned by subsequent calls to Object.toString ().

Parameters:

name - The new name of this job or queue; if non-null, the string will be returned by subsequent calls to Object.toString () (recommended implementation!); otherwise, the type-specific default toStringDefault() will be used for that.

See Also:

toStringDefault()

getRegisteredOperations

Set<SimEntityOperation> getRegisteredOperations()

Gets the registered operations of this entity.

Returns:

The registered operations at this entity (in registration-time order).

See Also:

SimEntityOperation

getUnknownOperationPolicy

SimEntity.UnknownOperationPolicy getUnknownOperationPolicy()

Returns the policy for unknown operations.

Returns:

The policy for unknown operations, non-null.

See Also:

SimEntityOperation, doOperation(double, Req)

setUnknownOperationPolicy

void setUnknownOperationPolicy(SimEntity.UnknownOperationPolicy unknownOperationPolicy)

Sets the policy for unknown operations.

Parameters:

unknownOperationPolicy - The new policy for unknown operations, non-null.

Throws:

IllegalArgumentException - If the argument is null.

See Also:

SimEntityOperation, doOperation(double, Req)

doOperation

<O extends SimEntityOperation,Req extends SimEntityOperation.Request,Rep extends SimEntityOperation.Reply> Rep doOperation(double time,
                                                                                                                           Req request)

Performs the given operation, identified by an operation request, at this entity at given time.

If the operation is unknown, the course of action is as determined by getUnknownOperationPolicy().

Type Parameters:

O - The operation type.

Req - The request type (corresponding to the operation type).

Rep - The reply type (corresponding to the operation type).

Parameters:

time - The time at which to perform the operation.

request - The operation request (holds operation type as well).

Returns:

The operation reply, non-null unless the request was unknown and ignored.

Throws:

IllegalArgumentException - If time is in the past, if the request is null, illegally structured, or contains illegal arguments, or if the corresponding operation is not registered and the policy is not to accept that.

See Also:

getRegisteredOperations(), SimEntity.UnknownOperationPolicy, getUnknownOperationPolicy()

getRegisteredNotificationTypes

Set<SimEntitySimpleEventType.Member> getRegisteredNotificationTypes()

Gets the registered notification types of this entity.

Returns:

The registered notifications types of this entity (in registration order).

doAfterNotifications

void doAfterNotifications(SimEntity.Action action)

Registers an SimEntity.Action to be taken once this entity has finished issuing notifications, or takes the action immediately if this entity is not notifying listeners.

Parameters:

action - The action to take, non-null.

Throws:

IllegalArgumentException - If the action is null.

getUnknownNotificationTypePolicy

SimEntity.UnknownNotificationTypePolicy getUnknownNotificationTypePolicy()

Returns the policy for unknown notifications types.

Returns:

The policy for unknown operations, non-null.

setUnknownNotificationTypePolicy

void setUnknownNotificationTypePolicy(SimEntity.UnknownNotificationTypePolicy unknownNotificationTypePolicy)

Sets the policy for unknown notifications types.

Parameters:

unknownNotificationTypePolicy - The new policy for unknown notification types, non-null.

Throws:

IllegalArgumentException - If the argument is null.

registerSimEntityListener

void registerSimEntityListener(SimEntityListener listener)

Registers a listener to event notifications related to this entity.

Implementations are encouraged to consider the use of weak/soft references to registered listeners.

Parameters:

listener - The listener; ignored if already registered or null.

See Also:

SimEntityListener, unregisterSimEntityListener(org.javades.jqueues.r5.entity.SimEntityListener), getSimEntityListeners()

unregisterSimEntityListener

void unregisterSimEntityListener(SimEntityListener listener)

Unregisters a listener to event notifications related to this entity.

Parameters:

listener - The listener; ignored if not registered or null.

See Also:

SimEntityListener, registerSimEntityListener(org.javades.jqueues.r5.entity.SimEntityListener), getSimEntityListeners()

getSimEntityListeners

Set<SimEntityListener> getSimEntityListeners()

Gets the listeners to this entity.

Callers must not attempt to change the returned set.

Implementations are encouraged to return read-only views.

Returns:

A read-only set holding listeners to this entity.

See Also:

SimEntityListener, registerSimEntityListener(org.javades.jqueues.r5.entity.SimEntityListener), unregisterSimEntityListener(org.javades.jqueues.r5.entity.SimEntityListener), getSimEntityListeners()

isIgnoreEventListReset

boolean isIgnoreEventListReset()

Returns whether this entity ignores event-list resets.

Returns:

Whether this entity ignores event-list resets.

See Also:

setIgnoreEventListReset(boolean)

setIgnoreEventListReset

void setIgnoreEventListReset(boolean ignoreEventListReset)

Sets whether this entity ignores future event-list resets.

By contract, a SimEntity must reset with resetEntity() whenever the underlying event list (if present) is reset. The normal procedure to achieve this is to register as a SimEventListResetListener, and invoke resetEntity() upon SimEventListResetListener.notifyEventListReset(org.javades.jsimulation.r5.SimEventList).

There are cases, however, in which resetting this entity has to be delegated to another entity (or other type of object listening to the event list), for instance because the order in which entities are reset is important. Through this method, the automatic resetting of this entity upon an event-list reset can be disabled. Note, however, that the contract remains that the entity has to follow event-list resets.

Parameters:

ignoreEventListReset - Whether this entity ignores future event-list resets.

See Also:

isIgnoreEventListReset(), SimEventListResetListener.notifyEventListReset(org.javades.jsimulation.r5.SimEventList)

resetEntity

void resetEntity()

Puts the entity into its "known" initial state.

This method is used in order to restart a simulation. By contract, a SimEntity must reset if its underlying SimEventList resets. However, a SimEntity can also be reset independently from the event list. In the latter case, it takes its current time from the event list, if available, or to Double.NEGATIVE_INFINITY otherwise.

Implementations must ensure that only a single SimEntityListener.notifyResetEntity(org.javades.jqueues.r5.entity.SimEntity) is invoked after the entity is in the new (valid) state.

See Also:

SimEventListResetListener.notifyEventListReset(org.javades.jsimulation.r5.SimEventList)

getLastUpdateTime

double getLastUpdateTime()

Gets the time of the last update of this entity.

Upon construction, the last-update time must be set to minus infinity, mimicking the behavior of SimEventList. Upon an explicit reset of this entity, the last-update time is to be copied from the event list, if available (or reset to Double.NEGATIVE_INFINITY otherwise). In all other cases, the time returned corresponds to the time argument of the last update of the entity, see SimEntityListener.notifyUpdate(double, org.javades.jqueues.r5.entity.SimEntity) for more details.

Returns:

The time of the last update of this entity.

See Also:

AbstractSimEntity.update(double), SimEntityListener.notifyUpdate(double, org.javades.jqueues.r5.entity.SimEntity)

update

void update(double time)

Updates this entity.

For a precise definition of an update of an entity, refer to SimEntityListener.notifyUpdate(double, org.javades.jqueues.r5.entity.SimEntity).

Parameters:

time - The time of the update (the new time on the entity).

Throws:

IllegalStateException - If time is in the past.

See Also:

getLastUpdateTime(), SimEntityListener.notifyUpdate(double, org.javades.jqueues.r5.entity.SimEntity)