Class ObjectNamerLauncher

java.lang.Object
org.bzdev.obnaming.ObjectNamerLauncher
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
DefaultLauncher, SimulationLauncher

public abstract class ObjectNamerLauncher extends Object implements AutoCloseable
Base class for object-namer launchers. An object-namer launcher allows on the process an instance of JSOps (e.g., aJSObject or a JSArray) to configure an application and run it as an alternative to using a scripting language in cases. The application is assumed to consist of an object namer, named objects, and named object factories. The ExpressionParser class is used to provide an ESP-like scripting environment, but without the ability to explicitly import Java classes. Examples of classes that have object-namer launchers are the org.bzdev.anim2d package, the org.bzdev.devqsim package, or the org.bzdev.drama package in cases for cases where factories and simple constructors can be used to create objects and where operations are simply sequences of expressions.

Please visit the object-namer launcher documentation and the manual page for the yrunner for additional information.

  • Constructor Details

  • Method Details

    • combine

      protected static JSObject combine(JSObject initializer1, JSObject... initializers)
      Merge two initializers. This is useful in constructors that combine their default initializer with an initilizer provided as an argument
      Parameters:
      initializer1 - the first initializer
      initializers - the remaining initializers
      Returns:
      the merger of the two initializers
    • loadFromStream

      protected static JSObject loadFromStream(Class<?> lclass, InputStream is, int tabspacing) throws ClassNotFoundException, IllegalAccessException, IOException
      Load a JSObject given a stream containing YAML data. The data is assumed to be UTF-8 encoded text. The tabspacing argument will add a filter that handles evenly spaced tabs in case these appear in the input. While 8 is a frequently used value, there are no standards specifying a specific number.
      Parameters:
      lclass - the class whose class loader will be used to convert class names to classes
      is - the input stream
      tabspacing - the tab spacing (0 implies no tab processing)
      Returns:
      the object loaded from the input stream
      Throws:
      ClassNotFoundException - a class needed to initialize this object could not be found
      IOException - an IO error occurred
      IllegalAccessException - if a Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.
    • currentLauncher

      protected static ObjectNamerLauncher currentLauncher()
      Get the current launcher.
      Returns:
      the current launcher; null if there is none
    • get

      public static Object get(String vname) throws IllegalStateException
      Get the value of a variable stored by the current launcher.
      Parameters:
      vname - the name of the variable
      Returns:
      the value of the variable
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • exists

      public static boolean exists(String name) throws IllegalStateException
      Determine if a variable is stored in the current launcher.
      Parameters:
      name - the name of the variable
      Returns:
      true if the variable exists; false otherwise
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • set

      public static void set(String vname, Object value) throws IllegalStateException
      Set the value of a variable stored in the current launcher.
      Parameters:
      vname - the name of the variable
      value - the value of the variable
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • remove

      public static Object remove(String name) throws IllegalStateException
      Remove a variable from the current launcher.
      Parameters:
      name - the name of the variable
      Returns:
      the value of the variable being removed
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • variables

      public static Set<String> variables() throws IllegalStateException
      Get the variables stored in the current launcher.
      Returns:
      a set containing the names of the variables
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • clear

      public static void clear() throws IllegalStateException
      Remove all variables from the current launcher and reset it.
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • process

      public static void process(String s, boolean ymode) throws Exception
      Process a JSON or YAML string.
      Parameters:
      s - the string to process
      ymode - true if YAML syntax is being parse; false for JSON
      Throws:
      Exception - an error occurred
    • process

      public static void process(Reader r, boolean ymode) throws Exception
      Process a JSON or YAML file.
      Parameters:
      r - a reader for the text stored in the file
      ymode - true if YAML syntax is being parse; false for JSON
      Throws:
      Exception - an error occurred
    • process

      public static void process(String filename, String s, boolean ymode) throws Exception
      Process a JSON or YAML string, supplying a file name. The file name is used when printing error messages.
      Parameters:
      filename - a file-name like identifier to assign to the input string
      s - the string to process
      ymode - true if YAML syntax is being parse; false for JSON
      Throws:
      Exception - an error occurred
    • process

      public static void process(String filename, Reader r, boolean ymode) throws Exception
      Process a JSON or YAML file, supplying a file name. The file name is used when printing error messages.
      Parameters:
      filename - the input file name; null if not known
      r - a reader for the text stored in the file
      ymode - true if YAML syntax is being parse; false for JSON
      Throws:
      Exception - an error occurred
    • process

      public static void process(String filename, JSOps object, boolean ymode, Map<JSUtilities.Location,JSUtilities.LocationPair> map) throws Exception
      Process a JSObject or JSArray. The argument is one that would be created as specified in the documentation for this class. While the BZDev class library can generate the argument from JSON or YAML inputs, other libraries may provide additional formats.

      How to construct the map argument is described in the documentation for JSUtilities.Locator.

      Parameters:
      filename - the input file name; null if not known
      object - the object specifying a configuration or series of actions
      ymode - true if the object was obtained by parsing a YAML file; false otherwise
      map - the mapping from parser locations to line/column numbers; null if not available
      Throws:
      Exception - an error occurred
      See Also:
    • getConstants

      public static List<String> getConstants() throws IllegalStateException
      Get the fully qualified names for enumeration constants and fields provided by the current launcher for use in expressions.

      This method is provided for applications that can list the available constants as part of a 'help' or documentation subsystem.

      Returns:
      the constants
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • getReturnClasses

      public static ArrayList<Class<?>> getReturnClasses() throws IllegalStateException
      Get the classes for objects that can be returned by in expressions processed by the current launcher. The values returned do not include primitive types.

      This method is provided for applications that can list the types of objects that can be returned as part of a 'help' or documentation subsystem.

      Returns:
      the classes
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • getArgumentClasses

      public static ArrayList<Class<?>> getArgumentClasses() throws IllegalStateException
      Get the classes for objects that can be uses as arguments of functions or methods in expressions processed by the current launcher. The values returned do not include primitive types or the type String.

      This method is provided for applications that can list the types of objects that can be used as arguments as part of a 'help' or documentation subsystem.

      Returns:
      the classes
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • getConstructors

      public static List<String> getConstructors() throws IllegalStateException
      Get the constructors supported by the current launcher for use in expressions. Each element in the returned list consists of a fully qualified class name followed by an open parenthesis, a comma-separated list of the class names for the arguments, and a closing parenthesis.

      This method is provided for applications that can list the constructors and their arguments as part of a 'help' or documentation subsystem.

      Returns:
      a list of the constructors
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • getFunctions

      public static List<String> getFunctions() throws IllegalStateException
      Get the functions supported by the current launcher for use in expressions. Each element in the returned list consists of a fully qualified class name followed the function name that is in turn followed by an open parenthesis, a comma-separated list of the class names for the arguments, and a closing parenthesis.

      This method is provided for applications that can list functions and their arguments as part of a 'help' or documentation subsystem.

      Returns:
      a list of the functions
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • getMethods

      public static List<String> getMethods() throws IllegalStateException
      Get the methods supported by the current launcher for use in expressions. Each element in the returned list consists of a fully qualified class name followed by a colon, a space, and the method name. The method name is in turn followed by an open parenthesis, a comma-separated list of the class names for the arguments, and a closing parenthesis.

      This method is provided for applications that can list methods and their arguments as part of a 'help' or documentation subsystem.

      Returns:
      a list of the methods
      Throws:
      IllegalStateException - a parser has not been created for the current thread
    • createAPIMap

      public static void createAPIMap(List<URL> apis) throws IOException
      Create a table mapping package names to the location containing the HTML files for that package's documentation. For the javadoc directories provided by the JDK, the name of the final component in the path is "api" and that directory will contain a file named either element-list or package-list.
      Parameters:
      apis - a list of the URLS for javadoc directories
      Throws:
      IOException - an IO error occured
    • keylistForConstants

      public static TemplateProcessor.KeyMapList keylistForConstants() throws IllegalStateException
      Get a key list for generating a table of constants. The key list will contain a sequence of key maps with the following keys:
      • href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
      • item - the fully qualified name of a constant
      This method is provided for generating HTML pages that can point to API documentation. The method createAPIMap(List) must be called before this method is used.
      Returns:
      the key list
      Throws:
      IllegalStateException - a launcher was not created for this thread.
    • keylistForReturnClasses

      public static TemplateProcessor.KeyMapList keylistForReturnClasses() throws IllegalStateException
      Get a key list for generating a table of classes, instances of which can be returned by an expression. The key list will contain a sequence of key maps with the following keys:
      • href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
      • item - the fully qualified class name of the class an expression can return
      This method is provided for generating HTML pages that can point to API documentation. The method createAPIMap(List) must be called before this method is used.
      Returns:
      the key list
      Throws:
      IllegalStateException - a launcher was not created for this thread.
    • keylistForArgumentClasses

      public static TemplateProcessor.KeyMapList keylistForArgumentClasses() throws IllegalStateException
      Get a key list for generating a table of . The key list will contain a sequence of key maps with the following keys:
      • href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
      • item - the fully qualified class name of a class for an argument to a constructor, function or method recognized by this expression parser
      This method is provided for generating HTML pages that can point to API documentation. The method createAPIMap(List) must be called before this method is used.
      Returns:
      the key list
      Throws:
      IllegalStateException - a launcher was not created for this thread.
    • keylistForConstructors

      public static TemplateProcessor.KeyMapList keylistForConstructors() throws IllegalStateException
      Get a key list for generating a table of constructors. The key list will contain a sequence of key maps with the following keys:
      • href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
      • class - the fully qualified class name for the object a constructor will create.
      • item - the simple class name followed by an open parenthesis, a comma-separated list of the types of the constructor's arguments, followed by a closing parenthesis.
      This method is provided for generating HTML pages that can point to API documentation. The method createAPIMap(List) must be called before this method is used.
      Returns:
      the key list
      Throws:
      IllegalStateException - a launcher was not created for this thread.
    • keylistForFunctions

      public static TemplateProcessor.KeyMapList keylistForFunctions() throws IllegalStateException
      Get a key list for generating a table of functions. The key list will contain a sequence of key maps with the following keys:
      • href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
      • class - the fully qualified class name for a class, one of whose static methods implements the function.
      • item - the name of the static method representing the function followed by an open parenthesis, a comma-separated list of the types of the function's arguments, followed by a closing parenthesis.
      This method is provided for generating HTML pages that can point to API documentation. The method createAPIMap(List) must be called before this method is used.
      Returns:
      the key list
      Throws:
      IllegalStateException - a launcher was not created for this thread.
    • keylistForMethods

      public static TemplateProcessor.KeyMapList keylistForMethods() throws IllegalStateException
      Get a key list for generating a table of instance methods, excluding methods for String. The key list will contain a sequence of key maps with the following keys:
      • href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
      • class - the fully qualified class name for the class declaring a method.
      • item - the name of the method followed by an open parenthesis, a comma-separated list of the types of the method's arguments, followed by a closing parenthesis.
      This method is provided for generating HTML pages that can point to API documentation. The method createAPIMap(List) must be called before this method is used.
      Returns:
      the key list
      Throws:
      IllegalStateException - a launcher was not created for this thread.
    • keylistForMethods

      public static TemplateProcessor.KeyMapList keylistForMethods(boolean hideString) throws IllegalStateException
      Get a key list for generating a table of instance methods. The key list will contain a sequence of key maps with the following keys:
      • href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
      • class - the fully qualified class name for the class declaring a method.
      • item - the name of the method followed by an open parenthesis, a comma-separated list of the types of the method's arguments, followed by a closing parenthesis.
      This method is provided for generating HTML pages that can point to API documentation. The method createAPIMap(List) must be called before this method is used.
      Parameters:
      hideString - true if methods of String should not be shown; false otherwise
      Returns:
      the key list
      Throws:
      IllegalStateException - a launcher was not created for this thread.
    • close

      public void close()
      Close the currently active launcher. If a launcher was created, this method must be called before a new launcher can be created in the current thread.
      Specified by:
      close in interface AutoCloseable
    • resetLoaders

      public static void resetLoaders()
      Reset the SPI loaders. This method resets the SPI (Service Provider Interface) loaders, and can be used in the unusual case in which the classes accessible from the class path or module path are modified.
    • newInstance

      Create a new instance of an object-namer launcher. There may be only one launcher active per thread. A launcher becomes active when its constructor is called and is active until its close() method is called.
      Parameters:
      name - the name of launcher.
      Returns:
      a new object-namer launcher
      Throws:
      IllegalAccessException - if a Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.
      IllegalArgumentException - if the number of actual and formal parameters differ; if an unwrapping conversion for primitive arguments fails; or if, after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if a constructor pertains to an enum type.
      InstantiationException - if the class that declares the underlying constructor represents an abstract class
      InvocationTargetException - if an underlying constructor throws an exception
      NoSuchMethodException - if there is an attempt to use a method that does not exist
      ExceptionInInitializerError - if the initialization provoked by this method fails
    • newInstance

      Create a new instance of an object namer launcher using an initializer. There may be only one launcher active per thread. A launcher becomes active when its constructor is called and is active until its close() method is called.
      Parameters:
      name - the name of launcher.
      dnames - the names of providers for additional data
      Returns:
      a new object-namer launcher
      Throws:
      IOException - an IO error occurred
      IllegalAccessException - if a constructor object is enforcing Java language access control and the underlying constructor is inaccessible.
      IllegalArgumentException - if the number of actual and formal parameters differ; if an unwrapping conversion for primitive arguments fails; or if, after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if a constructor pertains to an enum type.
      ClassNotFoundException - if the class for an object-namer launcher could not be found
      InstantiationException - if the class that declares the underlying constructor represents an abstract class.
      InvocationTargetException - if the underlying constructor throws an exception.
      ExceptionInInitializerError - if the initialization provoked by this method fails.
      NoSuchMethodException - if there is an attempt to use a method that does not exist
    • getLauncherNames

      public static String[] getLauncherNames()
      Get a all launcher names available via a service-provider interface.
      Returns:
      the names
    • getProviderKeyMap

      public static TemplateProcessor.KeyMap getProviderKeyMap()
      Get a key map describing the providers for each object-namer launcher and object-namer launcher and object-namer launcher data. The key map that is returned contains two iterator directives:
      • launcherList - an iteration listing all providers for instances of ObjectNamerLauncher.
      • launcherDataList -an iteration listing all providers for object-name launcher data.
      Each of these lists in turn contain a key map with two directives:
      • name - the name of a provider.
      • description - a description of the provider.
      Returns:
      the key map
    • getLauncherDataNames

      public static String[] getLauncherDataNames()
      Get all names for launcher-data additions available via the service-provider interface.
      Returns:
      the names
    • findRVFMethod

      Find the method implementing a real-valued function of 1 argument. The argument is the name of a static method with one double-precision argument that returns a double-precision value, and must include enough of the class name to be unique given the classes used to define functions.
      Parameters:
      fname - the name of the function
      Returns:
      the method
      Throws:
      NoSuchMethodException - if there is an attempt to use a method that does not exist
      IllegalStateException
      IllegalArgumentException