Class 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 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 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
    • Field Detail

      • DEFAULT_FACTORY_METHODS

        public static final java.lang.String[] DEFAULT_FACTORY_METHODS
        Standard names for factory methods.
    • 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, or null.
        factoryMethod - a list of factory methods that will be used before trying constructors, or null.
      • 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, or null.
      • 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)—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​(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)—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​(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)—possibly null.
        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)—possibly null.
    • Method Detail

      • parse

        public java.lang.Object parse​(java.lang.String spec)
                               throws com.martiansoftware.jsap.ParseException
        Specified by:
        parse in class com.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, or null.
        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, or null.
        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, or null.
        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, 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.
        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, or null.
        factoryMethod - a list of factory methods that will be used before trying constructors, or null.
        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, 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.
        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 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[])