On Saturday, Sep 13, 2003, at 22:39 Europe/London, Danny Angus wrote:
4/ We know from discussions regarding Tomcat that the behaviour of a RI
itself forms "case law" and sets precedence about the expected behaviour of
other implementations.
Can someone fill me in on the rest of this, or provide me pointers towards it? I've not been involved with Tomcat's discussions/RI before.
5/ Any acceptable copy of the JavaMail API must comply with the published
specification, being both the wordy specification and the javadocs. It must
also exhibit substantially the same behaviour as Suns product, and any
implementation must be consistent with the RI.
100% agree with this, with the caveat that 'any implementation must be consistent with the RI' does not include bugs in the RI.
Now Alex says..
The dependency is on the InvalidArgumentException and
NullArgumentException. I originally put those in since when they become
internationalised, changes made to those classes will have immediate
benefit to the JavaMail API.
Alex we (and you) have no jurisdiction to make any changes whasoever to the
API, specifically including method signatures.
Completely agree, and I have been very careful to ensure compliance. The method signature remains unchanged, since there are no declared exception types -- it was a case of using IllegalArgumentException instead of NullArgumentException (or vice versa). The latter extends the former, which in turn extends RuntimeException, so has no effect on the method signature and thus stays with compliance of the spec.
What is acceptable is for the internal implementation of the expected
behaviour to be implemented in any way we choose, but that any dependance
not specified by the API should be satisfied internally and not apparent in
any way to any user of the API.
Yes. NAE was a subtype of IAE, which is a subtype of RE which would be what any user could expect from methods in an external class.
That is to say we could use components from many sources, but our resulting
mailapi.jar should be a direct replacement for Sun's one with no additional
requirements.
Agree as well, though there's no reason why any necessary dependent classes could not be bundled in the mailapi.jar file as required. Nor does it have to be self-contained; for example, the mailapi explicitly depends on (but does not contain) the activation framework. And mailapi.jar depends on several other libraries provided by Java 1.4 ...
I do not believe that the specs package cannot include classes outside of
the javax. namespace; indeed, the Sun RI ships with a whole bunch of
com.sun classes as is. There isn't any reason why JavaMail couldn't ship
with an org.apache class or two instead.
The API only consist of the javax.mail.* packages, and only depends upon
java.* and javax.*
The com.sun classes are the refrence implementation and though they depend
upon the API the API does not depend upon them.
The JavaMail API does not (a) have to be self contained, and (b) cannot depend on others. For convenience, outside of Geronimo, it should be packaged in such a way that all dependent classes are part of the same Jar file.
There are also com.sun classes in the mailapi.jar as well -- for example, handlers for data types and so forth - so it is not the case that the mailapi.jar is solely the API; it is the full API and some RI code as well, with the remainder of the RI code (providers, transports etc) provided in their own Jar(s).
The issue at stake is that the bug also exists in the Sun RI.
Actually if it exists it is in the API not the RI.
Yes, my mistake -- it's in the core API class.
You are at liberty to "fix" it but this would then be a deviation from the
API behavoiur which our user would have to be informed of, for the sake of
their sanity if nothing else.
The 'bug' is in the definition of the 'equals' method, which is clearly defined in the Java language in the java.lang.Object class:
The JavaDoc states:
--- 8<--- http://java.sun.com/j2se/1.4.2/docs/api/java/lang/ Object.html#equals(java.lang.Object)
Indicates whether some other object is "equal to" this one.
The equals method implements an equivalence relation on non-null object references:
o It is reflexive: for any non-null reference value x, x.equals(x) should return true.
o It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
o It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
o It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
For any non-null reference value x, x.equals(null) should return false.
--- 8< ---
The implementation in the Sun JavaMail breaks this by not being transitive (that is, it is possible for the equals method to have a.equals(c) and b.equals(c), but not a.equals(b). The implementation I used had the advantage that (a) it was transitive, and that (b) the implementation of the method is more efficient for large numbers of subclasses.
The only time a behavioural difference will be noted is if subclasses of the offending object (URLName) are created.
The absolute question is: what are we trying to achieve in the JavaMail
API reimplementation? Copy it byte-for-byte, including any bugs that are
present in the JavaMail implementation? Or provide something that behaves
correctly as per the JavaDoc? My take on this is that we should implement
to the spec, and not try to represent every bug in the RI, since the
latter will be a moving target.
Well at least now you're beginning to realise why it is not a job to be undertaken lightly.
I never thought it was a job to be undertaken lightly :-) My aim was to recreate the JavaMail implementation for Apache, and implement the specifications as per the JavaMail specs. I was not aiming to recreate every bug in Sun's JavaMail, with the result that there are undoubtedly methods that work in a different manner between the two -- however, the public API will conform to the specification.
These may seem minor but they are symptomatic of a coding approach that may lead to other deviations and I think the entire patch should be reviewed in detail. If someone steps up to do that then it may be appropriate to commit this to a separate branch until done.
Always nice not to be trusted :-)
This has little or nothing to do with trust, Apache projects are meritocracies and operate a system of peer review.
I agree, and this issue is one that did deserve to be discussed openly on the mail review.
You have allegedly made an error of judgement based upon an apparent
difficulty in understanding what is the JavaMail API and what is it's
implementation and what is appropriate for your work on each part. This
has, quite rightly, been picked up by peer review and also quite rightly it
has been suggested that the the rest of your patch be reviewed in detail in
case the same assumtions are manifested elsewhere.
We're here to do this thing correctly, whether or not that offends you.
I have no issues with the implementation, and have no feelings of code ownership for what has been submitted. I am also, for the record, firmly committed to complete compliance with the specification of both JavaMail and any future code I am involved with a J2EE server.
What I objected to was the implication "symptomatic of a coding approach that may lead to other deviations" as if I was against working towards a fully compliant code. Granted, I may make mistakes in the implementation (and others have picked these out) but I am not working on a coding approach that throws this all out of the window.
I have always been very careful to implement the JavaMail APIs based on the JavaDoc
In which case why did you add a dependancy which doesn't exist there?
The dependencies are not part of the equation. There is nothing to say the mailapi.jar can only contain javax.mail classes, which is your assumption. You will note that Sun's mailapi.jar contains both the API and RI code; all I was doing was the same in Geronimo. For when JavaMail is extracted elsewhere, this class could easily be extracted as well and/or replaced with a different implementation. TBH the sooner that JavaMail becomes its own stand-alone module (along with the activation framework) then the less likely these issues will occur.
I also did that within the keeping of the API; no method signatures were harmed in the making of that method.
I hope this sorts out any possible confusion towards my last post(s) on the subject, and that we can continue to use a correct implementation of equals in the URLName class as per the Java specification.
Alex.
