[IMAGING-159] Parameters class for Image Parsers

["Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>]

Hello,
The IMAGING-159 [1] issue was raised during one of the 1.0 vote threads for Commons Imaging and it is a blocker for the final release.

We have a pull request [2] in which we couldn't reach consensus on an issue with generics..
There is a class called "Imaging.java", which exposes several static methods. That's the class that many users will access when getting started with Imaging, or when they need to simply read or write images. Other users may access parsers individually (e.g. BmpImageParser, or JpegImageParser, or TiffImageParser, etc), for more specific work.

One of the methods of Imaging.java accepts an image format, and then loads the parser for this format. Due to the current design with generics in the pull request, we needed to suppress warnings and cast an object to the right ImagingParameters type. i.e. you can, say, call Imaging.writeImage(..., "jpeg") and somewhere in that static method we will iterate the list of known parsers to locate the parser that accepts the format "jpeg" (or throw an error if none found).
The alternative approach to what's currently in the PR is to remove the generics from the ImageParser's. So each parser will accept simply ImagingParameters, and try to cast it down to the correct parameter type, throwing an error if it's not possible. [3]
So, in summary, we have:
option A) keep the current design, and have a suppress warning in Imaging.java's static methods, so that we can write code like:
        JpegImagingParameters params = new JpegImagingParameters();        params.setExif(new TiffOutputSet(ByteOrder.BIG_ENDIAN));
        JpegImageParser parser = new JpegImageParser();
        parser.writeImage(bufferedImage, outputStream, params); # params is defiend in JpegImageParser with generics

option B) use ImagingParameters and remove the generics, so that we can write code like:
        JpegImagingParameters params = new JpegImagingParameters();        params.setExif(new TiffOutputSet(ByteOrder.BIG_ENDIAN));
        JpegImageParser parser = new JpegImageParser();
        parser.writeImage(bufferedImage, outputStream, params); # valid because JpegImagingParameters is a ImagingParameters
My issue with option B, is that this code is also valid:

        PnmImagingParameters params = new PnmImagingParameters();
        params.setRawBits(Boolean.TRUE);
        JpegImageParser parser = new JpegImageParser();
        parser.writeImage(bufferedImage, outputStream, params); # an runtime error will occur due to the Pnm param

So instead of failing at runtime, the user can get the feedback while writing the code.
Any thoughts? Open to any alternative implementations too, options C, D, etc :)

Thank you,
Bruno

[1] https://issues.apache.org/jira/browse/IMAGING-159[2] https://github.com/apache/commons-imaging/pull/116[3] https://github.com/apache/commons-imaging/pull/116#discussion_r671481293