I added a comment to DERBY-289
(http://issues.apache.org/jira/browse/DERBY-289) that is my official
proposal for an approach to sharing code.
I am including it in this email as well for easy reference.
Please vote and/or comment on this proposal.
Thanks,
David
=====
PROPOSAL FOR SHARING CODE IN DERBY
Here are the outlines of how I plan to share code in Derby. This first
version is a high-level description of the approach. After incorporating
your feedback and piloting with the internationalization code, I will write
up a more detailed proposal.
PRINCIPLES AND REQUIREMENTS
It's important to understand and agree upon the principles and requirements
of this feature
- Allow sharing of common code across all parts of the Derby codeline,
in particular between the network client and the engine.
- Make it easy to code agains common components (avoid onerous overhead)
- Support the following binary compatibility rules. This is based
off of the compatibility rules defined for the Apache Portable
Runtime (APR) project (see http://apr.apache.org/versioning.html)
<http://apr.apache.org/versioning.html%29>:
* compatibility guaranteed against later versions until
the major version number changes (e.g. a 10.1 consumer will
work with with 10.2 common classes, but a 10.2 consumer is
not guaranteed to work with 11.0 common classes).
* compatibility guaranteed for all previous patch versions
(e.g. a 10.1.2 consumer will work with 10.1.1 common classes).
* compatibility will be strongly encouraged but not guaranteed
against previous minor versions (e.g. a 10.2 consumer works
with 10.1 common classes, but a 10.3 consumer has a hard
dependency on new methods, it can not work with 10.2
common classes).
* no expectation for compatibility for previous major versions
(e.g. 10.1 is not guaranteed to work with 11.0).
- Support for both direct creation of classes and pluggable infrastructure
where this is needed. Some common classes are very simple, and not
everything should require a pluggable infrastructure.
IMPLEMENTATION PLAN
- Create a new directory java/common
- Create a new package directory under common, org/apache/derby/common
- Classes created within the common package hierarchy needs to follow the
guidelines for common components as described below
- Provide a CommonVersion helper class (described further below)
that allows consumers to detect what version of the common components
is available and determine whether the version is compatible.
- Modify the build script to create a new jar file, derby-common.jar,
which contains all the common classes.
- Update the documentation to describe the need for this new jar file
in the classpath/ext directory/etc.
COMMON CLASS CODING GUIDELINES
These guidelines are for any classes in the common package with
public methods. These guidelines should actually be applied to major
releases as well, as much as possible, but compatibility is not
required between major releases.
Compatibility will be tested with a new suite of compatibility
tests (currently being devised by Rick Hillegas)
- Class names and package names should not change between patch or
minor releases.
- Existing public method names, method signatures, and public field
names should not change between patch or minor releases.
- Existing public fields or methods should not be removed between patch
or minor releases.
- Although the code of existing methods can change, the defined behavior,
in terms of semantics and observable effects, should not change
between patch and minor releases.
- New classes, packages, public fields and methods can be added between
minor releases, but not between patch releases, as this would break
forward-compatibility for patch releases.
VERSION DETECTION
The Version class will be defined as a common class and is used to
define a version and check for compatibility between a consumer and
the common package. Here is a first pass at the methods on this class.
public class Version
{
/**
* return the String representation of the version of the
* common package
*/
static Version getCommonVersion()
/**
* Create a version object. For 10.1.2 you would say
* <code>new Version(10, 1, 2)</code>
*/
public Version(int major, int minor, int patch)
int getMajor()
int getMinor()
int getPatch()
/**
* Check to see if a consumer is compatible with the common package.
* This method should be called when the consumer is being initialized,
* and an exception should be thrown if they are not compatible.
*
* If the consumer version is older than or the same as the common
* package version, we have all the knowledge we need to determine
* compatibility.
*
* If the consumer is newer than the common package, then we need
* to check for forward compatibility (e.g. to see if the older common
* package can work with the newer consumer). If only the patch
* versions differ, then by our compatibility rules the two versions
* must be compatible. If the major or minor versions differ then we
* use the firstIncompatibleVersion parameter to determine forward
* compatibility. If firstIncompatibleVersion is null then we
* assume full forward compatibility (the consumer is saying "I can
* work with anything").
*
*
* Usage example:
*
* checkCommonCompatibility(new Version(10, 1, 2), null);
* checkCommonCompatibility(new Version(11, 0, 1), new Version(10, 9, 0)
*/
boolean checkCommonCompatibility(Version consumer,
Version firstIncompatibleVersion)
}
begin:vcard
fn:David W Van Couvering
n:Van Couvering;David W
org:Sun Microsystems, Inc.;Database Technology Group
email;internet:[EMAIL PROTECTED]
title:Senior Staff Software Engineer
tel;work:510-550-6819
tel;cell:510-684-7281
x-mozilla-html:TRUE
version:2.1
end:vcard
