You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@harmony.apache.org by "Paulex Yang (JIRA)" <ji...@apache.org> on 2006/03/03 07:51:39 UTC
[jira] Created: (HARMONY-163) Three types in java.util.jar are not
implemented in Harmony
Three types in java.util.jar are not implemented in Harmony
-----------------------------------------------------------
Key: HARMONY-163
URL: http://issues.apache.org/jira/browse/HARMONY-163
Project: Harmony
Type: Bug
Components: Classlib
Reporter: Paulex Yang
Three types:
public abstract class java/util/jar/Pack200
public interface java/util/jar/Pack200$Packer
public interface java/util/jar/Pack200$Unpacker
are introduced in JSE 5, but not implemented in Harmony
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
Re: Understanding JAPI tools
Posted by Richard Liang <ri...@gmail.com>.
Hello Paulex,
Please refer to JDiff (http://javadiff.sourceforge.net/), maybe this is
tool can meet your requirement more. :-D
Richard Liang
China Software Development Lab, IBM
Dalibor Topic wrote:
> On Mon, Mar 06, 2006 at 02:12:16PM +0800, Paulex Yang wrote:
>
>> Stuart,
>>
>> Stuart Ballard wrote:
>>
>>> Tim Ellison <t.p.ellison <at> gmail.com> writes:
>>>
>>>
>>>> Stuart: is there some way to avoid JAPI taking inherited API signatures
>>>> into account when doing the diff? kinda like the javadoc tool.
>>>>
>>>>
>>> This is something of a Japi FAQ (I should probably put together a Japi FAQ
>>> page
>>> somewhere now that it's no longer the case that pretty much everyone using
>>> Japi
>>> is on the Classpath list ;) ).
>>>
>>> The answer is no, it doesn't do this, and I'm not going to implement it.
>>> The
>>> reason is that whether a method is overridden or not is *not* part of the
>>> public
>>> API. Javadoc documents it, sure, but that's not really sufficient to say
>>> whether
>>> it's part of the API or not - it's quite likely it was simply easier to
>>> write
>>> Javadoc that way (so it didn't have to go and find the doc comments in the
>>> superclass's source file, etc).
>>>
>>> The rules of binary compatibility say that moving a method up or down the
>>> class
>>> hierarchy is a completely compatible change.
>>>
>>> A method may be overridden, or not, purely for performance reasons and the
>>> behavior could be completely identical. For example, LinkedList.subList is
>>> not
>>> documented as being overridden, but if it's not, that guarantees that the
>>> iterator() method will always be at least O(N) where N is the startIndex
>>> that
>>> the sublist was created with. An overridden LinkedList.subList method
>>> could hang
>>> on to the start and end nodes of the list and provide an O(1)
>>> implementation of
>>> iterator(). As long as some effort was taken to ensure that serialization
>>> stayed
>>> compatible, there's no reason why a Free runtime shouldn't do that
>>> optimization
>>> even if Sun doesn't.
>>>
>>> I've also heard of cases where Sun documents a method as being overridden
>>> even
>>> though as far as any testing can determine, all it does is call super.
>>> There
>>> should be no obligation for any Free runtime to duplicate this
>>> inefficiency.
>>>
>>> It's also possible to implement a method that needs changed behavior in a
>>> subclass by making the superclass delegate some parts of its behavior to
>>> non-public methods, so the superclass method is unchanged but the subclass
>>> just
>>> overrides the non-public methods (obviously, this only works if the
>>> subclass is
>>> in the same package, but that's pretty common).
>>>
>>> Finally, it's possible (albeit unlikely) that even if there *was* an
>>> apparent
>>> need to override a method in a subclass because it has different behavior,
>>> there
>>> might be some weird optimization-related reason why somebody might want to
>>> actually write it as "if (this instanceof Whatever)" in the superclass. I
>>> can't
>>> see why that would happen, but if someone did that and got all the behavior
>>> right, they shouldn't be penalized for it in Japi.
>>>
>>>
>> Most of above is true and has good reason, but as a practicer trying to
>> implement a RI compatible class library, I still feel strongly that the
>> method override information has its value, maybe a most common example
>> is equals(Object), most classes don't override this method and only call
>> j.l.Object's, but others DO has their own criteria, it's very reasonable
>> to just remind programmer to implement this method, otherwise it will
>> introduce serious compatibility issue.
>>
>>
>
> It won't introduce a binary compatibility issue. That's what really
> matters. You can't get semantics like who overloads what right via a tool,
> you need to read the specs to see if you should override equals/hashCode or
> not, and how.
>
>
>> Just as a proposal, if you still feel that override difference is
>> another story with common difference, how about to separate them into
>> another category, similar with Compiler's warning, which at least can be
>> as reference to programmer, and this information even can be switched on
>> only if some user want to check the difference more *strictly*.
>>
>>> Basically, Japi's business is to test the coverage of the API, and it's a
>>> fundamental design decision that Japi will *not* be testing implementation
>>> details. I've done quite a lot of work fixing bugs where implementation
>>> details
>>> inadvertently get exposed in the Japi results and if I find any more I'll
>>> fix
>>> them too.
>>>
>>> I think this is *extremely* important because, among other things, it's the
>>> *only* reason I feel legally secure in distributing Japi files for the
>>> JDK. As
>>> long as they only contain functional information necessary for
>>> interoperability,
>>> they're uncopyrightable. If they start exposing copyrightable
>>> implementation
>>> details, they become derived works of the JDK, and illegal to distribute
>>> (or,
>>> technically, to even create in the first place). And potentially so do the
>>> results of the comparisons. And if you then use those comparisons to make
>>> decisions on what to implement in Harmony, it jeopardizes Harmony's
>>> cleanroom
>>> status too. (IANAL; the people who actually decide whether legal risks are
>>> acceptable might think this isn't actually a problem for Harmony, but *I*
>>> don't
>>> want to be responsible for it ;) )
>>>
>>> The right way to ensure that you've overridden all the right methods is to
>>> test
>>> the *behavior* of those methods. Obviously this is a lot more work than a
>>> simple
>>> automated run via Japi or equivalent, but it's the only way to get
>>> meaningful
>>> results.
>>>
>>>
>> It is definitely the right way, but maybe not the most practical one.
>> Still the example of equals(), do we need a testEquals for every single
>> class? or do we still need to check the JavaDoc one by one to find
>> difference on this method? why not the tool just give some warning to
>> some possible incompatible?
>>
>
> Because a tool can't know if an implementation detail outside of the
> binary compatibility spec is relevant for an implementation of the J2SE
> API spec or not. AI hasn't caught up with that goal yet. :)
>
> For example, different compatible implementations
> of the spec may or may not chose to override equals for a class: as long
> as they are binary compatible (trivial if we are not overriding), and fulfil
> both the contract of the spec for equals in their class, and the
> contract for equals in the superclasses, they are OK.
>
> You could for
> example, implement Object.equals as a giant instanceof if-else cascade
> for all the defined types in J2SE, and save yourself all the wasted
> bytes of storage going into having many little trivial methods in many
> classes. Such an implementation would be convenient for embedded uses,
> as it shaves off unnecessary bytecodes very nicely, and still be fully
> compatible with the specs.
>
> You could also implement a generic,
> reflection based equals method in Object that does the right thing in
> 99% of the cases, and just override the few cases where that's not
> good enough. Or use AOP, or something else, as long as your code is
> binary compatible.
>
> So yes, you need to wade through the specs one by one to implement them
> faithfully. On the other hand, the specs also give you a lot of leeway
> to do the right thing efficiently, without having to explicitely mimic
> the RI. :)
>
> cheers,
> dalibor topic
>
>
>>> Obviously since Japi is Free Software I can't prevent others from making a
>>> version that does this, but I hope I've shown why I think it would be a
>>> bad idea.
>>>
>>>
>>>
>> There is another issue of JAPI, pls. correct me if I'm wrong, seems the
>> *final* information is also ignored. I also think this difference of
>> method signature is a compatibility issue which could not be overlooked,
>> because the spec writer might have consider very carefully about which
>> methods can be overridden and which should be immutable. Comments?
>>
>>> Stuart.
>>>
>>>
>>>
>>>
>> --
>> Paulex Yang
>> China Software Development Lab
>> IBM
>>
>>
>>
>
>
Re: Understanding JAPI tools
Posted by Tim Ellison <t....@gmail.com>.
Dalibor Topic wrote:
> On Mon, Mar 06, 2006 at 02:12:16PM +0800, Paulex Yang wrote:
>> Stuart,
>>
>> Stuart Ballard wrote:
>>> Tim Ellison <t.p.ellison <at> gmail.com> writes:
>>>
>>>> Stuart: is there some way to avoid JAPI taking inherited API signatures
>>>> into account when doing the diff? kinda like the javadoc tool.
>>>>
>>> This is something of a Japi FAQ (I should probably put together a Japi FAQ
>>> page
>>> somewhere now that it's no longer the case that pretty much everyone using
>>> Japi
>>> is on the Classpath list ;) ).
>>>
>>> The answer is no, it doesn't do this, and I'm not going to implement it.
>>> The
>>> reason is that whether a method is overridden or not is *not* part of the
>>> public
>>> API. Javadoc documents it, sure, but that's not really sufficient to say
>>> whether
>>> it's part of the API or not - it's quite likely it was simply easier to
>>> write
>>> Javadoc that way (so it didn't have to go and find the doc comments in the
>>> superclass's source file, etc).
>>>
>>> The rules of binary compatibility say that moving a method up or down the
>>> class
>>> hierarchy is a completely compatible change.
>>>
>>> A method may be overridden, or not, purely for performance reasons and the
>>> behavior could be completely identical. For example, LinkedList.subList is
>>> not
>>> documented as being overridden, but if it's not, that guarantees that the
>>> iterator() method will always be at least O(N) where N is the startIndex
>>> that
>>> the sublist was created with. An overridden LinkedList.subList method
>>> could hang
>>> on to the start and end nodes of the list and provide an O(1)
>>> implementation of
>>> iterator(). As long as some effort was taken to ensure that serialization
>>> stayed
>>> compatible, there's no reason why a Free runtime shouldn't do that
>>> optimization
>>> even if Sun doesn't.
>>>
>>> I've also heard of cases where Sun documents a method as being overridden
>>> even
>>> though as far as any testing can determine, all it does is call super.
>>> There
>>> should be no obligation for any Free runtime to duplicate this
>>> inefficiency.
>>>
>>> It's also possible to implement a method that needs changed behavior in a
>>> subclass by making the superclass delegate some parts of its behavior to
>>> non-public methods, so the superclass method is unchanged but the subclass
>>> just
>>> overrides the non-public methods (obviously, this only works if the
>>> subclass is
>>> in the same package, but that's pretty common).
>>>
>>> Finally, it's possible (albeit unlikely) that even if there *was* an
>>> apparent
>>> need to override a method in a subclass because it has different behavior,
>>> there
>>> might be some weird optimization-related reason why somebody might want to
>>> actually write it as "if (this instanceof Whatever)" in the superclass. I
>>> can't
>>> see why that would happen, but if someone did that and got all the behavior
>>> right, they shouldn't be penalized for it in Japi.
>>>
>> Most of above is true and has good reason, but as a practicer trying to
>> implement a RI compatible class library, I still feel strongly that the
>> method override information has its value, maybe a most common example
>> is equals(Object), most classes don't override this method and only call
>> j.l.Object's, but others DO has their own criteria, it's very reasonable
>> to just remind programmer to implement this method, otherwise it will
>> introduce serious compatibility issue.
>>
>
> It won't introduce a binary compatibility issue. That's what really
> matters.
Of course, we need to be more than simply binary compatible with the
reference implementation, and while compliance with the spec gives some
flexibility in the implementation approach, being binary compatible is
not enough.
AIUI the JCK doesn't only test binary compatibility with the API, so if
we were to introduce a new method that is not in the spec, that would be
binary compatible but would fail the JCK.
> You can't get semantics like who overloads what right via a tool,
> you need to read the specs to see if you should override equals/hashCode or
> not, and how.
That is the point. We have to be careful not to use JAPI tools to say
Harmony is "X%-complete" -- as we all agree, that will not take into
account the semantics of inherited methods / fields into account (e.g.
equals() or abstract methods etc.). I believe that it is useful to
compare the Harmony implementation against the spec even if it does
produce some 'false positives' in order to guide developers to areas
that need enhancing.
>> Just as a proposal, if you still feel that override difference is
>> another story with common difference, how about to separate them into
>> another category, similar with Compiler's warning, which at least can be
>> as reference to programmer, and this information even can be switched on
>> only if some user want to check the difference more *strictly*.
>>> Basically, Japi's business is to test the coverage of the API, and it's a
>>> fundamental design decision that Japi will *not* be testing implementation
>>> details. I've done quite a lot of work fixing bugs where implementation
>>> details
>>> inadvertently get exposed in the Japi results and if I find any more I'll
>>> fix
>>> them too.
>>>
>>> I think this is *extremely* important because, among other things, it's the
>>> *only* reason I feel legally secure in distributing Japi files for the
>>> JDK. As
>>> long as they only contain functional information necessary for
>>> interoperability,
>>> they're uncopyrightable. If they start exposing copyrightable
>>> implementation
>>> details, they become derived works of the JDK, and illegal to distribute
>>> (or,
>>> technically, to even create in the first place). And potentially so do the
>>> results of the comparisons. And if you then use those comparisons to make
>>> decisions on what to implement in Harmony, it jeopardizes Harmony's
>>> cleanroom
>>> status too. (IANAL; the people who actually decide whether legal risks are
>>> acceptable might think this isn't actually a problem for Harmony, but *I*
>>> don't
>>> want to be responsible for it ;) )
>>>
>>> The right way to ensure that you've overridden all the right methods is to
>>> test
>>> the *behavior* of those methods. Obviously this is a lot more work than a
>>> simple
>>> automated run via Japi or equivalent, but it's the only way to get
>>> meaningful
>>> results.
>>>
>> It is definitely the right way, but maybe not the most practical one.
>> Still the example of equals(), do we need a testEquals for every single
>> class?
The short answer is 'yes' we do to be sure that equals works for every
object, and to ensure that our inherited implementation of equals()
works the same way as the reference implementation; however, when we
read the javadoc specification we expect every departure from the more
general spec to be documented in the subtype. Where the choice is made
to implement in the supertype there still needs to be a subtype test case.
What we seem to be missing is a mechanism for stating in Harmony that a
supertype's implementation satisfies a subtypes' specification
requirement. Again, I am prepared to believe that the set of those
implementation/specification departures are small enough to deal with,
and that the Harmony implementation to javadoc (not RI code) comparison
is worthwhile.
>> or do we still need to check the JavaDoc one by one to find
>> difference on this method? why not the tool just give some warning to
>> some possible incompatible?
>
> Because a tool can't know if an implementation detail outside of the
> binary compatibility spec is relevant for an implementation of the J2SE
> API spec or not. AI hasn't caught up with that goal yet. :)
>
> For example, different compatible implementations
> of the spec may or may not chose to override equals for a class: as long
> as they are binary compatible (trivial if we are not overriding), and fulfil
> both the contract of the spec for equals in their class, and the
> contract for equals in the superclasses, they are OK.
>
> You could for
> example, implement Object.equals as a giant instanceof if-else cascade
> for all the defined types in J2SE, and save yourself all the wasted
> bytes of storage going into having many little trivial methods in many
> classes. Such an implementation would be convenient for embedded uses,
> as it shaves off unnecessary bytecodes very nicely, and still be fully
> compatible with the specs.
>
> You could also implement a generic,
> reflection based equals method in Object that does the right thing in
> 99% of the cases, and just override the few cases where that's not
> good enough. Or use AOP, or something else, as long as your code is
> binary compatible.
>
> So yes, you need to wade through the specs one by one to implement them
> faithfully. On the other hand, the specs also give you a lot of leeway
> to do the right thing efficiently, without having to explicitely mimic
> the RI. :)
Any suggestions about how you record (in the code) that you have waded
through the spec and it is implemented right? or do you think this is a
completeness measure that has to be kept elsewhere?
Regards,
Tim
> cheers,
> dalibor topic
>
>>> Obviously since Japi is Free Software I can't prevent others from making a
>>> version that does this, but I hope I've shown why I think it would be a
>>> bad idea.
>>>
>>>
>> There is another issue of JAPI, pls. correct me if I'm wrong, seems the
>> *final* information is also ignored. I also think this difference of
>> method signature is a compatibility issue which could not be overlooked,
>> because the spec writer might have consider very carefully about which
>> methods can be overridden and which should be immutable. Comments?
>>> Stuart.
>>>
>>>
>>>
>>
>> --
>> Paulex Yang
>> China Software Development Lab
>> IBM
>>
>>
>
--
Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.
Re: Understanding JAPI tools
Posted by Dalibor Topic <ro...@kaffe.org>.
On Mon, Mar 06, 2006 at 02:12:16PM +0800, Paulex Yang wrote:
> Stuart,
>
> Stuart Ballard wrote:
> >Tim Ellison <t.p.ellison <at> gmail.com> writes:
> >
> >>Stuart: is there some way to avoid JAPI taking inherited API signatures
> >>into account when doing the diff? kinda like the javadoc tool.
> >>
> >
> >This is something of a Japi FAQ (I should probably put together a Japi FAQ
> >page
> >somewhere now that it's no longer the case that pretty much everyone using
> >Japi
> >is on the Classpath list ;) ).
> >
> >The answer is no, it doesn't do this, and I'm not going to implement it.
> >The
> >reason is that whether a method is overridden or not is *not* part of the
> >public
> >API. Javadoc documents it, sure, but that's not really sufficient to say
> >whether
> >it's part of the API or not - it's quite likely it was simply easier to
> >write
> >Javadoc that way (so it didn't have to go and find the doc comments in the
> >superclass's source file, etc).
> >
> >The rules of binary compatibility say that moving a method up or down the
> >class
> >hierarchy is a completely compatible change.
> >
> >A method may be overridden, or not, purely for performance reasons and the
> >behavior could be completely identical. For example, LinkedList.subList is
> >not
> >documented as being overridden, but if it's not, that guarantees that the
> >iterator() method will always be at least O(N) where N is the startIndex
> >that
> >the sublist was created with. An overridden LinkedList.subList method
> >could hang
> >on to the start and end nodes of the list and provide an O(1)
> >implementation of
> >iterator(). As long as some effort was taken to ensure that serialization
> >stayed
> >compatible, there's no reason why a Free runtime shouldn't do that
> >optimization
> >even if Sun doesn't.
> >
> >I've also heard of cases where Sun documents a method as being overridden
> >even
> >though as far as any testing can determine, all it does is call super.
> >There
> >should be no obligation for any Free runtime to duplicate this
> >inefficiency.
> >
> >It's also possible to implement a method that needs changed behavior in a
> >subclass by making the superclass delegate some parts of its behavior to
> >non-public methods, so the superclass method is unchanged but the subclass
> >just
> >overrides the non-public methods (obviously, this only works if the
> >subclass is
> >in the same package, but that's pretty common).
> >
> >Finally, it's possible (albeit unlikely) that even if there *was* an
> >apparent
> >need to override a method in a subclass because it has different behavior,
> >there
> >might be some weird optimization-related reason why somebody might want to
> >actually write it as "if (this instanceof Whatever)" in the superclass. I
> >can't
> >see why that would happen, but if someone did that and got all the behavior
> >right, they shouldn't be penalized for it in Japi.
> >
> Most of above is true and has good reason, but as a practicer trying to
> implement a RI compatible class library, I still feel strongly that the
> method override information has its value, maybe a most common example
> is equals(Object), most classes don't override this method and only call
> j.l.Object's, but others DO has their own criteria, it's very reasonable
> to just remind programmer to implement this method, otherwise it will
> introduce serious compatibility issue.
>
It won't introduce a binary compatibility issue. That's what really
matters. You can't get semantics like who overloads what right via a tool,
you need to read the specs to see if you should override equals/hashCode or
not, and how.
> Just as a proposal, if you still feel that override difference is
> another story with common difference, how about to separate them into
> another category, similar with Compiler's warning, which at least can be
> as reference to programmer, and this information even can be switched on
> only if some user want to check the difference more *strictly*.
> >Basically, Japi's business is to test the coverage of the API, and it's a
> >fundamental design decision that Japi will *not* be testing implementation
> >details. I've done quite a lot of work fixing bugs where implementation
> >details
> >inadvertently get exposed in the Japi results and if I find any more I'll
> >fix
> >them too.
> >
> >I think this is *extremely* important because, among other things, it's the
> >*only* reason I feel legally secure in distributing Japi files for the
> >JDK. As
> >long as they only contain functional information necessary for
> >interoperability,
> >they're uncopyrightable. If they start exposing copyrightable
> >implementation
> >details, they become derived works of the JDK, and illegal to distribute
> >(or,
> >technically, to even create in the first place). And potentially so do the
> >results of the comparisons. And if you then use those comparisons to make
> >decisions on what to implement in Harmony, it jeopardizes Harmony's
> >cleanroom
> >status too. (IANAL; the people who actually decide whether legal risks are
> >acceptable might think this isn't actually a problem for Harmony, but *I*
> >don't
> >want to be responsible for it ;) )
> >
> >The right way to ensure that you've overridden all the right methods is to
> >test
> >the *behavior* of those methods. Obviously this is a lot more work than a
> >simple
> >automated run via Japi or equivalent, but it's the only way to get
> >meaningful
> >results.
> >
> It is definitely the right way, but maybe not the most practical one.
> Still the example of equals(), do we need a testEquals for every single
> class? or do we still need to check the JavaDoc one by one to find
> difference on this method? why not the tool just give some warning to
> some possible incompatible?
Because a tool can't know if an implementation detail outside of the
binary compatibility spec is relevant for an implementation of the J2SE
API spec or not. AI hasn't caught up with that goal yet. :)
For example, different compatible implementations
of the spec may or may not chose to override equals for a class: as long
as they are binary compatible (trivial if we are not overriding), and fulfil
both the contract of the spec for equals in their class, and the
contract for equals in the superclasses, they are OK.
You could for
example, implement Object.equals as a giant instanceof if-else cascade
for all the defined types in J2SE, and save yourself all the wasted
bytes of storage going into having many little trivial methods in many
classes. Such an implementation would be convenient for embedded uses,
as it shaves off unnecessary bytecodes very nicely, and still be fully
compatible with the specs.
You could also implement a generic,
reflection based equals method in Object that does the right thing in
99% of the cases, and just override the few cases where that's not
good enough. Or use AOP, or something else, as long as your code is
binary compatible.
So yes, you need to wade through the specs one by one to implement them
faithfully. On the other hand, the specs also give you a lot of leeway
to do the right thing efficiently, without having to explicitely mimic
the RI. :)
cheers,
dalibor topic
> >Obviously since Japi is Free Software I can't prevent others from making a
> >version that does this, but I hope I've shown why I think it would be a
> >bad idea.
> >
> >
> There is another issue of JAPI, pls. correct me if I'm wrong, seems the
> *final* information is also ignored. I also think this difference of
> method signature is a compatibility issue which could not be overlooked,
> because the spec writer might have consider very carefully about which
> methods can be overridden and which should be immutable. Comments?
> >Stuart.
> >
> >
> >
>
>
> --
> Paulex Yang
> China Software Development Lab
> IBM
>
>
Re: Understanding JAPI tools
Posted by Paulex Yang <pa...@gmail.com>.
Stuart,
Stuart Ballard wrote:
> Tim Ellison <t.p.ellison <at> gmail.com> writes:
>
>> Stuart: is there some way to avoid JAPI taking inherited API signatures
>> into account when doing the diff? kinda like the javadoc tool.
>>
>
> This is something of a Japi FAQ (I should probably put together a Japi FAQ page
> somewhere now that it's no longer the case that pretty much everyone using Japi
> is on the Classpath list ;) ).
>
> The answer is no, it doesn't do this, and I'm not going to implement it. The
> reason is that whether a method is overridden or not is *not* part of the public
> API. Javadoc documents it, sure, but that's not really sufficient to say whether
> it's part of the API or not - it's quite likely it was simply easier to write
> Javadoc that way (so it didn't have to go and find the doc comments in the
> superclass's source file, etc).
>
> The rules of binary compatibility say that moving a method up or down the class
> hierarchy is a completely compatible change.
>
> A method may be overridden, or not, purely for performance reasons and the
> behavior could be completely identical. For example, LinkedList.subList is not
> documented as being overridden, but if it's not, that guarantees that the
> iterator() method will always be at least O(N) where N is the startIndex that
> the sublist was created with. An overridden LinkedList.subList method could hang
> on to the start and end nodes of the list and provide an O(1) implementation of
> iterator(). As long as some effort was taken to ensure that serialization stayed
> compatible, there's no reason why a Free runtime shouldn't do that optimization
> even if Sun doesn't.
>
> I've also heard of cases where Sun documents a method as being overridden even
> though as far as any testing can determine, all it does is call super. There
> should be no obligation for any Free runtime to duplicate this inefficiency.
>
> It's also possible to implement a method that needs changed behavior in a
> subclass by making the superclass delegate some parts of its behavior to
> non-public methods, so the superclass method is unchanged but the subclass just
> overrides the non-public methods (obviously, this only works if the subclass is
> in the same package, but that's pretty common).
>
> Finally, it's possible (albeit unlikely) that even if there *was* an apparent
> need to override a method in a subclass because it has different behavior, there
> might be some weird optimization-related reason why somebody might want to
> actually write it as "if (this instanceof Whatever)" in the superclass. I can't
> see why that would happen, but if someone did that and got all the behavior
> right, they shouldn't be penalized for it in Japi.
>
Most of above is true and has good reason, but as a practicer trying to
implement a RI compatible class library, I still feel strongly that the
method override information has its value, maybe a most common example
is equals(Object), most classes don't override this method and only call
j.l.Object's, but others DO has their own criteria, it's very reasonable
to just remind programmer to implement this method, otherwise it will
introduce serious compatibility issue.
Just as a proposal, if you still feel that override difference is
another story with common difference, how about to separate them into
another category, similar with Compiler's warning, which at least can be
as reference to programmer, and this information even can be switched on
only if some user want to check the difference more *strictly*.
> Basically, Japi's business is to test the coverage of the API, and it's a
> fundamental design decision that Japi will *not* be testing implementation
> details. I've done quite a lot of work fixing bugs where implementation details
> inadvertently get exposed in the Japi results and if I find any more I'll fix
> them too.
>
> I think this is *extremely* important because, among other things, it's the
> *only* reason I feel legally secure in distributing Japi files for the JDK. As
> long as they only contain functional information necessary for interoperability,
> they're uncopyrightable. If they start exposing copyrightable implementation
> details, they become derived works of the JDK, and illegal to distribute (or,
> technically, to even create in the first place). And potentially so do the
> results of the comparisons. And if you then use those comparisons to make
> decisions on what to implement in Harmony, it jeopardizes Harmony's cleanroom
> status too. (IANAL; the people who actually decide whether legal risks are
> acceptable might think this isn't actually a problem for Harmony, but *I* don't
> want to be responsible for it ;) )
>
> The right way to ensure that you've overridden all the right methods is to test
> the *behavior* of those methods. Obviously this is a lot more work than a simple
> automated run via Japi or equivalent, but it's the only way to get meaningful
> results.
>
It is definitely the right way, but maybe not the most practical one.
Still the example of equals(), do we need a testEquals for every single
class? or do we still need to check the JavaDoc one by one to find
difference on this method? why not the tool just give some warning to
some possible incompatible?
> Obviously since Japi is Free Software I can't prevent others from making a
> version that does this, but I hope I've shown why I think it would be a bad idea.
>
>
There is another issue of JAPI, pls. correct me if I'm wrong, seems the
*final* information is also ignored. I also think this difference of
method signature is a compatibility issue which could not be overlooked,
because the spec writer might have consider very carefully about which
methods can be overridden and which should be immutable. Comments?
> Stuart.
>
>
>
--
Paulex Yang
China Software Development Lab
IBM
Re: Understanding JAPI tools (was: Re: [jira] Created: (HARMONY-163) Three types in java.util.jar are not implemented in Harmony)
Posted by Stuart Ballard <st...@gmail.com>.
Tim Ellison <t.p.ellison <at> gmail.com> writes:
> Stuart: is there some way to avoid JAPI taking inherited API signatures
> into account when doing the diff? kinda like the javadoc tool.
This is something of a Japi FAQ (I should probably put together a Japi FAQ page
somewhere now that it's no longer the case that pretty much everyone using Japi
is on the Classpath list ;) ).
The answer is no, it doesn't do this, and I'm not going to implement it. The
reason is that whether a method is overridden or not is *not* part of the public
API. Javadoc documents it, sure, but that's not really sufficient to say whether
it's part of the API or not - it's quite likely it was simply easier to write
Javadoc that way (so it didn't have to go and find the doc comments in the
superclass's source file, etc).
The rules of binary compatibility say that moving a method up or down the class
hierarchy is a completely compatible change.
A method may be overridden, or not, purely for performance reasons and the
behavior could be completely identical. For example, LinkedList.subList is not
documented as being overridden, but if it's not, that guarantees that the
iterator() method will always be at least O(N) where N is the startIndex that
the sublist was created with. An overridden LinkedList.subList method could hang
on to the start and end nodes of the list and provide an O(1) implementation of
iterator(). As long as some effort was taken to ensure that serialization stayed
compatible, there's no reason why a Free runtime shouldn't do that optimization
even if Sun doesn't.
I've also heard of cases where Sun documents a method as being overridden even
though as far as any testing can determine, all it does is call super. There
should be no obligation for any Free runtime to duplicate this inefficiency.
It's also possible to implement a method that needs changed behavior in a
subclass by making the superclass delegate some parts of its behavior to
non-public methods, so the superclass method is unchanged but the subclass just
overrides the non-public methods (obviously, this only works if the subclass is
in the same package, but that's pretty common).
Finally, it's possible (albeit unlikely) that even if there *was* an apparent
need to override a method in a subclass because it has different behavior, there
might be some weird optimization-related reason why somebody might want to
actually write it as "if (this instanceof Whatever)" in the superclass. I can't
see why that would happen, but if someone did that and got all the behavior
right, they shouldn't be penalized for it in Japi.
Basically, Japi's business is to test the coverage of the API, and it's a
fundamental design decision that Japi will *not* be testing implementation
details. I've done quite a lot of work fixing bugs where implementation details
inadvertently get exposed in the Japi results and if I find any more I'll fix
them too.
I think this is *extremely* important because, among other things, it's the
*only* reason I feel legally secure in distributing Japi files for the JDK. As
long as they only contain functional information necessary for interoperability,
they're uncopyrightable. If they start exposing copyrightable implementation
details, they become derived works of the JDK, and illegal to distribute (or,
technically, to even create in the first place). And potentially so do the
results of the comparisons. And if you then use those comparisons to make
decisions on what to implement in Harmony, it jeopardizes Harmony's cleanroom
status too. (IANAL; the people who actually decide whether legal risks are
acceptable might think this isn't actually a problem for Harmony, but *I* don't
want to be responsible for it ;) )
The right way to ensure that you've overridden all the right methods is to test
the *behavior* of those methods. Obviously this is a lot more work than a simple
automated run via Japi or equivalent, but it's the only way to get meaningful
results.
Obviously since Japi is Free Software I can't prevent others from making a
version that does this, but I hope I've shown why I think it would be a bad idea.
Stuart.
Understanding JAPI tools (was: Re: [jira] Created: (HARMONY-163)
Three types in java.util.jar are not implemented in Harmony)
Posted by Tim Ellison <t....@gmail.com>.
Paulex Yang wrote:
> Tim
>
> Thank you to point out that. I did refer to the URL your provided. But
> seems the JAPI report ignores some difference, for example, the
> overridden information.
So it does, sorry Paulex.
Stuart: is there some way to avoid JAPI taking inherited API signatures
into account when doing the diff? kinda like the javadoc tool.
> And I raised several JIRAs just for convenience to create patch, I
> consider that a patch within smaller scope maybe introduce smaller risk,
> especially while the SVN structure is not so stable:).
Sure, I just saw a number of JIRAs appearing saying that the API was
wrong and thought that was the end of it. A JIRA with a patch including
implementation and test case is great!
Regards,
Tim
> Tim Ellison wrote:
>> Thanks for the JIRAs Paulex, but to save you a great deal of effort
>> opening a new issue for every API that is missing ;-) I should point out
>> already have the JAPI tool description of what we need to do [1] -- now
>> if you were sending code to fix these issues ... :-)
>>
>> [1] http://www.kaffe.org/~stuart/japi/htmlout/h-jdk15-harmony
>>
>> Regards,
>> Tim
>>
>> Paulex Yang (JIRA) wrote:
>>
>>> Three types in java.util.jar are not implemented in Harmony
>>> -----------------------------------------------------------
>>>
>>> Key: HARMONY-163
>>> URL: http://issues.apache.org/jira/browse/HARMONY-163
>>> Project: Harmony
>>> Type: Bug
>>> Components: Classlib Reporter: Paulex Yang
>>>
>>>
>>> Three types:
>>> public abstract class java/util/jar/Pack200
>>> public interface java/util/jar/Pack200$Packer
>>> public interface java/util/jar/Pack200$Unpacker
>>> are introduced in JSE 5, but not implemented in Harmony
>>>
>>>
>>
>>
>
>
--
Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.
Re: [jira] Created: (HARMONY-163) Three types in java.util.jar are
not implemented in Harmony
Posted by Paulex Yang <pa...@gmail.com>.
Tim
Thank you to point out that. I did refer to the URL your provided. But
seems the JAPI report ignores some difference, for example, the
overridden information.
And I raised several JIRAs just for convenience to create patch, I
consider that a patch within smaller scope maybe introduce smaller risk,
especially while the SVN structure is not so stable:).
Tim Ellison wrote:
> Thanks for the JIRAs Paulex, but to save you a great deal of effort
> opening a new issue for every API that is missing ;-) I should point out
> already have the JAPI tool description of what we need to do [1] -- now
> if you were sending code to fix these issues ... :-)
>
> [1] http://www.kaffe.org/~stuart/japi/htmlout/h-jdk15-harmony
>
> Regards,
> Tim
>
> Paulex Yang (JIRA) wrote:
>
>> Three types in java.util.jar are not implemented in Harmony
>> -----------------------------------------------------------
>>
>> Key: HARMONY-163
>> URL: http://issues.apache.org/jira/browse/HARMONY-163
>> Project: Harmony
>> Type: Bug
>> Components: Classlib
>> Reporter: Paulex Yang
>>
>>
>> Three types:
>> public abstract class java/util/jar/Pack200
>> public interface java/util/jar/Pack200$Packer
>> public interface java/util/jar/Pack200$Unpacker
>> are introduced in JSE 5, but not implemented in Harmony
>>
>>
>
>
--
Paulex Yang
China Software Development Lab
IBM
Re: [jira] Created: (HARMONY-163) Three types in java.util.jar are
not implemented in Harmony
Posted by Tim Ellison <t....@gmail.com>.
Thanks for the JIRAs Paulex, but to save you a great deal of effort
opening a new issue for every API that is missing ;-) I should point out
already have the JAPI tool description of what we need to do [1] -- now
if you were sending code to fix these issues ... :-)
[1] http://www.kaffe.org/~stuart/japi/htmlout/h-jdk15-harmony
Regards,
Tim
Paulex Yang (JIRA) wrote:
> Three types in java.util.jar are not implemented in Harmony
> -----------------------------------------------------------
>
> Key: HARMONY-163
> URL: http://issues.apache.org/jira/browse/HARMONY-163
> Project: Harmony
> Type: Bug
> Components: Classlib
> Reporter: Paulex Yang
>
>
> Three types:
> public abstract class java/util/jar/Pack200
> public interface java/util/jar/Pack200$Packer
> public interface java/util/jar/Pack200$Unpacker
> are introduced in JSE 5, but not implemented in Harmony
>
--
Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.