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

2016-08-24 Thread Jim Graham 

Hi Avik,

On 8/23/16 11:43 PM, Avik Niyogi wrote:

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 mailto:james.gra...@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?


I don't have answers to your questions, I just know that the documentation that was inherited (which seems to have 
missed inheriting the thrown exceptions) contains no mention of the exception that will be thrown here.


I also know that this method is not relevant to this type of image and the fact that we have to override it just to have 
it choose the escape clause inherent in the spec is silly.  We beg the question by having to implement it and then 
explain that we are implementing it only to assert that it can't be implemented.  That's a silly situation that should 
be instead handled by having the exception be the default implementation on the super class and have only those methods 
that can implement the behavior override it.


If we have a concrete implementation in the base Image class then this method doesn't even appear in the documentation 
of the AMRI class in the first place (it appears in the list of inherited methods which has the full description).


On the other hand, one could argue that the super class method is sort of vague in describing which types of image 
support the method and which do not.  In that case, then I think it makes sense for AMRI to override it just to state 
its policy on whether one can get a graphics from it.  If that is the route we go for this method then I think it makes 
sense to mention "why" we are throwing the exception rather than simply state that we are throwing it.



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 -1 and the specified
 * ImageObserver object is notified later.
 * @param observer an object waiting for the image to be loaded.
 * @return the width of this image, or -1
 * if the width is not yet known.
 */

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


Note that the AMRI class does provide a width and height so it does need to override these methods.  Also, the return 
values from these methods are special in the case of an AMRI and so the exact behavior needs to be described in these 
methods (in particular, that the w/h of the base image is used).



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?


I just copied and pasted from the source code for the Image.getGraphics() method and it used @exception.  They are 
described as synonyms by the documentation on writing javadocs and I'm not sure whether we prefer one or the other. 
Phil might know the answer to that...


...jim


*an off-screen image.
*/

...jim

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

2016-08-24 Thread Avik Niyogi 
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  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 -1 and the specified
 * ImageObserver object is notified later.
 * @param observer an object waiting for the image to be loaded.
 * @return the width of this image, or -1
 * 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 >>> > 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/
 *
 
 *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
>>> 
>>

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

2016-08-23 Thread Jim Graham 

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".


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 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 mailto:avik.niy...@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/
*

*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

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

2016-08-23 Thread Alexander Scherbatiy 

On 22/08/16 11:06, Avik Niyogi wrote:

+ awt-dev


On 22-Aug-2016, at 12:28 pm, Avik Niyogi > 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/ 
*


*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