db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David W. Van Couvering" <David.Vancouver...@Sun.COM>
Subject VOTE: Approach for sharing code
Date Thu, 08 Sep 2005 00:40:54 GMT
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)
}


Mime
View raw message