manager
Class LocalManager

java.lang.Object
  manager.LocalManager

All Implemented Interfaces:

uchicago.src.sim.engine.SimEventListener

public class LocalManager
extends java.lang.Object
implements uchicago.src.sim.engine.SimEventListener

This is the primary interface for the distributed executive which is exported to the local model. From a modeller's perspective, the most important function the LocalManager serves are the registration of local objects and the discovery of remote objects registered by other HLA_RePast instances. In addition to these visible functions, the LocalManager coordinates the creation and joining of the federation as well as constrained time-advance and conflict resolution (via ownership-management). Because the LocalManager performs reference tracking by interfacing with the local JVM (to automate object deletion) it is implemented as a singleton class and should only be accessed statically.

Author:

Rob Minson

Field Summary

protected Advancer13	advancer The Advancer13 used to manage the time-advance of this manager
protected manager.CallbackBuffer	cbDispatcher The dispatcher is the FederateAmbassador interface provided to the RTI, it filters incoming calls, cloning significant objects and equeing the callbacks in this manager's externQueue
protected java.lang.Class[]	classes The set of classes this federate will be using to represent objects in the simulation (this includes both local and proxy objects).
protected ClassLookup	classLookup A mapping of handles to variable names and vice-versa, is resolved on a simulation-by-simulation basis at the beginning of a fedex.
protected Coupler	coupler The Coupler used to constrain the initialisation of this manager
protected boolean	create Indicates whether this federate tried (or should try) to create the federation execution.
protected manager.EventQueue	externQueue The recipient of all events incoming from the RTI.
protected java.lang.String	federateID The id for this federate
protected java.lang.String	federationName The name of this federate execution
protected java.lang.String	fedFile The full path of the .fed file to use in this federation
protected java.lang.Class[]	fedTree The initial declaration of classes reflected or published by the local simulation
protected boolean	isLeader Indicates whether this federate was elected leader during the federation coupling process.
protected static java.net.InetAddress	localhost The IPv4 address of the host machine.
protected uchicago.src.sim.engine.SimModel	model The RePast model which this Manager is hosting
protected int	numNodes The number of nodes in the federation in total if the coupling process completed succesfully.
protected ObjectLookup	obLookup A large catalogue of all published and discovered objects in the federation about which the local simulation is interested.
protected hla.rti13.java1.RTIambassador	rtiAmb The RTIambassador which this Manager is communicating with
protected java.sql.Timestamp	sessionID The session_id for this execution, used purely for logging
protected static LocalManager	singletonManager A singleton instance (one LocalManager per JVM)

Constructor Summary

protected

LocalManager(java.lang.Class[] classes, int numNodes, java.lang.String federateID, java.lang.String fedName, java.lang.String fedFile, boolean create) Creates the skeleton of a LocalManager, establishing only the basic machinery for two-way communication with the RTI.

Method Summary

void	addLogicalTimeListener(LogicalTimeListener ltl) Register a listener which will be notified whenever this federate is granted to advance its clock.
void	constrainedEnabled(double time)
protected void	couple()
static LocalManager	createManager(java.lang.Class[] classes, int numNodes, java.lang.String federationName, java.lang.String fedFile) This is the same as the larger form but sets the federate's ID to the local host name.
static LocalManager	createManager(java.lang.Class[] classes, int numNodes, java.lang.String federateID, java.lang.String federationName, java.lang.String fedFile) This form is the same as the larger form but always tries to create the federation.
static LocalManager	createManager(java.lang.Class[] classes, int numNodes, java.lang.String federateID, java.lang.String federationName, java.lang.String fedFile, boolean create) Creates a LocalManager.
void	deletePublicObject(PublicObject obj) Explicitly delete the (locally registered) public object from the federation.
protected void	endParticipation()
void	endParticipation(boolean destroy) Resign from the federation, removing all objects created and registered in the past by this federate.
void	flushCallbackBuffer()
void	flushExternalEventQueueSngThrd()
hla.rti13.java1.RTIambassador	getAmbassador() Left public for development code (should not be needed by model code)
java.lang.String	getFederateID() The String id for this federate (not necessarily unique).
java.lang.String	getFederationName() The name of the federation.
static hla.rti13.java1.AttributeHandleSet	getHandleSet(int size)
static java.lang.String	getHost() Returns the hostname of the local machine
static LocalManager	getManager() Get the LocalManager for this JVM.
ProxyList	getProxies(java.lang.Class global, java.lang.Class local) Obtains a list of objects of type local which are reflecting remotely published instances of type global.
static hla.rti13.java1.RTIambassador	getRTI() Accesses the RTIambassador object itself.
DistributedSchedule	getSchedule() Obtains a RePast Schedule object that has been modified to comply with distributed operation (i.e.
java.sql.Timestamp	getSessionID() The session ID for this federation (should be unique for each federation execution, generated by the (randomly chosen) federation leader during the coupling process)
static hla.rti13.java1.SuppliedAttributes	getSuppliedAttributes(int size)
double	getTick()
protected void	initDatabase()
protected void	join()
protected void	print(java.lang.String message) Print the given message to an appropriate output/log.
void	registerPublicObject(PublicObject obj) Register a PublicObject with this LocalManager, handles registration of the object amongst the federation and sets certain accounting info for the object.
static void	setLazyDeletion(boolean lazy)
void	simEventPerformed(uchicago.src.sim.engine.SimEvent evt) Called by a simulation when a simulation-level event occurs (i.e.

Methods inherited from class java.lang.Object

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

Field Detail

localhost

protected static java.net.InetAddress localhost

The IPv4 address of the host machine.

singletonManager

protected static LocalManager singletonManager

A singleton instance (one LocalManager per JVM)

federateID

protected java.lang.String federateID

The id for this federate

federationName

protected java.lang.String federationName

The name of this federate execution

fedFile

protected java.lang.String fedFile

The full path of the .fed file to use in this federation

isLeader

protected boolean isLeader

Indicates whether this federate was elected leader during the federation coupling process. This is an HLA_RePast-specific piece of information and currently is simply used to ensure the simulation does not start until all federates are joined. It can be re-used for any other algorithms which require leader-election however as there is a guarantee that only one federate will have this variable set to 'true'.

create

protected boolean create

Indicates whether this federate tried (or should try) to create the federation execution. At least one of the federates should have this variable set to true.

See Also:

LocalManager(Class[], int, String, String, String, boolean)

numNodes

protected int numNodes

The number of nodes in the federation in total if the coupling process completed succesfully.

classes

protected java.lang.Class[] classes

The set of classes this federate will be using to represent objects in the simulation (this includes both local and proxy objects).

sessionID

protected java.sql.Timestamp sessionID

The session_id for this execution, used purely for logging

model

protected uchicago.src.sim.engine.SimModel model

The RePast model which this Manager is hosting

rtiAmb

protected hla.rti13.java1.RTIambassador rtiAmb

The RTIambassador which this Manager is communicating with

coupler

protected Coupler coupler

The Coupler used to constrain the initialisation of this manager

advancer

protected Advancer13 advancer

The Advancer13 used to manage the time-advance of this manager

fedTree

protected java.lang.Class[] fedTree

The initial declaration of classes reflected or published by the local simulation

classLookup

protected ClassLookup classLookup

A mapping of handles to variable names and vice-versa, is resolved on a simulation-by-simulation basis at the beginning of a fedex.

externQueue

protected manager.EventQueue externQueue

The recipient of all events incoming from the RTI. They arrive in the extern queue during time advance and are then all executed during the normal execution of the RePast schedule.

obLookup

protected ObjectLookup obLookup

A large catalogue of all published and discovered objects in the federation about which the local simulation is interested.

cbDispatcher

protected manager.CallbackBuffer cbDispatcher

The dispatcher is the FederateAmbassador interface provided to the RTI, it filters incoming calls, cloning significant objects and equeing the callbacks in this manager's externQueue

Constructor Detail

LocalManager

protected LocalManager(java.lang.Class[] classes,
                       int numNodes,
                       java.lang.String federateID,
                       java.lang.String fedName,
                       java.lang.String fedFile,
                       boolean create)
                throws hla.rti13.java1.RTIexception,
                       java.net.UnknownHostException,
                       BadClassTreeException,
                       java.lang.ClassNotFoundException

Creates the skeleton of a LocalManager, establishing only the basic machinery for two-way communication with the RTI. The join(), couple() and initDatabase() methods can then be used to create and join the federation in a stable way.

Parameters:

classes - the set of classes which will be instantiated in the local model as either PublicObject or RemoteObject instances (or both).

numNodes - the total number of nodes which will be involved in this federation.

federateID - the unique ID String of this federate. Does not need to be unique but may be useful for debugging output.

fedName - the name of the federation to create/join

fedFile - the .fed file to use to configure this federation. This must contain the standard HLA_RePast object types needed to gracefully couple of the federates together (see Coupler)

create - whether this federate should attempt to create the federation execution. At least one of the federates should have this argument set to true. The LocalManager will handle the case of multiple federates attempting to create, but initialisation will probably be slightly quicker if only one does so.

Throws:

hla.rti13.java1.RTIexception - If any error occurs from the RTIambassador calls.

java.net.UnknownHostException - If there is a problem attempting to obtain the local host machine's IP address.

java.lang.ClassNotFoundException

BadClassTreeException

Method Detail

getRTI

public static hla.rti13.java1.RTIambassador getRTI()
                                            throws java.lang.IllegalStateException

Accesses the RTIambassador object itself. (Should not be needed by modeller code.)

Returns:

the raw RTIambassador

Throws:

java.lang.IllegalStateException

getHost

public static java.lang.String getHost()

Returns the hostname of the local machine

Returns:

the local, fully qualified host name

Throws:

java.net.UnknownHostException

getManager

public static LocalManager getManager()

Get the LocalManager for this JVM.

Returns:

setLazyDeletion

public static void setLazyDeletion(boolean lazy)

join

protected void join()
             throws hla.rti13.java1.RTIexception

Throws:

hla.rti13.java1.RTIexception

couple

protected void couple()
               throws hla.rti13.java1.RTIexception

Throws:

hla.rti13.java1.RTIexception

initDatabase

protected void initDatabase()
                     throws hla.rti13.java1.RTIexception

Throws:

hla.rti13.java1.RTIexception

createManager

public static LocalManager createManager(java.lang.Class[] classes,
                                         int numNodes,
                                         java.lang.String federateID,
                                         java.lang.String federationName,
                                         java.lang.String fedFile,
                                         boolean create)
                                  throws java.lang.Exception

Creates a LocalManager. Once the call returns without exception, the local machine will be joined to a federation involving numNodes-1 other instances of HLA_RePast.

Parameters:

classes - the set of classes which will be instantiated in the local model as either PublicObject or RemoteObject instances (or both).

numNodes - the total number of nodes which will be involved in this federation.

federateID - the unique ID String of this federate. Does not need to be unique but may be useful for debugging output.

federationName - the name of the federation to create/join

fedFile - the .fed file to use to configure this federation. This must contain the standard HLA_RePast object types needed to gracefully couple of the federates together (see Coupler)

create - whether this federate should attempt to create the federation execution. At least one of the federates should have this argument set to true. The LocalManager will handle the case of multiple federates attempting to create, but initialisation will probably be slightly quicker if only one does so.

Returns:

A LocalManager connected to the required federation

Throws:

hla.rti13.java1.RTIexception - If any error occurs from the RTIambassador calls.

java.net.UnknownHostException - If there is a problem attempting to obtain the local host machine's IP address.

java.lang.Exception

createManager

public static LocalManager createManager(java.lang.Class[] classes,
                                         int numNodes,
                                         java.lang.String federateID,
                                         java.lang.String federationName,
                                         java.lang.String fedFile)
                                  throws java.lang.Exception

This form is the same as the larger form but always tries to create the federation.

Parameters:

classes -

numNodes -

federateID -

federationName -

fedFile -

Returns:

a LocalManger connected to the required federation

Throws:

java.lang.Exception

See Also:

createManager(Class[], int, String, String, String, boolean)

createManager

public static LocalManager createManager(java.lang.Class[] classes,
                                         int numNodes,
                                         java.lang.String federationName,
                                         java.lang.String fedFile)
                                  throws java.lang.Exception

This is the same as the larger form but sets the federate's ID to the local host name.

Parameters:

classes -

numNodes -

federationName -

fedFile -

Returns:

a LocalManager, connected to the required federation

Throws:

java.lang.Exception

See Also:

createManager(Class[], int, String, String, String, boolean)

getAmbassador

public hla.rti13.java1.RTIambassador getAmbassador()

Left public for development code (should not be needed by model code)

Returns:

the ambassador currently being used by this LocalManager

getHandleSet

public static hla.rti13.java1.AttributeHandleSet getHandleSet(int size)
                                                       throws hla.rti13.java1.MemoryExhausted,
                                                              hla.rti13.java1.ValueCountExceeded

Returns:

an AttributeHandleSet obtained from the RTIambassador.

Throws:

hla.rti13.java1.MemoryExhausted

hla.rti13.java1.ValueCountExceeded

getSuppliedAttributes

public static hla.rti13.java1.SuppliedAttributes getSuppliedAttributes(int size)
                                                                throws hla.rti13.java1.MemoryExhausted,
                                                                       hla.rti13.java1.ValueCountExceeded,
                                                                       hla.rti13.java1.HandleValuePairMaximumExceeded

Parameters:

size - the size of the SuppliedAttributes enumeration

Returns:

a SuppliedAttributes enumeration for passing attribute values

Throws:

hla.rti13.java1.MemoryExhausted

hla.rti13.java1.ValueCountExceeded

hla.rti13.java1.HandleValuePairMaximumExceeded

getTick

public double getTick()

Returns:

the current time recorded for this federate.

getFederateID

public java.lang.String getFederateID()

The String id for this federate (not necessarily unique).

Returns:

the federate's ID

getFederationName

public java.lang.String getFederationName()

The name of the federation.

Returns:

the federation's name

getSessionID

public java.sql.Timestamp getSessionID()

The session ID for this federation (should be unique for each federation execution, generated by the (randomly chosen) federation leader during the coupling process)

Returns:

the randomly generated unique ID for this federation execution (useful for logging etc.)

getSchedule

public DistributedSchedule getSchedule()
                                throws hla.rti13.java1.RTIexception

Obtains a RePast Schedule object that has been modified to comply with distributed operation (i.e. it advances in constraint with the federation). An HLA_RePast model MUST use a Schedule object obtained in this way. If a standard schedule is used, time advance will be unconstrained, and, most probably, the simulation will stop making sense very quickly. That said, time-constrained schedule execution is not a guarantee of semantically correct execution, conflict-resolution semantics and object registration must be correctly used as well.

Returns:

the Schedule object for use with the host model

Throws:

hla.rti13.java1.RTIexception

flushCallbackBuffer

public void flushCallbackBuffer()

flushExternalEventQueueSngThrd

public void flushExternalEventQueueSngThrd()

registerPublicObject

public void registerPublicObject(PublicObject obj)
                          throws hla.rti13.java1.RTIexception,
                                 java.io.IOException,
                                 BadClassException

Register a PublicObject with this LocalManager, handles registration of the object amongst the federation and sets certain accounting info for the object. Whilst it is not generally advisable for a PublicObject to interact with a local simulation before registration it is allowable, providing an effort is made to reach a stable point before registration. As a general rule it is advisable to register PublicObjects as the last command of a constructor.

Throws:

hla.rti13.java1.RTIexception

java.io.IOException

BadClassException

deletePublicObject

public void deletePublicObject(PublicObject obj)
                        throws hla.rti13.java1.RTIexception,
                               ObjectNotFoundException

Explicitly delete the (locally registered) public object from the federation.

Parameters:

obj - the object to delete

Throws:

ObjectNotFoundException - if the object with the given handle was never registered or if it was registered but has already been deleted. (The only situation in which the latter might happen is if the object is cloned, then the original object is garbage collected. If you are doing this, stop it, nobody is impressed.)

hla.rti13.java1.RTIexception - in several cases, though if the federation is still running happily, this is probably due to a failure in sanity checking in the internal HLA_RePast engine code leading to a delete call on a non-existent object.

getProxies

public ProxyList getProxies(java.lang.Class global,
                            java.lang.Class local)
                     throws hla.rti13.java1.FederateInternalError,
                            hla.rti13.java1.RTIinternalError,
                            java.lang.InstantiationException,
                            java.lang.IllegalAccessException

Obtains a list of objects of type local which are reflecting remotely published instances of type global. This list will be of indeterminate size and will most likely begin empty (particularly if this is done towards the beginning of an execution) and will grow as more objects are published and discovered. This list is not synchronized but provided access is only made to it in the execute() methods of scheduled BasicActions there will be no concurrency issues.

Note that although global and local need not be unique, if the public attributes retrievable from local are not a strict subset of those retrievable from global, this list will remain at size 0 for ever.

Parameters:

global - the Class of the objects as they were published remotely

local - the Class of the objects as they are to be stored in the list.

Returns:

a ReflectedList object populated with some number of instances of class local.

Throws:

BadClassException - if either class is not supported by this manager's internal database (i.e. if the Class[] it was initialised with does not contain one of the two classes).

hla.rti13.java1.FederateInternalError

hla.rti13.java1.RTIinternalError

java.lang.InstantiationException

java.lang.IllegalAccessException

simEventPerformed

public void simEventPerformed(uchicago.src.sim.engine.SimEvent evt)

Called by a simulation when a simulation-level event occurs (i.e. not an 'event' within a simulation, but an exterior event, such as the pausing or destroying of a simulation).

Specified by:

simEventPerformed in interface uchicago.src.sim.engine.SimEventListener

Parameters:

evt - the SimEvent type that has occurred

endParticipation

public void endParticipation(boolean destroy)

Resign from the federation, removing all objects created and registered in the past by this federate. A more powerful version of this method call is made when the RePast STOP_EVENT or END_EVENT events are received from the engine. Therefore modeller code should not need to independetly call this method. An exeptional circumstance may be if the model wishes to do more processing after resignation without producing a STOP_ or END_EVENT. Note that, in this case, more hacking will be required since the DistributedSchedule that has been used up to this point will not advance forward in time after this call has returned.

Parameters:

destroy - Also attempt to destroy the federation execution itself

endParticipation

protected void endParticipation()

addLogicalTimeListener

public void addLogicalTimeListener(LogicalTimeListener ltl)

Register a listener which will be notified whenever this federate is granted to advance its clock. This should be used by internal engine components which wish to interact directly with the process of time advance. Model code which wishes to simply do 'something' model-wise at a specific tick should *always* use the standard RePast scheduling procedures. Hijacking this method to execute arbitrary code in the model is not correct useage and will almost certainly result in unexpected results as the model is changed out-of-band with the synchronisation algorithm.

Parameters:

ltl - the listener

constrainedEnabled

public void constrainedEnabled(double time)

print

protected void print(java.lang.String message)

Print the given message to an appropriate output/log. For example if hasGui is false then message should be sent to System.out, if it returns true then in some cases it should go to a non-modal dialog

Parameters:

message - the message to print