Module org.bzdev.devqsim
Package org.bzdev.devqsim
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.
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@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>();
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):
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 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); } }); }
@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
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; @CompoundParm("msgFontColor") ColorParm msgFontColor = new ColorParm(); }
and to allow msgFontColor to be restored to its default value, add a Parm instance explicitly in the constructor:@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; }
If msgFontColor is considered to be missing, the red, green, blue, and alpha fields will all be null. When overridinginitParm(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);
addToTimelineRequest(SimObject,int,double)
, one should
set the color only if at least one of these four fields is not null.-
Nested Class Summary
Nested classes/interfaces inherited from class org.bzdev.obnaming.NamedObjectFactory
NamedObjectFactory.ConfigException, NamedObjectFactory.IndexedSetter, NamedObjectFactory.ParmNameIterator
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected void
addToTimelineRequest
(OBJ object, int key, double time) Request subclasses to add entries to the timeline.protected final void
addToTimelineResponse
(Callable callable) Allows a subclass to provide a Callable in response to a superclass calling addToTimelineRequest.void
clear()
Clear all entries and restore to default values.Get the simulation associated with a named-object factory.protected void
initObject
(OBJ object) Initialize an object.Methods inherited from class org.bzdev.obnaming.NamedObjectFactory
add, add, add, add, add, add, add, add, addDocResourceBundle, addDocResourceBundle, addJDoc, addJDoc, addLabelResourceBundle, addLabelResourceBundle, addTipResourceBundle, addTipResourceBundle, arrayInit, canAdd3, clear, configure, configureSupported, containsParm, createObject, createObject, createObject, createObject, createObjects, createObjects, createObjects, createObjects, createObjects, createObjects, doAfterInits, endObjectCreation, getDoc, getFactoryClass, getGLB, getLabel, getLayoutResource, getListedFactories, getLUB, getNextName, getNextNameIndex, getObjectNamer, getParmKeyType, getParmPrefix, getRVMode, getTemplateKeyMap, getTemplateKeyMapForFactories, getTemplateKeyMapForFactories, getTemplateKeyMapForFactories, getTip, getType, glbInRange, initParm, initParms, initParms, isClearOnly, isNamedObject, isRandomVariable, keyType, lubInRange, mustAdd, newConfigExceptionInstance, newConfigExceptionInstance, newConfigExceptionInstance, newConfigExceptionInstance, newConfigExceptionInstance, newConfigExceptionInstance, newConfigExceptionInstance, newInstance, newInstance, newObject, parmNames, parmNameSet, parmPrefixes, remove, remove, remove, remove, remove, remove, remove, remove, removeParm, removeParms, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, set, setDocAPIBase, setInterned, setLayoutResource, setLayoutResource, setNameRoot, setTarget, startObjectCreation, unset, unset, unset, unset, unset, unset, willIntern
-
Constructor Details
-
SimObjectFactory
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 callsuper.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 classNamedObjectFactory<F extends SimObjectFactory<F,
S, OBJ>, Simulation, SimObject, OBJ extends SimObject>
-
getSimulation
Get the simulation associated with a named-object factory.- Returns:
- the simulation
-
initObject
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 bycreateObject()
andcreateObjects
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 classNamedObjectFactory<F extends SimObjectFactory<F,
S, OBJ>, Simulation, SimObject, OBJ extends SimObject> - Parameters:
object
- the object to initialize
-
addToTimelineRequest
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 keytime
- the time for the timeline entry
-
addToTimelineResponse
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 toaddToTimelineRequest(OBJ, int, double)
.- Parameters:
callable
- the Callable provided by the subclass.
-