geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Blewitt <>
Subject Re: Status: JavaMail API implementation now at Alpha quality
Date Tue, 16 Sep 2003 17:51:33 GMT
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<--- 
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  

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.


View raw message