- All Implemented Interfaces:
AutoCloseable
- Direct Known Subclasses:
DefaultLauncher
,SimulationLauncher
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 Summary
ConstructorsModifierConstructorDescriptionprotected
Constructor given an expression parser.ObjectNamerLauncher
(JSObject initializer) Constructor given an initializer. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
clear()
Remove all variables from the current launcher and reset it.void
close()
Close the currently active launcher.protected static JSObject
Merge two initializers.static void
createAPIMap
(List<URL> apis) Create a table mapping package names to the location containing the HTML files for that package's documentation.protected static ObjectNamerLauncher
Get the current launcher.static boolean
Determine if a variable is stored in the current launcher.static Method
findRVFMethod
(String fname) Find the method implementing a real-valued function of 1 argument.static Object
Get the value of a variable stored by the current launcher.Get the classes for objects that can be uses as arguments of functions or methods in expressions processed by the current launcher.Get the fully qualified names for enumeration constants and fields provided by the current launcher for use in expressions.Get the constructors supported by the current launcher for use in expressions.Get the functions supported by the current launcher for use in expressions.static String[]
Get all names for launcher-data additions available via the service-provider interface.static String[]
Get a all launcher names available via a service-provider interface.Get the methods supported by the current launcher for use in expressions.static TemplateProcessor.KeyMap
Get a key map describing the providers for each object-namer launcher and object-namer launcher and object-namer launcher data.Get the classes for objects that can be returned by in expressions processed by the current launcher.static TemplateProcessor.KeyMapList
Get a key list for generating a table of .static TemplateProcessor.KeyMapList
Get a key list for generating a table of constants.static TemplateProcessor.KeyMapList
Get a key list for generating a table of constructors.static TemplateProcessor.KeyMapList
Get a key list for generating a table of functions.static TemplateProcessor.KeyMapList
Get a key list for generating a table of instance methods, excluding methods forString
.static TemplateProcessor.KeyMapList
keylistForMethods
(boolean hideString) Get a key list for generating a table of instance methods.static TemplateProcessor.KeyMapList
Get a key list for generating a table of classes, instances of which can be returned by an expression.protected static JSObject
loadFromStream
(Class<?> lclass, InputStream is, int tabspacing) Load aJSObject
given a stream containing YAML data.static ObjectNamerLauncher
newInstance
(String name) Create a new instance of an object-namer launcher.static ObjectNamerLauncher
newInstance
(String name, String... dnames) Create a new instance of an object namer launcher using an initializer.static void
Process a JSON or YAML file.static void
Process a JSON or YAML string.static void
Process a JSON or YAML file, supplying a file name.static void
Process a JSON or YAML string, supplying a file name.static void
process
(String filename, JSOps object, boolean ymode, Map<JSUtilities.Location, JSUtilities.LocationPair> map) Process a JSObject or JSArray.static Object
Remove a variable from the current launcher.static void
Reset the SPI loaders.static void
Set the value of a variable stored in the current launcher.Get the variables stored in the current launcher.
-
Constructor Details
-
ObjectNamerLauncher
Constructor given an expression parser.- Parameters:
ep
- the expression parser- Throws:
IllegalStateException
- an object namer launcher is currently active in this thread
-
ObjectNamerLauncher
public ObjectNamerLauncher(JSObject initializer) throws ClassNotFoundException, IllegalAccessException, IllegalStateException Constructor given an initializer.- Parameters:
initializer
- the initializer.- Throws:
IllegalStateException
- an object namer launcher is currently active in this threadIllegalAccessException
- if a Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.ClassNotFoundException
- a class needed to initialize this object could not be found
-
-
Method Details
-
combine
Merge two initializers. This is useful in constructors that combine their default initializer with an initilizer provided as an argument- Parameters:
initializer1
- the first initializerinitializers
- 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 aJSObject
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 classesis
- the input streamtabspacing
- 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 foundIOException
- an IO error occurredIllegalAccessException
- if a Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.
-
currentLauncher
Get the current launcher.- Returns:
- the current launcher; null if there is none
-
get
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
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
Set the value of a variable stored in the current launcher.- Parameters:
vname
- the name of the variablevalue
- the value of the variable- Throws:
IllegalStateException
- a parser has not been created for the current thread
-
remove
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
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
Remove all variables from the current launcher and reset it.- Throws:
IllegalStateException
- a parser has not been created for the current thread
-
process
Process a JSON or YAML string.- Parameters:
s
- the string to processymode
- true if YAML syntax is being parse; false for JSON- Throws:
Exception
- an error occurred
-
process
Process a JSON or YAML file.- Parameters:
r
- a reader for the text stored in the fileymode
- true if YAML syntax is being parse; false for JSON- Throws:
Exception
- an error occurred
-
process
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 strings
- the string to processymode
- true if YAML syntax is being parse; false for JSON- Throws:
Exception
- an error occurred
-
process
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 knownr
- a reader for the text stored in the fileymode
- 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 ExceptionProcess a JSObject or JSArray. The argument is one that would be created as specified in the documentation forthis 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 knownobject
- the object specifying a configuration or series of actionsymode
- true if the object was obtained by parsing a YAML file; false otherwisemap
- the mapping from parser locations to line/column numbers; null if not available- Throws:
Exception
- an error occurred- See Also:
-
getConstants
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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.
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
Get a key list for generating a table of instance methods, excluding methods forString
. 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.
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.
createAPIMap(List)
must be called before this method is used.- Parameters:
hideString
- true if methods ofString
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 interfaceAutoCloseable
-
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
public static ObjectNamerLauncher newInstance(String name) throws InstantiationException, IllegalAccessException, IllegalArgumentException, InvocationTargetException, NoSuchMethodException 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 itsclose()
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 classInvocationTargetException
- if an underlying constructor throws an exceptionNoSuchMethodException
- if there is an attempt to use a method that does not existExceptionInInitializerError
- if the initialization provoked by this method fails
-
newInstance
public static ObjectNamerLauncher newInstance(String name, String... dnames) throws InstantiationException, IllegalAccessException, IllegalArgumentException, InvocationTargetException, NoSuchMethodException, ClassNotFoundException, IOException 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 itsclose()
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 occurredIllegalAccessException
- 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 foundInstantiationException
- 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
Get a all launcher names available via a service-provider interface.- Returns:
- the names
-
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.
- name - the name of a provider.
- description - a description of the provider.
- Returns:
- the key map
- launcherList - an iteration listing all providers for
instances of
-
getLauncherDataNames
Get all names for launcher-data additions available via the service-provider interface.- Returns:
- the names
-
findRVFMethod
public static Method findRVFMethod(String fname) throws IllegalStateException, NoSuchMethodException, IllegalArgumentException 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 existIllegalStateException
IllegalArgumentException
-