Class DramaSimulation

All Implemented Interfaces:
ObjectNamerOps<SimObject>

Top level class for a basic simulation. This class models the flow of time, handles scheduling of events, and provides tables that allow simulation objects to be looked up by name. It also allows named objects interned in the simulation's tables to be retrieved, with access methods for specific types of objects (Actors, etc.)
  • Constructor Details

    • DramaSimulation

      public DramaSimulation()
      Constructor.
    • DramaSimulation

      public DramaSimulation(double ticksPerUnitTime)
      Constructor with time-unit specification.
      Parameters:
      ticksPerUnitTime - the number of ticks per unit time
    • DramaSimulation

      public DramaSimulation(DramaFactory factory)
      Constructor providing a factory.
      Parameters:
      factory - the simulation factory
    • DramaSimulation

      public DramaSimulation(DramaFactory factory, double ticksPerUnitTime)
      Constructor providing a factory and unit-time specification. The factory argument is provided to allow the default factory to be replaced. The default factory is used to create DomainMember instances. A subclass might provide additional methods, for use in conjunction with a subclass of DramaSimulation.
      Parameters:
      factory - the simulation factory
      ticksPerUnitTime - the number of ticks per unit time
    • DramaSimulation

      public DramaSimulation(ScriptingContext parent)
      Constructor providing a parent. When a simulation has a parent, the simulation's scripting context is that of its parent unless specific methods are overridden. When a simulation has a parent that is also a Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them.
      Parameters:
      parent - the parent simulation or scripting context
    • DramaSimulation

      public DramaSimulation(ScriptingContext parent, double ticksPerUnitTime)
      Constructor providing a parent and time-unit specification. When a simulation has a parent, the simulation's scripting context is that of its parent unless specific methods are overridden. When a simulation has a parent that is also a Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them.
      Parameters:
      parent - the parent simulation or scripting context
      ticksPerUnitTime - the number of ticks per unit time
    • DramaSimulation

      public DramaSimulation(ScriptingContext parent, DramaFactory factory)
      Constructor with a parent and factory. When a simulation has a parent, the simulation's scripting context is that of its parent unless specific methods are overridden. When a simulation has a parent that is also a Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them.
      Parameters:
      parent - the parent simulation or scripting context.
      factory - the simulation factory
    • DramaSimulation

      public DramaSimulation(ScriptingContext parent, DramaFactory factory, double ticksPerUnitTime)
      Constructor with a parent, factory, and time-unit specification. When a simulation has a parent, the simulation's scripting context is that of its parent unless specific methods are overridden. When a simulation has a parent that is also a Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them.

      The factory argument is provided to allow the default factory to be replaced. The default factory is used to create DomainMember instances. A subclass might provide additional methods, for use in conjunction with a subclass of DramaSimulation.

      Parameters:
      parent - the parent simulation or scripting context.
      factory - the simulation factory
      ticksPerUnitTime - the number of ticks per unit time
  • Method Details

    • getActor

      public Actor getActor(String name)
      Get an actor.
      Specified by:
      getActor in class GenericSimulation<DramaSimulation,Actor,Condition,Domain,DomainMember,DramaFactory,Group>
      Parameters:
      name - the actor's name
      Returns:
      the actor; null if none with that name
    • getCondition

      public Condition getCondition(String name)
      Get an condition.
      Parameters:
      name - the condition's name
      Returns:
      the condition; null if none with that name
    • getDomain

      public Domain getDomain(String name)
      Get a domain.
      Specified by:
      getDomain in class GenericSimulation<DramaSimulation,Actor,Condition,Domain,DomainMember,DramaFactory,Group>
      Parameters:
      name - the domain's name
      Returns:
      the domain; null if none with that name
    • getDomainMember

      public DomainMember getDomainMember(String name)
      Get a domain member.
      Specified by:
      getDomainMember in class GenericSimulation<DramaSimulation,Actor,Condition,Domain,DomainMember,DramaFactory,Group>
      Parameters:
      name - the domain member's name
      Returns:
      the domain member; null if none with that name
    • getGroup

      public Group getGroup(String name)
      Get a group.
      Specified by:
      getGroup in class GenericSimulation<DramaSimulation,Actor,Condition,Domain,DomainMember,DramaFactory,Group>
      Parameters:
      name - the group's name
      Returns:
      the group; null if none with that name
    • getNamedObjectClass

      public Class<SimObject> getNamedObjectClass()
      Get the class common to all named objects.
      Specified by:
      getNamedObjectClass in interface ObjectNamerOps<SimObject>
      Returns:
      the class
    • addObjectNamer

      public final void addObjectNamer(ObjectNamerOps<SimObject> altNamer)
      Add an alternative object namer for use by getObject methods.
      Specified by:
      addObjectNamer in interface ObjectNamerOps<SimObject>
      Parameters:
      altNamer - the alternative object namer
    • checkAltList

      public boolean checkAltList(ObjectNamerOps<SimObject> altNamer)
      Determine if the argument is equal to this object namer or a member of this object namer's object-namer list. This test is recursive. It is specified in this interface for technical reasons, and is not intended to be called otherwise. It is called by addObjectNamer to ensure that a depth-first search will terminate.
      Specified by:
      checkAltList in interface ObjectNamerOps<SimObject>
      Parameters:
      altNamer - the object namer to test
      Returns:
      true if he argument is equal to this object namer or a member of this object namer's object-namer list, tested recursively; false otherwise
    • getObject

      public SimObject getObject(String name)
      Get an object from the object namer's tables.
      Specified by:
      getObject in interface ObjectNamerOps<SimObject>
      Parameters:
      name - the name of the object
      Returns:
      the object corresponding to the name provided
    • getObjectNames

      public Set<String> getObjectNames()
      Get all the object names from a object namer's tables.
      Specified by:
      getObjectNames in interface ObjectNamerOps<SimObject>
      Returns:
      a set containing the names of all objects interned in the object namer's tables
    • getObjectNames

      public Set<String> getObjectNames(Class<?> clazz)
      Get some the object names from a object namer's tables. The object names are those of objects for which either their classes or one of their superclasses match the class passed as an argument.
      Specified by:
      getObjectNames in interface ObjectNamerOps<SimObject>
      Parameters:
      clazz - the class of the objects whose names are to appear in the set returned
      Returns:
      a set containing the names of all objects interned in the object namer's tables such that the class of that object or the class of a subclass of that object matches the clazz argument
    • getObject

      public <T> T getObject(String name, Class<T> clazz)
      Get a named object with a particular name, provided that the object is a subclass of a specific class.
      Specified by:
      getObject in interface ObjectNamerOps<SimObject>
      Type Parameters:
      T - the type specified by the argument clazz
      Parameters:
      name - the name of the object
      clazz - the class of the object
      Returns:
      the object or null if the object cannot be found
    • getObjects

      public Collection<SimObject> getObjects()
      Get a collection of all the interned named objects assocated with an object namer.
      Specified by:
      getObjects in interface ObjectNamerOps<SimObject>
      Returns:
      an unmodifiable collection of the objects interned in the object namer's tables.
    • getObjects

      public <T> Collection<T> getObjects(Class<T> clazz)
      Get a set of objects from a object namer's tables. The objects are those for which either their classes or one of their superclasses match the class passed as an argument.
      Specified by:
      getObjects in interface ObjectNamerOps<SimObject>
      Type Parameters:
      T - the type specified by the argument clazz
      Parameters:
      clazz - the class of the objects to get.
      Returns:
      a collection containing all interned objects whose class or one of its superclasses matches the class clazz passed as the method's argument
    • getObjects

      public Collection<SimObject> getObjects(String className)
      Get a collection of objects with a class constraint, expressed as a class name, from a object namer's tables. The objects are those for which either their classes or one of their superclasses match the class passed as an argument.

      Note: this method is provided because script engines do not provide a standard way of denoting a Java class (the class not an instance of it). The collection it returns is a collection of the common named object type. Except for scripting languages that do not provide compile-time type checking, one should nearly always use ObjectNamerOps.getObjects(Class).

      Parameters:
      className - the fully qualified class name of the objects to get.
      Returns:
      an unmodifiable collection containing all interned objects whose class or one of its superclasses matches the class clazz passed as the method's argument; an empty (and unmodifiable) collection if no objects can be found
    • configureFactorySupported

      public boolean configureFactorySupported()
      Determine if the configureFactory method is supported.
      Specified by:
      configureFactorySupported in interface ObjectNamerOps<SimObject>
      Returns:
      true if configure() is supported; false otherwise
    • configureFactory

      public void configureFactory(NamedObjectFactory factory, Object scriptObject) throws UnsupportedOperationException, IllegalArgumentException
      Configure a factory. This is an optional operation.
      Specified by:
      configureFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      factory - the factory to be configured
      scriptObject - an object in a scripting language representing a specification for how this factory should be configured
      Throws:
      UnsupportedOperationException - the factory cannot be configured using a script object
      IllegalArgumentException - the scriptObject is ill formed
    • createFactories

      public void createFactories(String pkg, Object scriptObject) throws UnsupportedOperationException, IllegalArgumentException
      Description copied from interface: ObjectNamerOps
      Create multiple factories from a package in a single statement. The first argument is the fully qualified name of a package. The second is a scripting-language object specifying the individual factories and how they should be named. For the object-namer subclass Simulation and its subclasses (DramaSimulation and Animation2D are defined in this class library), the specification for ECMAScript is an ECMAScript objects whose property names are used as the name of a scripting language variable and whose value is a string containing the name of the factory class (excluding its package name, which is provided by the first argument). For example, with ECMAScript for one of these subclasses,
      
          a2d = new Animation2D(scripting, ...);
          a2d.createFactories("org.bzdev.anim2d", {
             alf: "AnimationLayer2DFactory",
             gvf: "GraphViewFactory"
          });
       
      will create two ECMAScript variables whose names are alf and gvf.

      Unless explicitly implemented, this method will throw an UnsupportedOperationException.

      Specified by:
      createFactories in interface ObjectNamerOps<SimObject>
      Parameters:
      pkg - the fully-qualified package name
      scriptObject - a scripting-language object specifying factories that should be created
      Throws:
      UnsupportedOperationException - this object namer does not support scripting or creating multiple factories specified by a scripting object
      IllegalArgumentException - an argument was not suitable for creating a factory.
    • createFactory

      public NamedObjectFactory createFactory(String varName, String packageName, String className) throws UnsupportedOperationException, IllegalArgumentException
      Create a factory and store it in a scripting-language variable. The factory must have a single-argument constructor that takes its object namer as its argument.

      This method is provided for convenience - to reduce the amount of typing when adding factories to a script. It returns the factory that was created in addition to storing it in a variable in case a user of this method tries to assign the value it returns.

      Specified by:
      createFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      varName - the name of a scripting-language variable
      packageName - the name of the package (null or an empty string for the unnamed package)
      className - the class name of a factory, excluding the package name
      Returns:
      the factory that was created
      Throws:
      IllegalArgumentException - the factory is not listed in a META-INF/services/org.bzdev.NamedObjectFactory resource or the class name does not refer to subclass of NamedObjectFactory
      UnsupportedOperationException - this object namer does not support scripting;
    • createFactory

      public NamedObjectFactory createFactory(String className) throws IllegalArgumentException
      Create a factory. The factory must have a single-argument constructor that takes its object namer as its argument.
      Specified by:
      createFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      className - the fully-qualified class name of a factory.
      Returns:
      a new factory
      Throws:
      IllegalArgumentException - the factory is not listed in a META-INF/services/org.bzdev.NamedObjectFactory resource or the class name does not refer to subclass of NamedObjectFactory
    • createFactory

      public NamedObjectFactory createFactory(Class clazz) throws IllegalArgumentException
      Create a factory given a class. The factory must have a single-argument constructor that takes its object namer as its argument.
      Specified by:
      createFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      clazz - the factory's class
      Returns:
      a new factory
      Throws:
      IllegalArgumentException - the factory is not listed in a META-INF/services/org.bzdev.NamedObjectFactory resource or the class name does not refer to subclass of NamedObjectFactory