RTIComponent Launcher

RTIComponent Launcher is an JDK 1.2 application to run components that exchange attributes of object and parameters of interactions. Components describe their interest to publish and subscribe objects in the federation executions with an XML formatted configuration file. Components should implement the RTIComponent interface. RTIComponent interface contains a method for setting the RTIContext object from which the component gets the MessagePublisher and MessageFactory object, and registers a MessageHandler object to receive the incoming calls. Other methods in RTIComponent are related to lifecycle.

RTIComponent DTD

<!ELEMENT object    (attribute*)>
<!ATTLIST object    name CDATA #REQUIRED>
<!ELEMENT attribute EMPTY>
<!ATTLIST attribute name CDATA #REQUIRED>
<!ATTLIST attribute callback CDATA #IMPLIED>
<!ELEMENT interaction (parameter*)>
<!ATTLIST interaction name CDATA #REQUIRED>
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter name CDATA #REQUIRED>
<!ATTLIST parameter callback CDATA #IMPLIED>
<!ELEMENT publish    (object|interaction)+>
<!ELEMENT subscribe  (object|interaction)+>
<!ELEMENT federation (publish?,subscribe?)>
<!ELEMENT RTIComponent (federation+)>
<!ATTLIST RTIComponent name CDATA #REQUIRED>

An example configuration file looks as follows:

<RTIComponent name="HelloWorlViewer">
 <federation name="HelloWorld"> 
  <publish> 
   <object name="Country"> 
    <attribute name="Name"/> 
    <attribute name="Population"/> 
   </object>  
   <interaction name="Communication"> 
    <parameter name="Message"/> 
   </interaction>  
  </publish> 
  <subscribe>
   <object name="Country"> 
    <attribute name="Name"/> 
    <attribute name="Population"/> 
   </object> 
   <interaction name="Communication"> 
    <parameter name="Message"/> 
   </interaction>  
  </subscribe> 
 </federation> 
</RTIComponent>

The component can specify the callback method name (parameter will be byte[]). For attribute updates, first parameter contains the instance identifier and the second parameter contains the byte[].

  <subscribe>
   <object name="Country"> 
    <attribute name="Name" callback="setName"/>
    <attribute name="Population" callback="setPopulation"/> 
   </object> 
   <interaction name="Communication"> 
    <parameter name="Message" callback="setMessage"/> 
   </interaction>  
  </subscribe> 
 

setName(int objectId, byte[] value);
setPopulation(int objectId, byte[] value);
setMessage(byte[] value);

It is also possible to mention only the object or interaction class name instead of enumerating all the attributes and parameters.

name attribute of RTIComponent element is used to give the class name. Instead, this information can be defined by another element as follows:

<implementation> 
 <classname>..</classname>
 <path>..</path>
 <jarfile>..</jarfile>
 <url>..</url>
</implementation> 

The following DTD definition should be added to the RTIComponent DTD description.

<!ELEMENT classname PCDATA>
<!ELEMENT path      PCDATA>
<!ELEMENT jarfile   PCDATA>
<!ELEMENT url       PCDATA>
<!ELEMENT implementation (classname,path*,jarfile*,url*)>

For configuration options, properties tag is defined. Component can access these settings from RTIContext.

<properties> 
 <attr name="">..</attr>
 <attr name="">..</attr>
</properties> 

<!ELEMENT attr       PCDATA>
<!ATTLIST attr       name CDATA #REQUIRED>
<!ELEMENT properties attr+>

xml.RTIComponentDocument contains this information.

The inital components are defined in components.xml file. Launcher loads the given components. This file conforms with the following syntax:

<components> 
 <component name=""> 
  <img file=""> 
  <filename> 
   <name>..</name> 
   <path>..</path> 
   <url>..</url> 
  </filename> 
 </component> 
</components> 

<!ELEMENT name       PCDATA>
<!ELEMENT path       PCDATA>
<!ELEMENT url        PCDATA>
<!ELEMENT filename   (name,path?,url?)>
<!ELEMENT img        EMPTY>
<!ATTLIST file       name CDATA #REQUIRED>
<!ELEMENT component  (img?,filename)>
<!ATTLIST component  name CDATA #REQUIRED>
<!ELEMENT components component*>

xml.ComponentsDocument contains this information.

Responsibilities of Component Developer

1. provide the configuration file,
2. provide an implementation of RTIComponent interface, and
3. provide an implementation of MessageHandler interface.

RTIComponent Launcher Internals

Launcher defines one FederationAmbassador per active federation. Launcher defines one RTIAmbassador. The interaction between container and components are Push-Push model.

Launcher defines message queues for:

1. Discover/RemoveObjectMessage queue,
2. UpdateAttributeMessage queue,
3. UpdateParameterMessage queue.

FederateAmbassador publishes Message objects to the proper queues based on the callback call from the RTI.

Launcher defines PullProxy for each component. PullProxy is registered by the Launcher to proper queues. PullProxy takes Messages from the queue and filters if necessary. After it decides that it need to inform the component, then it uses the proper CallbackInvoker object. CallbackInvoker (default) uses the handleMessage().

1. AggregatedFedAmbFactory : implements Factory and Finder patterns for AggregatedFedAmb objects. Uses FedNameToAmbMap object.

2. FedNameToAmbMap : keeps the mapping between the federation name and AggregatedFedAmb object.

3. AggregatedFedAmb : implements the FederateAmbassador interface. Contains information about the joining RTIComponents through this object. Contains remove/join methods. It will be removed when it is not serving any local RTIComponent. Defines three message queues (UpdateAttribute, UpdateParameter, Discover/RemoveObject). Contains methods to get the handle of these queues. Publishes RTI callbacks in Message format to the proper queues.

4. PullProxyFactory : Accepts the subscription definitions and produces a PullProxy object containing filtering.

5. RTIComponentLoader : Loads the component.

   It can load from:
   1. class files by using path and system path.
   2. class files by url.
   3. class files by using jar file from the given path.
   4. class files by using jar file from the given url.

6. ObjectInstanceMapper : Each component can have multiple instances. Each one of them are registered through this mapper. Each component contains a RTIContext object which contains the handle of MessageHandler object provided by the component.

7. RTIContextFactory : Factory pattern for RTIContext objects.

Messages

The interaction between the component and the container based on the following Message types:

1. DefineObjectMessage
2. DiscoverObjectMessage
3. RemoveObjectMessage
4. UpdateAttributeMessage
5. UpdateParameterMessage

DefineObjectMessage is send by the component when a new object is defined.

DiscoverObjectMessage is send to the component to inform the existence of that particular object.

RemoveObjectMessage is send to the component to informm that the object is removed.

UpdateAttributeMessage is send to/from the component to receive/update the attribute of a particular object.

UpdateParameterMessage is send to/from the component to receive/update the parameter of an interaction class.

Each message contains a source attribute:

null	:	came from the network
non-null	:	contains a reference to the component that actually pushed the message. PullProxy objects can filter the message by checking this field.

Class diagram for Message Types. InteractionMessage and ObjectMessage classes are abstract.

MessageFactory object has static methods to create a particular messages.

Factory object for Messages.

MessageFactory object is defined per federation. Each MessageFactory object knows the handle of:

1. RTIInteractionLookUp
2. RTIObjectClassAttributeLookUp

MessageFactory object throws an exception for invalid names (MessageException).

package lrti.rtidb;
RTIInteractionLookUp 
  getInteractionClassId(String);
  getInteractionClassName(id);
  getParameterId(String,String);
  getParameterName(String,id);

package lrti.rtidb;
RTIObjectClassAttributeLookUp 
  getObjectClassId(String);
  getObjectClassName(id);
  getObjectAttributeId(String,String);
  getObjectAttributeName(String,id);

package lrti.rtidb.inmem;
InMemRTIInteractionLookUp implements RTIInteractionLookUp
  Hashtable interactionName_to_record;
  Hashtable interactionId_to_record;

  getInteractionClassId(String);
  getInteractionClassName(id);
  getParameterId(String,String);
  getParameterName(String,id);

package lrti.rtidb.inmem;
RTIInteractionClassRecord
  String    interactionClassName;
  int       id;
  Hashtable parameterName_to_id;
  Hashtable id_to_parameterName;

  getInteractionClassId();
  getInteractionClassName();
  getParameterId(String);
  getParameterName(id);

package lrti.rtidb.inmem;
InMemRTIObjectClassAttributeLookUp  implements RTIObjectClassAttributeLookUp
  Hashtable objectClassName_to_record;
  Hashtable objectClassId_to_record;

  getObjectClassId(String);
  getObjectClassName(id);
  getObjectAttributeId(String,String);
  getObjectAttributeName(String,id);

package lrti.rtidb.inmem;
RTIObjectClassRecord
  String    objectClassName;
  int       id;
  Hashtable attributeName_to_id;
  Hashtable id_to_attributeName;

  getObjectClassId();
  getObjectClassName();
  getObjectAttributeId(String);
  getObjectAttributeName(id);

FederationDescription
  MessageFactory
  AggregatedFedAmb
  RTIContextFactory
  ObjectInstanceMapper

RTIContext
  MessageFactory
  MessagePublisher

Components implement the RTIComponent interface to be launched by the RTIComponent Launcher. RTIComponent interface contains the following methods:

1. setContext() :
2. Properties getProperties() : (or String getProperty(String))
3. created()
4. activated()
5. deactivated()
6. removed()

RTIContext interface contains:

1. registerMessageHandler()
2. MessageFactory getMessageFactory()
3. MessagePublisher getMessagePublisher()

MessageHandler interface contains:

1. handleMessage(Message inMsg) : the container uses this method to inform the component.

MessagePublisher interface contains only one method:

1. push(Message inMsg) : the component builds the message and publishes by using this object.

Interaction between container and component is based on two interfaces.

CallbackInvoker

CallbackInvoker object invokes the handleMessage() method on the component provided MessageHandler interface. It is obtained from CallbackInvokerFactory object. DCallbackInvoker object invokes the method provided by the component's MessageHandler implementation. If this method does not exist, it uses the invoke() method of its parent (CallbackInvoker).

Queues

Each queue object implements the Queue interface. Each AggregatedFedAmb object has at most three queues.

MessagePusher contains methods to push for all possible messages.

There can be only one MessagePusher object per federation. Each MessagePublisher object given to component shares the same MessagePusher object. (Better than handing out the queues all over the place.)

MessagePusher is an active object.

Client   MessagePublisher  MessagePusher    Q0   Q1   Q2   RTI
  --push()->    
               --push()--> 
                                (1) --push()--> 
                                (2) ------push()--> 
                                (3) ---------- push()--> 
                                (4) ------------- push()--> 

Each message publication causes one push() out of {1,2,3} and may be push() to RTI if there are other networked federates in the federation execution. This ensures that if there are no other networked federate , then there won't be any publishing to RTI. Meanwhile, other local components can receive them via the queues. The source attribute (of Message) is used to filter the message coming back to the originating component.

CallbackRegistry
void addCallback(String,String method_name)
String getCallback(String)

CallbackRegistry is a part of RTIComponentDocument. Object attribute name is followed with the qualified object class name(Country.name). Parameter name is preceded with the qualified interaction class name. RTIComponentDocument contains two CallbackRegistry object implementations: one for object and one for interactions.

CallbackRepository contains information about the method call that will be invoked when the message is received for a parameter or an attribute.

PullProxyImpl has a reference to FedPubSubInfo, RTIComponent, and CallbackRepository objects. PullProxyImpl is an active object.

RTIComponentDocument contains a mapping from federation name to FedPubSubInfo object.

capis.Command
void execute()

RTIContextImpl

1. load the component,
2. define the PullProxyImpl (contains filters)
3. define MessagePublisher (contains filters)

Classes and Interfaces

List of classes

src:
DebugFlags.java
GetName.java
LoadComponentForm.java
RTIComponentLoader.java
RTIContextImpl.java
RTILauncherGUI.java
app1.java
app1.xml
app2.java
app2.xml
components.xml
default.properties
doDir.java
doDir.xml
mainRTIDesktop.java
runJDIS.java
runJDIS.xml
runParCMSMon.java
runParCMSMon.xml
runSimVis.java
runSimVis.xml
runWinCmd.java
runWinCmd.xml
wincmd.exe

src/comprti:
MessageHandler.java
MessagePublisher.java
PullProxy.java
PullProxyRegistry.java
Queue.java
RTIComponent.java
RTIContext.java

src/comprti/cback:
CallbackInvoker.java
CallbackInvokerFactory.java
CallbackRepository.java
DCallbackInvoker.java

src/comprti/msg:
DefineObjectMessage.java
DeleteObjectMessage.java
DiscoverObjectMessage.java
InteractionMessage.java
Message.java
MessageFactory.java
ObjectMessage.java
UpdateAttributeMessage.java
UpdateParameterMessage.java

src/lrti:
FederationDefinition.java

src/lrti/rtidb:
RTIDBException.java
RTIInteractionLookUp.java
RTIObjectClassAttributeLookUp.java

src/lrti/rtidb/inmem:
InMemRTIInteractionLookUp.java
InMemRTIObjectClassAttributeLookUp.java
RTIInteractionClassRecord.java
RTIObjectClassRecord.java

src/queue:

src/util:
CallbackRegistry.java
Command.java

src/util/inmem:
InMemCallbackRegistry.java

src/xml:
BaseDocument.java
CommonRec.java
ComponentRecord.java
ComponentsConstants.java
ComponentsDocument.java
FedPubSubInfo.java
InterRec.java
ObjRec.java
RTIComponentConstants.java
RTIComponentDocument.java
XMLDebugFlags.java

MessagePublisherImpl

It is used by component to send a message out from the component. It extends from the BaseMessagePublisher.

MessagePusher

It dispatches the message to the proper Queues and the RTIMessagePusher.

RTIMessagePusher

It resolves the Message and calls the proper RTIambassador methods.

PullProxyImpl

It has a reference to PullQueue and CallbackRepository implementation. It uses CallbackInvoker objects to execute the callback on the object.

PushSupPullConQueue

FederationsRegistryImpl

Keeps the mapping from federation name to the FederationDefinition mapping. It has a reference to RTIKernelInterface.

BaseFedAmb

AggregatedFedAmb

It needs to register the incoming messages to the proper Queues. It has a handle to MessagePusher (without RTIMessagePusher).

CallbackInvokerFactory

CallbackRepository

keeps the default CallbackInvoker and a reference to MessageHandler object. It also keeps the Parameter and Attribute CallbackInvoker objects.

CallbackRepositoryFactory

It accepts a MessageHandler object and CallbackRegistry object and returns a CallbackRepository object.

MessageHandler

The component provides a MessageHandler interface implementation. This object is used for callback purposes.

MessagePublisher

A push method.

MessagePublisherRegistry

A registry pattern for MessagePublisher.

RTIComponent

RTIContext

RTIContextRegistry

Queue

PullProxy

PullProxyRegistry

PullQueue

extends Queue and PullProxyRegistry

FederationsRegistry