Class ObjectParser
- java.lang.Object
-
- com.martiansoftware.jsap.StringParser
-
- it.unimi.dsi.lang.ObjectParser
-
public class ObjectParser extends com.martiansoftware.jsap.StringParser
A parser for simple object specifications based on strings.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 methodfromSpec(String, Class, String[], String[])
that will generate object instances starting from a specification of the formclass(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
Fields Modifier and Type Field Description static java.lang.String[]
DEFAULT_FACTORY_METHODS
Standard names for factory methods.
-
Constructor Summary
Constructors Constructor Description ObjectParser()
Creates a new object parser.ObjectParser(java.lang.Class<?> type)
Creates a new object parser with given control type.ObjectParser(java.lang.Class<?> type, java.lang.String[] packages)
Creates a new object parser with given control type and list of packages.ObjectParser(java.lang.Class<?> type, java.lang.String[] packages, java.lang.String[] factoryMethod)
Creates a new object parser with given control type, list of packages and factory methods.ObjectParser(java.lang.Object context)
Creates a new object parser with given context.ObjectParser(java.lang.Object context, java.lang.Class<?> type)
Creates a new object parser with given context and control type.ObjectParser(java.lang.Object context, java.lang.Class<?> type, java.lang.String[] packages)
Creates a new object parser with given context, control type and list of packages.ObjectParser(java.lang.Object context, java.lang.Class<?> type, java.lang.String[] packages, java.lang.String[] factoryMethod)
Creates a new object parser with given context, control type, list of packages and factory methods.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static java.lang.Object
fromSpec(java.lang.Object context, java.lang.String spec)
Creates a new instance from a context and a specification.static <S> S
fromSpec(java.lang.Object context, java.lang.String spec, java.lang.Class<S> type)
Creates a new instance from a context and a specification using a given control type.static <S> S
fromSpec(java.lang.Object context, java.lang.String spec, java.lang.Class<S> type, java.lang.String[] packages)
Creates a new instance from a context and a specification using a given control type, list of packages and factory methods.static <S> S
fromSpec(java.lang.Object context, java.lang.String spec, java.lang.Class<S> type, java.lang.String[] packages, java.lang.String[] factoryMethod)
Creates a new instance from a context and a specification using a given control type and list of packages.static java.lang.Object
fromSpec(java.lang.String spec)
Creates a new instance from a specification.static <S> S
fromSpec(java.lang.String spec, java.lang.Class<S> type)
Creates a new instance from a specification using a given control type.static <S> S
fromSpec(java.lang.String spec, java.lang.Class<S> type, java.lang.String[] packages)
Creates a new instance from a specification using a given control type, list of packages and factory methods.static <S> S
fromSpec(java.lang.String spec, java.lang.Class<S> type, java.lang.String[] packages, java.lang.String[] factoryMethod)
Creates a new instance from a specification using a given control type and list of packages.java.lang.Object
parse(java.lang.String spec)
static java.lang.String
toSpec(java.lang.Object o)
Generates a parseable representation of an object fetching by reflection atoSpec()
method, or using the class name.
-
-
-
Constructor Detail
-
ObjectParser
public ObjectParser(java.lang.Class<?> type, java.lang.String[] packages, java.lang.String[] factoryMethod)
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
public ObjectParser(java.lang.Class<?> type, java.lang.String[] packages)
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
public ObjectParser(java.lang.Class<?> type)
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
public ObjectParser(java.lang.Object context, java.lang.Class<?> type, java.lang.String[] packages, java.lang.String[] factoryMethod)
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
public ObjectParser(java.lang.Object context, java.lang.Class<?> type, java.lang.String[] packages)
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
public ObjectParser(java.lang.Object context, java.lang.Class<?> type)
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
public ObjectParser(java.lang.Object context)
Creates a new object parser with given context.- Parameters:
context
- the context for this parser (will be passed on to instantiated objects)—possiblynull
.
-
-
Method Detail
-
parse
public java.lang.Object parse(java.lang.String spec) throws com.martiansoftware.jsap.ParseException
- Specified by:
parse
in classcom.martiansoftware.jsap.StringParser
- Throws:
com.martiansoftware.jsap.ParseException
-
fromSpec
public static java.lang.Object fromSpec(java.lang.String spec) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.InstantiationException, java.lang.NoSuchMethodException, java.io.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:
java.lang.IllegalArgumentException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException
java.lang.NoSuchMethodException
java.io.IOException
-
fromSpec
public static <S> S fromSpec(java.lang.String spec, java.lang.Class<S> type) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.InstantiationException, java.lang.NoSuchMethodException, java.io.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:
java.lang.IllegalArgumentException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException
java.lang.NoSuchMethodException
java.io.IOException
-
fromSpec
public static <S> S fromSpec(java.lang.String spec, java.lang.Class<S> type, java.lang.String[] packages) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.InstantiationException, java.lang.NoSuchMethodException, java.io.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:
java.lang.IllegalArgumentException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException
java.lang.NoSuchMethodException
java.io.IOException
-
fromSpec
public static java.lang.Object fromSpec(java.lang.Object context, java.lang.String spec) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.InstantiationException, java.lang.NoSuchMethodException, java.io.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:
java.lang.IllegalArgumentException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException
java.lang.NoSuchMethodException
java.io.IOException
-
fromSpec
public static <S> S fromSpec(java.lang.Object context, java.lang.String spec, java.lang.Class<S> type) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.InstantiationException, java.lang.NoSuchMethodException, java.io.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:
java.lang.IllegalArgumentException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException
java.lang.NoSuchMethodException
java.io.IOException
-
fromSpec
public static <S> S fromSpec(java.lang.Object context, java.lang.String spec, java.lang.Class<S> type, java.lang.String[] packages) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.InstantiationException, java.lang.NoSuchMethodException, java.io.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:
java.lang.IllegalArgumentException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException
java.lang.NoSuchMethodException
java.io.IOException
-
fromSpec
public static <S> S fromSpec(java.lang.String spec, java.lang.Class<S> type, java.lang.String[] packages, java.lang.String[] factoryMethod) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.InstantiationException, java.lang.NoSuchMethodException, java.io.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:
java.lang.IllegalArgumentException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException
java.lang.NoSuchMethodException
java.io.IOException
-
fromSpec
public static <S> S fromSpec(java.lang.Object context, java.lang.String spec, java.lang.Class<S> type, java.lang.String[] packages, java.lang.String[] factoryMethod) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.InstantiationException, java.lang.NoSuchMethodException, java.io.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:
java.lang.IllegalArgumentException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException
java.lang.NoSuchMethodException
java.io.IOException
-
toSpec
public static java.lang.String toSpec(java.lang.Object o)
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:
fromSpec(String, Class, String[], String[])
-
-