it.unimi.dsi.lang

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 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 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. Several polymorphic versions make it possible to specify just a subset of the arguments.

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.

Constructor Summary

Constructors

Constructor and Description
ObjectParser() Creates 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

Methods

Modifier and Type	Method and Description
static Object	fromSpec(Object context, String spec) Creates a new instance from a context and a specification.
static <S> S	fromSpec(Object context, String spec, Class<S> type) Creates a new instance from a context and a specification using a given control type.
static <S> S	fromSpec(Object context, String spec, Class<S> type, 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(Object context, String spec, Class<S> type, String[] packages, String[] factoryMethod) Creates a new instance from a context and a specification using a given control type and list of packages.
static Object	fromSpec(String spec) Creates a new instance from a specification.
static <S> S	fromSpec(String spec, Class<S> type) Creates a new instance from a specification using a given control type.
static <S> S	fromSpec(String spec, Class<S> type, String[] packages) Creates a new instance from a specification using a given control type, list of packages and factory methods.
static <S> S	fromSpec(String spec, Class<S> type, String[] packages, String[] factoryMethod) Creates a new instance from a specification using a given control type and list of packages.
Object	parse(String spec)
static String	toSpec(Object o) Generates a parseable representation of an object fetching by reflection a toSpec() method, or using the class name.

Methods inherited from class com.martiansoftware.jsap.StringParser

setUp, tearDown

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectParser

public ObjectParser(Class<?> type,
            String[] packages,
            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, or null.

factoryMethod - a list of factory methods that will be used before trying constructors, or null.

ObjectParser

public ObjectParser(Class<?> type,
            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, or null.

ObjectParser

public ObjectParser(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(Object context,
            Class<?> type,
            String[] packages,
            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)—possibly null.

type - a type that will be used to check instantiated objects.

packages - a list of package names that will be prepended to the specification, or null.

factoryMethod - a list of factory methods that will be used before trying constructors, or null.

ObjectParser

public ObjectParser(Object context,
            Class<?> type,
            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)—possibly null.

type - a type that will be used to check instantiated objects.

packages - a list of package names that will be prepended to the specification, or null.

ObjectParser

public ObjectParser(Object context,
            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)—possibly null.

type - a type that will be used to check instantiated objects.

ObjectParser

public ObjectParser(Object context)

Creates a new object parser with given context.

Parameters:

context - the context for this parser (will be passed on to instantiated objects)—possibly null.

Method Detail

parse

public Object parse(String spec)
             throws com.martiansoftware.jsap.ParseException

Specified by:

parse in class com.martiansoftware.jsap.StringParser

Throws:

com.martiansoftware.jsap.ParseException

fromSpec

public static Object fromSpec(String spec)
                       throws IllegalArgumentException,
                              ClassNotFoundException,
                              IllegalAccessException,
                              InvocationTargetException,
                              InstantiationException,
                              NoSuchMethodException

Creates a new instance from a specification.

Parameters:

spec - the object specification (see the class documentation).

Throws:

IllegalArgumentException

ClassNotFoundException

IllegalAccessException

InvocationTargetException

InstantiationException

NoSuchMethodException

fromSpec

public static <S> S fromSpec(String spec,
             Class<S> type)
                  throws IllegalArgumentException,
                         ClassNotFoundException,
                         IllegalAccessException,
                         InvocationTargetException,
                         InstantiationException,
                         NoSuchMethodException

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.

Throws:

IllegalArgumentException

ClassNotFoundException

IllegalAccessException

InvocationTargetException

InstantiationException

NoSuchMethodException

fromSpec

public static <S> S fromSpec(String spec,
             Class<S> type,
             String[] packages)
                  throws IllegalArgumentException,
                         ClassNotFoundException,
                         IllegalAccessException,
                         InvocationTargetException,
                         InstantiationException,
                         NoSuchMethodException

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, or null.

Throws:

IllegalArgumentException

ClassNotFoundException

IllegalAccessException

InvocationTargetException

InstantiationException

NoSuchMethodException

fromSpec

public static <S> S fromSpec(String spec,
             Class<S> type,
             String[] packages,
             String[] factoryMethod)
                  throws IllegalArgumentException,
                         ClassNotFoundException,
                         IllegalAccessException,
                         InvocationTargetException,
                         InstantiationException,
                         NoSuchMethodException

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, or null.

factoryMethod - a list of factory methods that will be used before trying constructors, or null.

Throws:

IllegalArgumentException

ClassNotFoundException

IllegalAccessException

InvocationTargetException

InstantiationException

NoSuchMethodException

fromSpec

public static Object fromSpec(Object context,
              String spec)
                       throws IllegalArgumentException,
                              ClassNotFoundException,
                              IllegalAccessException,
                              InvocationTargetException,
                              InstantiationException,
                              NoSuchMethodException

Creates a new instance from a context and a specification.

Parameters:

context - a context object, or null.

spec - the object specification (see the class documentation).

Throws:

IllegalArgumentException

ClassNotFoundException

IllegalAccessException

InvocationTargetException

InstantiationException

NoSuchMethodException

fromSpec

public static <S> S fromSpec(Object context,
             String spec,
             Class<S> type)
                  throws IllegalArgumentException,
                         ClassNotFoundException,
                         IllegalAccessException,
                         InvocationTargetException,
                         InstantiationException,
                         NoSuchMethodException

Creates a new instance from a context and a specification using a given control type.

Parameters:

context - a context object, or null.

spec - the object specification (see the class documentation).

type - a type that will be used to check instantiated objects.

Throws:

IllegalArgumentException

ClassNotFoundException

IllegalAccessException

InvocationTargetException

InstantiationException

NoSuchMethodException

fromSpec

public static <S> S fromSpec(Object context,
             String spec,
             Class<S> type,
             String[] packages)
                  throws IllegalArgumentException,
                         ClassNotFoundException,
                         IllegalAccessException,
                         InvocationTargetException,
                         InstantiationException,
                         NoSuchMethodException

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, or null.

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, or null.

Throws:

IllegalArgumentException

ClassNotFoundException

IllegalAccessException

InvocationTargetException

InstantiationException

NoSuchMethodException

fromSpec

public static <S> S fromSpec(Object context,
             String spec,
             Class<S> type,
             String[] packages,
             String[] factoryMethod)
                  throws IllegalArgumentException,
                         ClassNotFoundException,
                         IllegalAccessException,
                         InvocationTargetException,
                         InstantiationException,
                         NoSuchMethodException

Creates a new instance from a context and a specification using a given control type and list of packages.

Parameters:

context - a context object, or null.

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, or null.

factoryMethod - a list of factory methods that will be used before trying constructors, or null.

Throws:

IllegalArgumentException

ClassNotFoundException

IllegalAccessException

InvocationTargetException

InstantiationException

NoSuchMethodException

toSpec

public static String toSpec(Object o)

Generates a parseable representation of an object fetching by reflection a toSpec() 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 a String. 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[])