Class SimObjectFactory<F extends SimObjectFactory<F,S,OBJ>,S extends Simulation,OBJ extends SimObject>

java.lang.Object
org.bzdev.obnaming.NamedObjectFactory<F,Simulation,SimObject,OBJ>
org.bzdev.devqsim.SimObjectFactory<F,S,OBJ>
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
AbstractSimObjFactory, AnimationObject2DFactory, DefaultSimObjectFactory, GenericActorFactory, GenericCondFactory, GenericDMFactory, GenericDomainFactory, GenericGroupFactory, GenericMsgFrwdngInfoFactory

public abstract class SimObjectFactory<F extends SimObjectFactory<F,S,OBJ>,S extends Simulation,OBJ extends SimObject> extends NamedObjectFactory<F,Simulation,SimObject,OBJ>
SimObjectFactory base class. The only parameters are the following:
  • "timeline" - an integer-keyed set of values that define changes in the object's configuration at specified pionts in simulation time. Subclasses may optionally provide additional parameters as described below. The default parameters are:
    • "timeline.time" - the time at which timeline parameters are to change. This parameter must be provided if a timeline entry exists. The units are those used by the double-precession time unit for the simulation (for animations, this is generally seconds).
    • "timeline.traceSetMode" - indicates how the parameter "timeline.traceSets" is interpreted. the values are enumeration constants of type TraceSetMode and are used as follows:
      • KEEP - keep the existing trace sets, adding additional ones specified by the parameter "timeline.traceSets".
      • REMOVE - remove the trace sets specified by the parameter "timeline.traceSets".
      • REPLACE - remove all existing trace sets and replace those with the ones specified by the timeline.traceSets parameter.
    • "timeline.traceSets" - a parameter representing a set of TraceSet objects (the three-argument 'add' method is used to add entries).
  • "traceSets" - a set of trace sets (class TraceSet) a SimObject will use for tracing. One should use the add and remove factory methods as this parameter refers to a set of values. This parameter provides the initial value for an object's trace sets. If this parameter or the corresponding timeline parameters are not used, an object will not have any trace sets.
This class also provides support for subclasses that add parameters to timelines. To add parameters to a timeline using annotations, a subclass will define an inner class (the name is arbitrary, but Timeline is a good choice). The following example shows how to' add a parameter named "foo" with a value that is a double-precision number. One starts with an inner class definition and a corresponding map for a keyed compound parameter with an integer key and name of "timeline":

        @CompoundParmType(tipResourceBundle = "*.lpack.TIP_NAME",
                          labelResourceBundle = "*.lpack.LABEL_NAME")
        static class TimelineEntry {
          @PrimitiveParm("foo") Double foo = null;
        }
        @KeyedCoumpoundParm("timeline")
        Map<Integer,TimelineEntry> timeline =
             new HashMap<Integer,Timeline>();
 
The result is that a new parameter named "timeline.foo" will be defined. The "timeline" parameter alone can be used to remove an entry or clear the tables. To implement this behavior, the annotation processor creates a Parm entry with the name "timeline" but uses a multi-argument constructor for its ParmParser entry.

Then one overrides a protected method named addToTimelineRequest which is required to call the same method with the same arguments on its superclass (nearly always, this should be the first statement):


        @Override
        protected void addToTimelineRequest(final OBJ obj,
                                           int key,
                                           double time)
        {
            super.addToTimelineRequest(obj, key, time);
            TimelineEntry entry = timelineMap.get(key);
            final boolean hasFoo = (entry.foo != null);
            final double foo = (hasFoo? entry.foo: 0.0);
            addToTimelineResponse(new Callable() {
                public void call() {
                    if (hasFoo) obj.setFoo(foo);
                }
            });
        }
 
Each addToTimelineRequest method that wishes to provide some code that will run at the specified time must call addToTimelineResponse with an argument that implements the interface org.bzdev.lang.Callable. In the example, the test of the value hasFoo results in no call to setFoo if the parameter was not defined. Be sure that the clear() method will clear the timeline table or unpredictable behavior may occur (this is done automatically if the timeline table is annotated for use with a parameter manager). While super.addToTimelineRequest must always be called in an overriding addToTimelineRequest method, the call to addToTimelineResponse may be omitted if one can determine that there is nothing for it to do. As a debugging hint, if addToTimelineRequest is not being called when a call is expected, check the initObject methods to make sure that each overrriden method calls super.initObject on the overridden method's argument:

        @Override
        protected void initObject(OBJ object) {
             super.initObject(object);
             ...
        }
 

In the example above, the class TimelineEntry was annotated with the CompoundParmType annotation. Classes with this annotation cannot have members with a CompoundParm annotation: for example


        @CompoundParmType(tipResourceBundle = "*.lpack.TIP_NAME",
                          labelResourceBundle = "*.lpack.LABEL_NAME")
        static class TimelineEntry {
          @PrimitiveParm("foo") Double foo = null;
          @CompoundParm("msgFontColor")
               ColorParm msgFontColor = new ColorParm();
        }
 
is illegal. To get the desired effect, use

        @CompoundParmType(tipResourceBundle = "*.lpack.TIP_NAME",
                          labelResourceBundle = "*.lpack.LABEL_NAME")
        static class TimelineEntry {
          @PrimitiveParm("foo") Double foo = null;
          @PrimitiveParm("msgFontColor.red")
             Integer red = null;
          @PrimitiveParm("msgFontColor.green")
             Integer green = null;
          @PrimitiveParm("msgFontColor.blue")
             Integer blue = null;
          @PrimitiveParm("msgFontColor.alpha")
             Integer alpha = null;
          @PrimitiveParm("msgFontColor.css")
             Integer css = null;
        }
 
and to allow msgFontColor to be restored to its default value, add a Parm instance explicitly in the constructor:

    initParm(new Parm("timeline.msgFontColor", int.class, null
                         new ParmParser() {
                             public void clear(int key) {
                                 TimelineEntry tle = timeline.get(key);
                                 if (tle != null) {
                                     tle.red = null;
                                     tle.green = null;
                                     tle.blue = null;
                                     tle.alpha = null;
                                 }
                             }
                         },
                         null,
                         null, true, null, true),
                 THIS_FACTORY_CLASS_NAME.class);
 
If msgFontColor is considered to be missing, the red, green, blue, and alpha fields will all be null. When overriding addToTimelineRequest(SimObject,int,double), one should set the color only if at least one of these four fields is not null.
  • Constructor Details

    • SimObjectFactory

      protected SimObjectFactory(S namer)
      Constructor.
      Parameters:
      namer - the simulation used to name objects.
  • Method Details

    • clear

      public void clear()
      Description copied from class: NamedObjectFactory
      Clear all entries and restore to default values. Note: each subclass that implements this method should call super.clear(). Any subclass that defines parameters should call this method in order to restore the parameters to their default values. When an annotation processor is used for some parameters, those parameters can be restored to their default value by calling the parm manager's setDefaults method with the factory as its argument.
      Overrides:
      clear in class NamedObjectFactory<F extends SimObjectFactory<F,S,OBJ>,Simulation,SimObject,OBJ extends SimObject>
    • getSimulation

      public S getSimulation()
      Get the simulation associated with a named-object factory.
      Returns:
      the simulation
    • initObject

      protected void initObject(OBJ object)
      Description copied from class: NamedObjectFactory
      Initialize an object. This method will call the methods for the object necessary to initialize it based on how the factory was configured, and is called by createObject() and createObjects unless these methods are overridden. The default method does nothing. Subclasses that override this method to provide subclass-specific initializations must start with the statement "super.initObject(object);".
      Overrides:
      initObject in class NamedObjectFactory<F extends SimObjectFactory<F,S,OBJ>,Simulation,SimObject,OBJ extends SimObject>
      Parameters:
      object - the object to initialize
    • addToTimelineRequest

      protected void addToTimelineRequest(OBJ object, int key, double time)
      Request subclasses to add entries to the timeline. Each subclass adding entries should create a Callable that performs any necessary operations at the specified time, and that Callable should be returned via a call to addToTimelineResponse. Each subclass that implements addToTimelineRequest must call super.addToTimelineRequest(object, key, time) as the first statement in addToTimelineRequest.
      Parameters:
      object - the object being configured.
      key - the timeline key
      time - the time for the timeline entry
    • addToTimelineResponse

      protected final void addToTimelineResponse(Callable callable)
      Allows a subclass to provide a Callable in response to a superclass calling addToTimelineRequest. The callable will be executed at the time associated with the timeline entry indexed by the key passed to addToTimelineRequest(OBJ, int, double).
      Parameters:
      callable - the Callable provided by the subclass.