db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David Van Couvering (JIRA)" <derby-...@db.apache.org>
Subject [jira] Commented: (DERBY-289) Enable code sharing between Derby client and engine
Date Thu, 08 Sep 2005 00:38:31 GMT
    [ http://issues.apache.org/jira/browse/DERBY-289?page=comments#action_12322900 ] 

David Van Couvering commented on DERBY-289:


Here are the outlines of how we 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.  


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

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


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

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.


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)

> Enable code sharing between Derby client and engine
> ---------------------------------------------------
>          Key: DERBY-289
>          URL: http://issues.apache.org/jira/browse/DERBY-289
>      Project: Derby
>         Type: Improvement
>   Components: Network Client
>     Versions:,,,
>  Environment: N/A
>     Reporter: David Van Couvering
>     Assignee: David Van Couvering
>     Priority: Minor
>      Fix For:

> Right now, there is no way for the Derby network client to share code with the Derby
engine.  We should have a separate jar file, e.g. derby_common.jar, that contains shared code
and is used by both the client and the engine.  

This message is automatically generated by JIRA.
If you think it was sent incorrectly contact one of the administrators:
For more information on JIRA, see:

View raw message