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

[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 DanDebrunner:
http://wiki.apache.org/db-derby/ForwardCompatibility

New page:
= Derby Public Interfaces & Forward Compatibility =

= WORK IN PROGESS =
/!\
Initial set of public interfaces from an e-mail discussion on
the derby-dev list. The list is subject to change.
/!\

== Goal ==

Derby strives to acheive that public interfaces must remain forward compatible across releases
The goal is to allow any application written against the public interfaces an older version of Derby can run, without
any changes, against a newer version of Derby.

Detailed information on [http://db.apache.org/derby/papers/versionupgrade.html Derby's versioning scheme]. 

== Public Interfaces ==

An interface must be providing useful and reasonable functionality for an application.
For example changing a public api from throwing a not-implemented exception to
implementing the functionality is not a regression.  :-)  Applications that are relying on broken
behaviour or unreasonable un-documented behaviour should not stand in the way of improving Derby.

 * Derby's SQL language support

 * Derby's JDBC support
 
 * Derby's embedded published/public api classes (defined by the published api javadoc target)
   * http://db.apache.org/derby/docs/10.1/publishedapi/ (for 10.1)

 * Derby's system tables (catalogs) as documented. Note that new releases may add columns to existing system tables, or add new allowable values for type columns etc.. JDBC DatabaseMetaData is the preferred way to obtain information about database.

 * Derby's network api - DRDA protocol support

 * Jar file names, class path requirements

 * External behaviour defined by jar file manifest entries, e.g. OSGi bundling now and auto-loading of JDBC driver in the future.

 * Platform support
    * J2SE 1.3/1.4/1.5 support
    * 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

== Exceptions ==

There will be occasions where the Derby community does introduce
regressions or what might be considered regressions by some. Any such
item should be a deliberate choice by the community, not by accident. 

Examples are:

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