You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by Apache Wiki <wi...@apache.org> on 2006/03/28 22:08:34 UTC
[Db-derby Wiki] Update of "ForwardCompatibility" by DavidVanCouvering
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 DavidVanCouvering:
http://wiki.apache.org/db-derby/ForwardCompatibility
------------------------------------------------------------------------------
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
@@ -58, +28 @@
* 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)
+
+ == What is an Interface? ==
+
+ An interface is any "interaction point" of the software, something that customers may touch and may therefore depend upon. Each interface is assigned a specific stability level which communicates the guarantee, or the contract, to how and when these interfaces will change in a non-compatible way. Here are some examples of interfaces:
+
+ * Application Programmatic Interfaces (APIs)
+ * Command Line Interfaces (CLIs). A CLI is actually often split up into sub-interfaces
+ * CLI arguments
+ * stdin
+ * stdout
+ * error codes
+ * File formats
+ * File names
+ * Network port numbers
+ * Network protocols
+ * Environment variables
+ * Directory locations
+ * Jar file names
+ * Class names
+ *
+
+ == Stability Levels ==
+
+ To help describe the types of stability guarantees Derby provides for a given interface, we identify the following stability levels. These definitions are inspired by the [http://www.opensolaris.org/os/community/arc/policies/interface-taxonomy/ OpenSolaris interface taxonomy]
+
+ === Stable ===
+ * Incompatible change allowed in major release (X.0)
+
+ This is an interface which we expect others to depend upon to remain stable enough for them to build their own products or systems on top of. Most of our public interfaces should be given the stability level of Stable.
+
+ === Standard ===
+ * Incompatible change allowed in major release (X.0)
+
+ These are interfaces that we make available which are produced by a standards body, or which is an industry standard that we feel is unlikely to change in incompatible ways.
+
+ === Unstable ===
+ * Incompatible change allowed in minor release (x.Y)
+
+ This is usually for new functionality that we feel is experimental or unstable. Documentation should make it very clear that this interface may change between minor releases. Changes to unstable interfaces should be documented in the release notes.
+
+ === Private ===
+ * Incompatible change allowed at any time
+
+ Private interfaces are interfaces which are not documented for external users, and generally users should not be depending upon,
+ and which can change at any time.
+
+ Some private interfaces must have a level of stability beyond the private guarantee, even though they are not documented. For example, the on-disk format for Derby databases must remain stable across minor releases and in general changes to this format should be rare, because of the impact on upgrade.
+
+ == Interface Table ==
+
+ This table describes each of the interfaces Derby provides, and the stability guarantee we provide for that interface.
+
+ '''NOTE: This table is still a draft form and is subject to change'''
+
+ ||'''Interface Name'''||'''Stability Level'''||'''Specification Reference (if available)'''||'''Comments'''||
+ ||SQL language support||Standard||SQL92 and SQL99||See (SQL table) for complete listing||
+ ||JDBC support||Standard||[need reference here]|| ||
+ ||Embedded published/public api classes (defined by the published api javadoc target)||Stable||http://db.apache.org/derby/docs/10.1/publishedapi/|| ||
+ ||System tables (catalogs) as documented||Stable|| ||Note that adding columns to existing system tables, or add new allowable values for type columns etc., is considered a compatible change. JDBC DatabaseMetaData is the preferred way to obtain information about database.||
+ ||DRDA||Standard|| [need ref] || ||
+ ||Jar file names||Stable|| || ||
+ ||Class path requirements||Stable|| || ||
+ ||Jar file manifest entires that define external behavior||Stable|| ||e.g. OSGi bundling now and auto-loading of JDBC driver in the future||
+ ||derby.log file format||Unstable|| ||
+ ||SQL States returned by Derby SQLExceptions||Unstable|| ||
+ ||Error message text||Private|| ||Note that this means canon-based tests can not make claims that a regression has occurred because the output from error messages has changed||
+ ||Install directory hierarchy||Stable?|| ||Script writers may require guarantees as to the location of files within the system||
+ ||Tools (ij, dblook, etc.) command-line name and arguments||Stable|| || ||
+ ||Tools class names||Stable|| || ||
+ ||Tools stdout||Private|| || ||
+ ||Tools stderr||Private|| || ||
+ ||Tools error codes||Unstable|| || ||
+ ||ij properties||Stable|| || ||
+ ||Environment variables used by Derby||Stable|| || ||
+ ||Default port number used by Derby network server||Stable|| || ||
+ ||JDBC URL format and driver properties for Derby JDBC drivers||Stable|| || ||
+ ||Documented derby properties||Stable|| || ||
+ ||Undocumented derby properties||Private|| || ||
+ ||Network server properties||Stable|| || ||
+
+
+
+ == Other notes ==
+ * 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
+