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.

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

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

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

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

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


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 :-).

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