Class ObjectParser
Whenever a particular instance of a class (not a singleton) has to be specified in textual format,
one faces the difficulty of having Class.forName(String)
but no analogous method for instances. This
class provides a method fromSpec(String, Class, String[], String[])
that will generate object instances
starting from a specification of the form
class(arg,…)
The format of the specification is rather loose, to ease use on the command line: each argument may or may not be quote-delimited, with the proviso that inside quotes you have the usual escape rules, whereas without quotes the end of the parameter is marked by the next comma or closed parenthesis, and surrounding space is trimmed. For empty constructors, parentheses can be omitted. Valid examples are, for instance,
java.lang.Object java.lang.Object() java.lang.String(foo) java.lang.String("foo")
After parsing, we search for a constructor accepting as many strings as specified arguments, or possibly
a string varargs constructor. The second optional argument will be used to check
that the generated object is of the correct type, and the last argument is a list of packages that
will be prepended in turn to the specified class name. Finally, the last argument is an optional list of static factory method
names that will be tried before resorting to constructors (lacking such a list,
DEFAULT_FACTORY_METHODS
will be used). Several polymorphic versions make it possible to specify
just a subset of the arguments. Note that if you provide a specific list of factory methods they
will be tried before constructors, whereas default factory methods will be tried
after constructors.
Alternatively, a specification starting with file:
will be interpreted as the filename of a
serialized object, which will be deserialized and returned. This approach makes it possible to have a single
string-based constructor for both serialized objects and textually-described objects, which is often convenient.
Additionally, it is possible to specify a context object
that will be passed to the construction or factory method used to generate the new instance. The context is class dependent, and must
be correctly understood by the target class. In this case, the resolution process described above proceed similarly, but
the signatures searched for contain an additional Object
argument before the string arguments.
Note that this arrangement requires some collaboration from the specified class, which must provide string-based constructors.
If additionally you plan on saving parseable representations which require more than just the class name, you are invited
to follow the toSpec(Object)
conventions.
This class is a JSAP
StringParser
, and can be used in a JSAP parameter
specifications to build easily objects on the command line. Several constructors make it possible
to generate parsers that will check for type compliance, and possibly attempt to prepend package names.
-
Field Summary
-
Constructor Summary
ConstructorDescriptionCreates a new object parser.ObjectParser
(Class<?> type) Creates a new object parser with given control type.ObjectParser
(Class<?> type, String[] packages) Creates a new object parser with given control type and list of packages.ObjectParser
(Class<?> type, String[] packages, String[] factoryMethod) Creates a new object parser with given control type, list of packages and factory methods.ObjectParser
(Object context) Creates a new object parser with given context.ObjectParser
(Object context, Class<?> type) Creates a new object parser with given context and control type.ObjectParser
(Object context, Class<?> type, String[] packages) Creates a new object parser with given context, control type and list of packages.ObjectParser
(Object context, Class<?> type, String[] packages, String[] factoryMethod) Creates a new object parser with given context, control type, list of packages and factory methods. -
Method Summary
Modifier and TypeMethodDescriptionstatic Object
Creates a new instance from a context and a specification.static <S> S
Creates a new instance from a context and a specification using a given control type.static <S> S
Creates a new instance from a context and a specification using a given control type, list of packages and factory methods.static <S> S
Creates a new instance from a context and a specification using a given control type and list of packages.static Object
Creates a new instance from a specification.static <S> S
Creates a new instance from a specification using a given control type.static <S> S
Creates a new instance from a specification using a given control type, list of packages and factory methods.static <S> S
Creates a new instance from a specification using a given control type and list of packages.static String
Generates a parseable representation of an object fetching by reflection atoSpec()
method, or using the class name.Methods inherited from class com.martiansoftware.jsap.StringParser
setUp, tearDown
-
Field Details
-
DEFAULT_FACTORY_METHODS
Standard names for factory methods.
-
-
Constructor Details
-
ObjectParser
Creates a new object parser with given control type, list of packages and factory methods.- Parameters:
type
- a type that will be used to check instantiated objects.packages
- a list of package names that will be prepended to the specification, ornull
.factoryMethod
- a list of factory methods that will be used before trying constructors, ornull
.
-
ObjectParser
Creates a new object parser with given control type and list of packages.- Parameters:
type
- a type that will be used to check instantiated objects.packages
- a list of package names that will be prepended to the specification, ornull
.
-
ObjectParser
Creates a new object parser with given control type.- Parameters:
type
- a type that will be used to check instantiated objects.
-
ObjectParser
public ObjectParser()Creates a new object parser. -
ObjectParser
Creates a new object parser with given context, control type, list of packages and factory methods.- Parameters:
context
- the context for this parser (will be passed on to instantiated objects)—possiblynull
.type
- a type that will be used to check instantiated objects.packages
- a list of package names that will be prepended to the specification, ornull
.factoryMethod
- a list of factory methods that will be used before trying constructors, ornull
.
-
ObjectParser
Creates a new object parser with given context, control type and list of packages.- Parameters:
context
- the context for this parser (will be passed on to instantiated objects)—possiblynull
.type
- a type that will be used to check instantiated objects.packages
- a list of package names that will be prepended to the specification, ornull
.
-
ObjectParser
Creates a new object parser with given context and control type.- Parameters:
context
- the context for this parser (will be passed on to instantiated objects)—possiblynull
.type
- a type that will be used to check instantiated objects.
-
ObjectParser
Creates a new object parser with given context.- Parameters:
context
- the context for this parser (will be passed on to instantiated objects)—possiblynull
.
-
-
Method Details
-
parse
- Specified by:
parse
in classStringParser
- Throws:
ParseException
-
fromSpec
public static Object fromSpec(String spec) throws IllegalArgumentException, ClassNotFoundException, IllegalAccessException, InvocationTargetException, InstantiationException, NoSuchMethodException, IOException Creates a new instance from a specification.- Parameters:
spec
- the object specification (see the class documentation).- Returns:
- an instance generated using the given specification and no ancillary data.
- Throws:
IllegalArgumentException
ClassNotFoundException
IllegalAccessException
InvocationTargetException
InstantiationException
NoSuchMethodException
IOException
-
fromSpec
public static <S> S fromSpec(String spec, Class<S> type) throws IllegalArgumentException, ClassNotFoundException, IllegalAccessException, InvocationTargetException, InstantiationException, NoSuchMethodException, IOException Creates a new instance from a specification using a given control type.- Parameters:
spec
- the object specification (see the class documentation).type
- a type that will be used to check instantiated objects.- Returns:
- an instance generated using the given specification.
- Throws:
IllegalArgumentException
ClassNotFoundException
IllegalAccessException
InvocationTargetException
InstantiationException
NoSuchMethodException
IOException
-
fromSpec
public static <S> S fromSpec(String spec, Class<S> type, String[] packages) throws IllegalArgumentException, ClassNotFoundException, IllegalAccessException, InvocationTargetException, InstantiationException, NoSuchMethodException, IOException Creates a new instance from a specification using a given control type, list of packages and factory methods.- Parameters:
spec
- the object specification (see the class documentation).type
- a type that will be used to check instantiated objects.packages
- a list of package names that will be prepended to the specification, ornull
.- Returns:
- an instance generated using the given specification and ancillary data.
- Throws:
IllegalArgumentException
ClassNotFoundException
IllegalAccessException
InvocationTargetException
InstantiationException
NoSuchMethodException
IOException
-
fromSpec
public static Object fromSpec(Object context, String spec) throws IllegalArgumentException, ClassNotFoundException, IllegalAccessException, InvocationTargetException, InstantiationException, NoSuchMethodException, IOException Creates a new instance from a context and a specification.- Parameters:
context
- a context object, ornull
.spec
- the object specification (see the class documentation).- Returns:
- an instance generated using the given specification and ancillary data.
- Throws:
IllegalArgumentException
ClassNotFoundException
IllegalAccessException
InvocationTargetException
InstantiationException
NoSuchMethodException
IOException
-
fromSpec
public static <S> S fromSpec(Object context, String spec, Class<S> type) throws IllegalArgumentException, ClassNotFoundException, IllegalAccessException, InvocationTargetException, InstantiationException, NoSuchMethodException, IOException Creates a new instance from a context and a specification using a given control type.- Parameters:
context
- a context object, ornull
.spec
- the object specification (see the class documentation).type
- a type that will be used to check instantiated objects.- Returns:
- an instance generated using the given specification and ancillary data.
- Throws:
IllegalArgumentException
ClassNotFoundException
IllegalAccessException
InvocationTargetException
InstantiationException
NoSuchMethodException
IOException
-
fromSpec
public static <S> S fromSpec(Object context, String spec, Class<S> type, String[] packages) throws IllegalArgumentException, ClassNotFoundException, IllegalAccessException, InvocationTargetException, InstantiationException, NoSuchMethodException, IOException Creates a new instance from a context and a specification using a given control type, list of packages and factory methods.- Parameters:
context
- a context object, ornull
.spec
- the object specification (see the class documentation).type
- a type that will be used to check instantiated objects.packages
- a list of package names that will be prepended to the specification, ornull
.- Returns:
- an instance generated using the given specification and ancillary data.
- Throws:
IllegalArgumentException
ClassNotFoundException
IllegalAccessException
InvocationTargetException
InstantiationException
NoSuchMethodException
IOException
-
fromSpec
public static <S> S fromSpec(String spec, Class<S> type, String[] packages, String[] factoryMethod) throws IllegalArgumentException, ClassNotFoundException, IllegalAccessException, InvocationTargetException, InstantiationException, NoSuchMethodException, IOException Creates a new instance from a specification using a given control type and list of packages.- Parameters:
spec
- the object specification (see the class documentation).type
- a type that will be used to check instantiated objects.packages
- a list of package names that will be prepended to the specification, ornull
.factoryMethod
- a list of factory methods that will be used before trying constructors, ornull
.- Returns:
- an instance generated using the given specification and ancillary data.
- Throws:
IllegalArgumentException
ClassNotFoundException
IllegalAccessException
InvocationTargetException
InstantiationException
NoSuchMethodException
IOException
-
fromSpec
public static <S> S fromSpec(Object context, String spec, Class<S> type, String[] packages, String[] factoryMethod) throws IllegalArgumentException, ClassNotFoundException, IllegalAccessException, InvocationTargetException, InstantiationException, NoSuchMethodException, IOException Creates a new instance from a context and a specification using a given control type and list of packages.- Parameters:
context
- a context object, ornull
.spec
- the object specification (see the class documentation).type
- a type that will be used to check instantiated objects.packages
- a list of package names that will be prepended to the specification, ornull
.factoryMethod
- a list of factory methods that will be used before trying constructors, ornull
.- Returns:
- an instance generated using the given specification and ancillary data.
- Throws:
IllegalArgumentException
ClassNotFoundException
IllegalAccessException
InvocationTargetException
InstantiationException
NoSuchMethodException
IOException
-
toSpec
Generates a parseable representation of an object fetching by reflection atoSpec()
method, or using the class name.The standard approach to generate a parseable representation would be to have some interface specifying a no-arg
toSpec()
method returning aString
. Since most of the typically parsed objects are singletons, and often one does not need to save a parseable representation, we rather fetch such a method if available, but we will otherwise return just the class name.- Parameters:
o
- an object.- Returns:
- hopefully, a parseable representation of the object.
- See Also:
-