<AWT Dev> [OpenJDK 2D-Dev] <Swing Dev> 8138771: java.awt.image.AbstractMultiResolutionImage needs customized spec for methods of Image which it implements

Avik Niyogi avik.niyogi at oracle.com
Wed Aug 24 06:43:23 UTC 2016


Hi Jim,

Just a few queries I have regarding the inputs provided. I have added them inline in red. Thank you for further inputs in advance.
> On 24-Aug-2016, at 3:02 am, Jim Graham <james.graham at oracle.com> wrote:
> 
> I wonder why the @throws is not inherited...?
> 
> Another way to fix this would be to implement it in the base Image class with the throw and all classes that can return a graphics override it.  Then you wouldn't even need documentation in the AMRI class just to say "never mind we don't provide this method”.
AN: According to the bug description as written by the JCK team, they are expecting a custom synopsis for all the overridden methods in the AMRI class. Is this absolutely necessary for the JCK implementation. Is the real reason that a custom documentation required or is the documentation derived not available while creating JCK tests and/or they are not apt descriptions for the JCK tests? Either ways, which way of documentation of the AMRI class seem most appropriate and which requirement mention should be given the right precedence?
For example:
For the getWidth(ImageObserver observer) method, the description which would have come in a new webrev would have been the following. 

 /**
     * Returns the width of the base image. If the width is not yet known,
     * this method returns <code>-1</code> and the specified
     * <code>ImageObserver</code> object is notified later.
     * @param observer an object waiting for the image to be loaded.
     * @return the width of this image, or <code>-1</code>
     * if the width is not yet known.
     */

Does this look apposite for the AMRI class or does this seem “too custom” for the worse?

> The spec mentions that the method only works for off-screen images.  While an AMRI may contain some off-screen images, it is not itself an off-screen so it should mention that.  If we choose to list it in the methods in AMRI then I would just copy the entire comment from the super class Image and edit it based on the assumption that it is not supported for off-screen images, something like:
> 
>    /**
>     * This inherited method can only be called for off-screen images, and throws
>     * an exception in classes like this that do not support it.
>     * @return  there is no return value for a non-off-screen image.
>     * @exception UnsupportedOperationException since this class does not represent
AN: Is there any particular reason we need to use @exception and not @throws? 
Sorry if it seems like a novice question, but when is either one used and why is @throws not the right tag to use here?
>     *            an off-screen image.
>     */
> 
> 			...jim
> 
> On 8/23/16 2:28 AM, Alexander Scherbatiy wrote:
>> On 22/08/16 11:06, Avik Niyogi wrote:
>>> + awt-dev
>>> 
>>> 
>>>> On 22-Aug-2016, at 12:28 pm, Avik Niyogi <avik.niyogi at oracle.com <mailto:avik.niyogi at oracle.com>> wrote:
>>>> 
>>>> Hi All,
>>>> 
>>>> Kindly review the proposed specifications for JDK9.
>>>> 
>>>> *Bug: https://bugs.openjdk.java.net/browse/JDK-8138771*
>>>> 
>>>> *Webrev: http://cr.openjdk.java.net/~aniyogi/8138771/webrev.00/
>>>> <http://cr.openjdk.java.net/%7Eaniyogi/8138771/webrev.00/>*
>>>> 
>>>> *Issue: *The customised specifications necessitated for getGraphics method did not exist.
>>>> So test cases created according to derived specifications would lead to test cases failures.
>>>> 
>>>> *Cause: * No congruous specifications could elicit failure in circumstances not encompassed
>>>> in test cases generated without the knowledge of the same.
>>>> 
>>>> *Fix:* Appropriate comprehensive specifications required were added.
>> -  I am not a native speaker. May be something like this would be better:
>> ------
>>    /**
>>     * This method is not supported by {@code AbstractMultiResolutionImage}
>>     * and always throws {@code UnsupportedOperationException}
>>     *
>>     * @return {@code UnsupportedOperationException} is thrown
>>     * @throws UnsupportedOperationException this method is not supported
>> ------
>> 
>> - others overridden method should have a documentation that they delegate call to the base image (see #getBaseImage)
>> 
>> Thanks,
>> Alexandr.
>> 
>>>> 
>>>> With Regards,
>>>> Avik Niyogi
>>> 
>> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/awt-dev/attachments/20160824/a411b1f2/attachment-0001.html>


More information about the awt-dev mailing list