kinow commented on a change in pull request #116: URL: https://github.com/apache/commons-imaging/pull/116#discussion_r780503881
########## File path: src/main/java/org/apache/commons/imaging/Imaging.java ########## @@ -50,62 +48,40 @@ * * <h3>Using this class</h3> * - * <p> - * Almost all of the Apache Commons Imaging library's core functionality can + * <p>Almost all of the Apache Commons Imaging library's core functionality can * be accessed through the methods provided by this class. * The use of the Imaging class is similar to the Java API's ImageIO class, - * though Imaging supports formats and options not included in the standard - * Java API. - * </p> + * though Imaging supports formats not included in the standard Java API.</p> * - * <p> - * All of methods provided by the Imaging class are declared static. - * </p> + * <p>All of methods provided by the Imaging class are declared static.</p> * - * <p> - * The Apache Commons Imaging package is a pure Java implementation. - * </p> + * <p>The Apache Commons Imaging package is a pure Java implementation.</p> * * <h3>Format support</h3> * - * <p> - * While the Apache Commons Imaging package handles a number of different + * <p>While the Apache Commons Imaging package handles a number of different * graphics formats, support for some formats is not yet complete. * For the most recent information on support for specific formats, refer to * <a href="https://commons.apache.org/imaging/formatsupport.html";>Format Support</a> - * at the main project development web site. - * </p> + * at the main project development web site.</p> * * <h3>Optional parameters for image reading and writing</h3> * - * <p> - * Some of the methods provided by this class accept an optional - * <strong>params</strong> argument that permits the application to specify - * elements for special handling. If these specifications are not required by - * the application, the params argument may be omitted (as appropriate) or - * a null argument may be provided. In image-writing operations, the option - * parameters may include options such as data-compression type (if any), - * color model, or other format-specific data representations. The parameters - * map may also be used to provide EXIF Tags and other metadata to those - * formats that support them. In image-reading operations, - * the parameters may include information about special handling in reading - * the image data. - * </p> + * <p>Many of the operations provided in this class as static calls can be accessed directly + * using {@link ImageParser}'s. It is, however, difficult to design an API that is generic + * enough so users can safely read or write byte arrays when specifying the type of parameters, + * since the only way to confirm the parameters are valid for a specific format is by reading + * the byte array (when it is already too late.)</p> Review comment: **N.B.** we are removing the public methods of `Imaging`, and updating the docs here. Now users must use the `ImageParser` classes directly if they want to customize how to read/write images. This reduced a lot the size of `Imaging`. I think this prevents issues we have in [lang] where some classes grow longer and longer as more features are added - in our case it would grow by 3-4 methods (one for `File`, one for `ByteSource`, one for `bytes`, etc) for each new image file format added to [imaging]. And, of course, that solves the issue of trying to prevent `ClassCastException`'s, generics, and trying to create a good API for users in `Imaging`. ########## File path: src/main/java/org/apache/commons/imaging/ImageParser.java ########## @@ -79,25 +78,18 @@ * that the documentation is perfect, especially in the more obscure * and specialized areas of implementation. * - * <h3>The "Map params" argument</h3> + * <h3>The "params" argument</h3> * - * Many of the methods specified by this class accept an argument of - * type Map giving a list of parameters to be used when processing an - * image. For example, some of the output formats permit the specification + * <p>Many of the methods specified by this class accept an argument of + * type {@code T} defining the parameters to be used when + * processing an image. For example, some of the output formats permit * of different kinds of image compression or color models. Some of the * reading methods permit the calling application to require strict - * format compliance. In many cases, however, an application will not - * require the use of this argument. While some of the ImageParser - * implementations check for (and ignore) null arguments for this parameter, - * not all of them do (at least not at the time these notes were written). - * Therefore, a prudent programmer will always supply an valid, though - * empty instance of a Map implementation when calling such methods. - * Generally, the java HashMap class is useful for this purpose. + * format compliance.</p> * - * <p>Additionally, developers creating or enhancing classes derived - * from ImageParser are encouraged to include such checks in their code. + * @param <T> type of parameters used by this image parser */ -public abstract class ImageParser extends BinaryFileParser { +public abstract class ImageParser<T extends ImagingParameters> extends BinaryFileParser { Review comment: Separated TIFF and JPEG parameters, now they share a common ancestor, but JPEG doesn't extend TIFF. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
