[Db-derby Wiki] Update of "ForwardCompatibility" by KatheyMarsden

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The following page has been changed by KatheyMarsden:
http://wiki.apache.org/db-derby/ForwardCompatibility

------------------------------------------------------------------------------
  
  == Goal ==
  
- Original goal (with minor re-wording)
- 
  The goal is to allow any application written against the public interfaces of an older version of Derby to run,
  without any changes, against a newer version of Derby.
  
- Alternate goal
- 
- This is our goal: An application which runs against a Derby release today ''that does not depend on interfaces explicitly declared as unstable or on interfaces which are not documented'' will also run tomorrow against all subsequent patch and minor releases. We strive to minimize churn for applications migrating to the next major release of Derby.  However these migrations may entail application changes.
- 
- 
- 
  Detailed information on [http://db.apache.org/derby/papers/versionupgrade.html Derby's versioning scheme]. 
  
  == Exceptions ==
  
  There will be occasions where the Derby community does introduce
- regressions or what might be considered regressions by some. Examples of such exceptions include fixing incorrect implementations of a standard or a correctness bug (for example a query returning the wrong results).  Such changes may break existing applications.  We will strive to avoid such changes but they may occur.  Any such change should be a deliberate choice by the community, not by accident. 
+ regressions or what might be considered regressions by some. Examples of such exceptions include fixing incorrect implementations of a standard or a correctness bug (for example a query returning the wrong results).  Such changes may break existing applications.  We will strive to avoid such changes but they may occur.  Any such change should be a deliberate choice by the community, not by accident. If at all possible such changes should be deferred to minor release boundaries.
  
  Specific examples:
  
       * Disabling !ResultSet.getXXXStream to be called twice on the same column in the same row in 10.2. Previously 10.1 and 10.1 allowed this but returned the incorrect data. It seems a reasonable choice as it stops incorrect behaviour and is in-line with the JDBC spec.
  
       * Dropping support of JDK 1.3/JDBC2.1. Technically a regression but it seems unlikely that by the time the community does this that there will be any demand for JDK 1.3. (We've voted that it's ok to do this in 10.3, but someone has to scratch that itch)
+ 
+     * The Derby community voted that the client driver should match embedded for implementation defined behaviour.
+ 
+ We will mark any fixes or product changes that intentionally change product behaviour and might affect existing applications by checking the [http://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&&pid=10594&customfield_12310090=Existing+Application+Impact&sorter/field=issuekey&sorter/order=DESC  Existing Application Impact] checkbox.  Also the "Release Note Needed" box will be checked as well and user impact described in ReleaseNoteFormat. 
  
  Users of Derby have several options under the hopefully rare occasion that a new release breaks their application:
     * Fix their application
@@ -156, +152 @@

        * Adding new indexes to the table
        * Changing the primary key for the table (?)
  
+ Changes to the system tables cannot occur for soft upgrade.  Associated upgrade code and tests will be added for compatible changes.
+ 
  === Incompatible Changes for Data File Formats ===
  
  '''I need help with this one'''
@@ -190, +188 @@

  === Changes to a Network Protocol ===
  DRDA is the current protocol we use, and is the underpinning of client/server compatibility
  
- Generally the network protocol needs to be versioned and the client and server need to negotiate to a given version level.  The types of changes described below are changes to an existing version of the protocol.  In general it is very difficult to make a compatible change to an existing version of the protocol.
+ Generally the network protocol needs to be versioned and the client and server need to negotiate to a given version level.  The types of changes described below are changes to an existing version of the protocol.  
+ 
+ Compatible Change
+    * Add unimplemented DRDA support to client or server with appropriate logic to trigger it only for Derby versions that support it.
+ 
+ Incompatible Change
+ 
+    * Add unimplemented DRDA Support to client or server that might impact compatiblity with earlier releases of client or server.
  
  === Other Miscellaneous Interfaces ===
  
@@ -244, +249 @@

  ||System stored procedures||Stable|| || ||
  ||Query plan output as displayed by RUNTIMESTATISTICS||Private|| ||There are example outputs in the documentation but the full format of RUNTIMESTATISTICS is not document and therefore this should be considered a private interface. '''Do we need a Private Unstable classification for this?'''||
  
- == Other notes ==
+ == JVM Support and Version Interoperability ==
    * Platform support
-      * J2SE 1.3/1.4/1.5 support
+      * J2SE 1.3.1/1.4/1.5 support (Note: 10.2 is the last supported release for 1.3.1)   
       * J2ME/CDC/Foundation support
       * Pure Java to enable run-anywhere
  
    * Derby's versioning of its on-disk database format is described here:
      *http://db.apache.org/derby/papers/versionupgrade.html
- 
-   * The Derby development community voted that network client driver will be changed (over time) to match embedded where possible for implementation defined behaviour
  
    * Derby will at a minimum negotiate down to the lower interface revision level:
        * When different versions of Derby client and server are used together (in the same or different JVM's)