Re: VOTE: Approach for sharing code

I thought Kathey/Dan's idea of generating copies of the common code
into two separate directories was interesting and solved a lot of problems,
and I thought it would be worthwhile to walk through this in a bit more
detail.

I took a look at all the relevant use cases I could think of and describe
the steps involved and what the user experience will be like.  Through
this effort I did find a couple of possible issues that may make us want
to think twice about this approach.  Perhaps others can think of ways around
these issues.  I have labelled issues uncovered with the tag <ISSUE> in
the text below, rather than try and summarize them here.


CREATING A COMMON CLASS

Say a developer wants to add a new class for logging.

The developer creates the package directory
java/common/org/apache/derby/common/logging

Under this directory she creates the new class Logger.  A simple
version is shown here.

===========

/**
   Derby class org.apache.derby.common.logging.Logger

   Copyright  yada yada
*/

 
package org.apache.derby.common.logging;

/**
* Class description
*/
public class Logger
{
  public void log(int level, String message)
  {
    // log this message
  }
}

===========

Note that this looks like a regular class.  This is so you
can edit it as a Java class in Java-aware IDEs.


BUILDING THE COMMON PACKAGE

The build script for the org/apache/derby/common directories
will not compile the class.  Instead, it invokes a build-time
tool that will perform the following actions for each class
in the org/apache/derby/common hierarchy:

- Create a copy of the file in java/common/org/apache/derby/engine/common
  and change the package name in this copy to
org.apache.derby.engine.common.

- Create a copy of the file in java/common/org/apache/derby/client/common
  and change the package name in this copy to org.apache.derby.client.common

- No lines will be added or removed.  This ensures that during debugging
  the line numbers in the generated code match the line numbers in the
  original source.

- Compile both copies

The client/common and engine/common directories will be created if
they don't exist and will NOT be included in the svn directory structure.

ant clobber/clean will remove the client/common and engine/common
directories.

The generated source files will NOT be removed after compilation so
that developers can use a source debugger and so that you can navigate
to the source for browsing in Java-aware IDEs.  More on debugging below.

The classes under engine/common will be placed into derby.jar and
derbytools.jar.  The classes under client/common will be placed into
derbyclient.jar.

<ISSUE>
QUESTION: is there a need for mixed versions between the tools and
engine code?  If so we will need to generate a third package hierarchy
org.apache.derby.tools.common.*.
</ISSUE>



USING A COMMON CLASS

Code under java/engine, java/drda, java/tools and java/testing should
all import the classes under org.apache.derby.engine.common.

Code under java/client should import the classes under
org.apache.derby.client.common.

Common code unit tests can use either package hierarchy.



DEBUGGING A COMMON CLASS

Stack traces and debug stacks will point to the generated code
under engine/common or client/common depending on whether you
are debugging engine/tools/network code or client code.

<ISSUE>
If the debugger takes a developer to a common file and they see a bug,
the temptation will be to fix it in place and recompile.  This will
not work -- their changes will be lost when they run the build script.

The developer must instead go to the original source file in
org/apache/derby/common and fix it there.  I suspect this is going
to be confusing and annoying.

We could avoid this confusion by removing the generated source file
after compilation, but I think that this would be even more annoying,
as you wouldn't be able to do interactive source-level debugging.  Most
debugging is just stepping through code that you aren't modifying; you
just want to follow the logic.
</ISSUE>



CHECKING IN A COMMON CLASS

You check in the original source, NOT the generated source.

<ISSUE>
This is another potential source of errors.  A newbie developer
could check in the generated source, and we would have to clean
it out
</ISSUE>


RUNTIME WITH MIXED VERSIONS

If you have a 10.2 client and a 10.3 embedded driver in the same
VM, there is no conflict.  The 10.2 client code uses the 10.2
client/common classes and the 10.3 embedded/engine code uses the
engine/common classes



Daniel John Debrunner wrote:

[david.vancouvering.vcf]

---

begin:vcard
fn:David W Van Couvering
n:Van Couvering;David W
org:Sun Microsystems, Inc.;Database Technology Group
email;internet:david.vancouvering@...
title:Senior Staff Software Engineer
tel;work:510-550-6819
tel;cell:510-684-7281
x-mozilla-html:TRUE
version:2.1
end:vcard

---