Package it.unimi.dsi.lang

Class ObjectParser

  • public class ObjectParser
extends 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 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.

    • Constructor Summary

      Constructors 
      Constructor 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

      Modifier and Type Method 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.