Re: Suggestions for Jawin 2.x development

All are  good points.

See inline comments. And more later.  All I can do today:-)
----- Original Message -----
From: "Morten Andersen" <[email protected]>
To: <[email protected]>
Sent: Sunday, June 06, 2004 11:59 AM
Subject: [JAWIN] Suggestions for Jawin 2.x development


> Hi all
>
> As promised a "start out"-list of what could happen in Jawin 2.x if we
> decide to make a branch with the existing 1.x-code and develop 2.x in
> the HEAD of the CVS.
+1 for branching
>
> - the most important thing is that in the 2.x code we are free to "play"
> with new solutions and changes that will break user code working with
> Jawin 1.x. The increase in major release number will signal to all users
> of Jawin that they should expect that things break when upgrading code
> from using Jawin 1.x to 2.x.
>
> - we are free to increase the supported JDK's version if we need. Eg.
> Java NIO -> JDK1.4. Personally I am fine with JDK1.4 as the oldest
> supported release (after all it is 2 years old by now). But if anybody
> have strong feelings (or projects requiring it) for JDK1.3 we of course
> have to make any code that uses JDK1.4 features in a way so Jawin can
> still be used with JDK1.3.
>
> - we should finally get rid of some of the old "dead" source we are
> dragging around, this includes the following:
>         - com.develop code - both native and the src/com-tree. I fear we
will
> get a mutual headache if we try to support both.
>         - obsolete packages/classes must go out or be updated:
>                 * org.jawin.event
>                 * org.jawin.tools - some generator classes - but for what?
>                 * org.jawin.marshal.COMCustom and COMMarshal - there are
no native
> implementation for the native methods in these classes.
>                 * org.jawin.IEnumVariant - uses the above mentioned
COMCustom +
> COMMarshall classes.
>
> - we could clean the Jawin-core (I think it has evolved over some time,
> and now it needs a gentle cleanup to be easier to access and comprehend
> for newcomers - both users and new developers) - this includes (but is
> not limited too - please add points):
>         - move the "non-core" code out of Jawin and into a separate
src-tree -
> eg. a donated-source for donated stubs.
>         - better javadoc for the central Jawin classes (I have started on
this
> boring task :-)).
>         - minimize the API's the Jawin user should know, down to mostly
three:
>                 * FuncPtr for win32 invokes (DLL entry points).
>                 * COMPtr for vtable based COM-objects (the threading
helper methods,
> should be included in this class, instead of users having to now the
> IdentityManager class).
>                 * DispatchPtr for IDispatch based COM-objects (since it
extends
> COMPtr, it will also include the threading helper methods).
>         - the only other helper classes that some users should know are
> (perhaps this could be made even better? - good ideas are welcome):
>                 * Variant and Variant.ByrefHolder: if the marshaling
details is needed
> for dispatch calls.
>                 * Ole32: for the CoInitialize() and
CoUninitialize()-methods.
>                 * NakedByteStream: if the caller is not using generated
stubs, and
> would like to build a call-stack manually.
>                 * ReturnFlags: if using FuncPtr, for controlling the error
handling.
>                 * IdentityManager: the registerProxy()-method, if building
the stub
> for, and registering a interface manually.

Maybe more than a little gently.

>
> - we could change the marshaling code so we uses Java NIO instead of the
> existing NakedByteStream-solution. We should of course profile on the
> solution to see if it actually does increase performance. Especially for
> purposes like this, I started making some (primitive) performance tests
> that should probably be extended.

Yes this is a good place to explore.
>
> - we should refactor the (internal) interfaces to minimize scope (eg.
> mostly private and package scoped where possible), and to better align
> with Java terms (eg. the Variant.marshalIn() and marshalOut(), could be
> renamed to "standard" method names for serialize methods: readObject()
> and writeObject(), and so on).

Yea the variant stuff is very inefficient.  The checking and casing on
Variant happens all over the place including on the cpp side.
>
> - I already started on refactoring some of the variant-marshaling on
> both Java and C++ side to finish the already started support for ByRef
> variants (used for [out] parameters in dispatch calls). As part of the
> testing of this refactoring, unit-tests for ByRef and SafeArrays was
> added. - this changes the calling convention for calling Dispatch.invoke
> for ByRef parameters. Before they should be wrapped in an array[1] of
> the base type. This made it impossible to pass in ordinary arrays with
> just one element. So now ByRef parameters must be wrapped in a
> Variant.ByrefHolder-variable to be marshaled correctly.
Yes this fixes the one or many array issue nicely.
>
> - and finally the transition from 1.x to 2.x would be a good time to
> finally solve the licensing issues we have been discussing previously:
> http://discuss.develop.com/archives/wa.exe?A2=ind0309B&L=JAWIN&P=R237&I=-3
> and
>
http://discuss.develop.com/archives/wa.exe?A2=ind0309C&L=JAWIN&P=R2&D=0&I=-3
> At that time nothing was done about it. So i propose we do the following
> for the 2.x code:
>         - use the BSD-license:
> http://www.opensource.org/licenses/bsd-license.php - where we set
> <OWNER>="The Jawin Project" and <ORGANIZATION>="The Jawin Project and
> DevelopMentor" and <YEAR>=2004.
>         - this should be done since the original "DevelopMentor OpenSource
> Software License" is as far as I can tell actually identical to the
> BSD-license. EXCEPT for clause 3 in the DevelopMentor OS license, which
> Stuart has permitted to be deleted in thread no. 2 above (a similar
> clause was actually present in the original BSD-license, but was deleted
> in 1999).
>         - the main advantages of using the BSD-license are as see it:
>                 * it is almost similar to the existing license, so I
assume Stuart
> will accept it.
>                 * it is one of the OSI approved licenses.
>                 * it is well known, so most users/companies knows it, and
won't have
> to consult their legal department to verify whether it is okay or not to
> use Jawin in their solutions.
>                 * personally I like it since it allows usage of Jawin in
most projects
> (both other opensource projects as well as commercial closed source
> projects). See eg. the Mozilla.org explanation for the license:
> http://www.mozilla.org/MPL/FAQ.html#5
>
> If we agree on the licensing issue, Roger, can you contact Stuart and
> get his permission to do this.

Yes I'll draw his attention to this email.

>
>
> And finally a more "organizational" suggestion: Perhaps we should start
> using some of the functionality SourceForge.net offers for Jawin
> development (eg. the different bug-tracker functionality - eg. I only
> recently saw that somebody posted a problem in the "Support
> Requests"-forum
> (http://sourceforge.net/tracker/?atid=514370&group_id=66397&func=browse)
> back in the end of 2003.
>
> One way to start out could be to add some of the requested features from
> the above list to the RFE-forum:
> http://sourceforge.net/tracker/?group_id=66397&atid=514372 - this way
> they won't be forgotten with this email :-).

Good also.
>
> Please feel free to comment (both critically and supportive) on these
> ideas, and to come with further enhancements.
> Best Regards
> Morten