Interface ObjectNamerOps<TO extends NamedObjectOps>

All Known Implementing Classes:
Animation2D, DefaultObjectNamer, DramaSimulation, GenericSimulation, Simulation

public interface ObjectNamerOps<TO extends NamedObjectOps>
Operations provided by an object namer. Insertion and deletion of objects is handled by named-object classes and hence the operations object namers support involve just lookup operations. This interface, and the NamedObjectOps interface, are provided mostly for documentation as javadocs may not show the helper classes an annotation processor generates.
See Also:
  • Method Details

    • getNamedObjectClass

      Class<TO> getNamedObjectClass()
      Get the class common to all named objects.
      Returns:
      the class
    • getObject

      TO getObject(String name)
      Get an object from the object namer's tables.
      Parameters:
      name - the name of the object
      Returns:
      the object corresponding to the name provided
    • getObjectNames

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

      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.
      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
    • getObjects

      <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.
      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

      Collection<TO> getObjects()
      Get a collection of all the interned named objects associated with an object namer.
      Returns:
      an unmodifiable collection of the objects interned in the object namer's tables.
    • getObject

      <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.
      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
    • configureFactorySupported

      boolean configureFactorySupported()
      Determine if the configureFactory method is supported.
      Returns:
      true if configure() is supported; false otherwise
    • configureFactory

      void configureFactory(NamedObjectFactory factory, Object scriptObject) throws UnsupportedOperationException, IllegalArgumentException
      Configure a factory. This is an optional operation.
      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
    • createFactory

      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.

      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
    • createFactories

      default void createFactories(String pkg, Object scriptObject) throws UnsupportedOperationException, IllegalArgumentException
      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.

      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

      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.
      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

      NamedObjectFactory createFactory(Class clazz) throws IllegalArgumentException
      Create a factory given its class. The factory must have a single-argument constructor that takes its object namer as its argument.
      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
    • addObjectNamer

      void addObjectNamer(ObjectNamerOps<TO> altNamer)
      Add an alternative object namer for use by getObject methods. When called, the alternate object namer specified in the argument is added to a list of object namers that will be searched depth first when getObject cannot find an object with a given name in the current object namer's tables.
      Parameters:
      altNamer - the alternative object namer
    • checkAltList

      boolean checkAltList(ObjectNamerOps<TO> 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.
      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