db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Db-derby Wiki] Update of "ModuleVersioningGuidelines" by DavidVanCouvering
Date Tue, 04 Oct 2005 19:33:45 GMT
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/ModuleVersioningGuidelines

------------------------------------------------------------------------------
  
  Review comments for these guidelines can be created, viewed and responded to at ModuleVersioningGuidelinesReview
  
- This document describes our guidelines around modules in Derby, where a module is a group
of one or more packages made available as an cohesive unit which can be shared across multiple
consumers, either internally or externally to Derby.  As of this writing, the only module
like this is the proposed common code module (see [http://issues.apache.org/jira/browse/DERBY-289
 DERBY-289])
+ This document describes our guidelines around shared components in Derby, where a shared
component is a collection of one or more packages that is used across multiple subsystems
within Derby. Very loosely, I would define a "subsystem" as the code contained in one of the
top-level source directories, e.g. engine, client, drda, tools, etc.  As of this writing,
the only shared component like this is the proposed common code component (see [http://issues.apache.org/jira/browse/DERBY-289
 DERBY-289]).  Other components may be defined in the future as needed (for example, perhaps
the DRDA networking code should be separated out as an independent shared component).
  
- These guidelines are based on the [http://jakarta.apache.org/commons/releases/versioning.html
Jakarta Runtime Versioning Guidelines].  There are some areas that these guidelines do not
cover, however, which we will address here:
+ The guidelines for shared components in Derby are based on the [http://jakarta.apache.org/commons/releases/versioning.html
Jakarta Runtime Versioning Guidelines].  There are some areas that these guidelines do not
cover, however, which we will address here:
  
     * Mixed Version support
  
@@ -16, +16 @@

  
     * Deprecation guidelines and mechanisms
  
+    * Packaging of common components
+ 
  == Mixed Version Support ==
  
  As much as possible, two applications should be able to use different versions of Derby
within the same Java VM without having to resort to creating specialized classloaders.  This
is enabled by supporting forward compatibility as described below.  
  
- == Version Publishing and Detection ==
- 
- Every module must provide access to its version information through a static method that
returns an instance of `org.apache.derby.iapi.services.ProductVersionHolder`.  
- 
- '''Note''' - I would like to migrate `ProductVersionHolder` and the other classes in the
`info` package to `org.apache.derby.common.info` as they are already shared across tools,
client, DRDA and engine.
- 
  == Guidelines for Forward Compatibility ==
  
- Wherever possible, a consumer built against version X.Y of a module should work with version
X.Y' of a module where Y' < Y.  If the consumer uses new functionality added in version
X.Y of the module, it should degrade to X.Y' level functionality.  In the rare cases where
this is not achievable, the consumer should throw an exception explaining that it requires
version X.Y or greater of the module (rather than an obtuse Java exception like `NoSuchMethodException`).
 The consumer takes adavantage of the version detection mechanism described above to query
the version of the module and then take appropriate action.
+ In general, a consumer built against version X.Y of a shared component should work with
version X.Y' of a module where Y' < Y.  This is called ''forward compatibility''.
+ 
+ If the consumer uses new functionality added in version X.Y of the module, it should degrade
to X.Y' level functionality.  In the ''rare cases'' where this is not achievable, the consumer
should throw an exception explaining that it requires version X.Y or greater of the shared
component (rather than an obtuse Java exception like `NoSuchMethodException`).  
+ 
+ The consumer decides it can work with a given version of a shared component not by looking
up its version number and then extrapolating what features are available, but instead by directly
querying the component to see if the shared component provides the feature or features it
is looking for.  
+ 
+ A shared component must provide a class called {{{<ComponentName>Info}}} that provides
a static method called {{{hasFeature}}}.  This method takes a single parameter which is a
feature identifier.  If the shared component implementation recognizes the feature identifier,
it returns true, otherwise it returns false.   Here is an example definition and usage using
the common component.  Assume that a consumer is making use of a new whizbang feature in the
message utilities in a newer version of the common component which is not available in older
versions.
+ 
+ Here is the old version of the {{{CommonInfo}}} class: {{{#!java
+ 
+ public static class CommonInfo
+ {
+   public static final int COOL_FEATURE = 1;
+   private static final int MAX_FEATURE = COOL_FEATURE;
+ 
+   public static boolean hasFeature(int featureId)
+   {
+       return featureID <= MAX_FEATURE;
+   }
+ }
+ 
+ }}}
+ 
+ Here is the new definition of the {{{CommonInfo}}} class: {{{#!java
+ 
+ public static class CommonInfo
+ {
+   public static final int COOL_FEATURE = 1;
+   public static final int WHIZBANG_FEATURE = 2;
+   private static final int MAX_FEATURE = WHIZBANG_FEATURE;
+ 
+   public static boolean hasFeature(int featureId)
+   {
+       return featureID <= MAX_FEATURE;
+   }
+ }
+ 
+ }}}
+ 
+ The consumer is then built with the new common component and uses the new {{{CommonInfo}}}
class definition: {{{#!java
+ 
+ if ( CommonInfo.hasFeature(CommonInfo.WHIZBANG_FEATURE) )
+ {
+   // use whizbang feature
+ }
+ else
+ {
+   // use older mechanism
+ }
+ 
+ }}}
+ 
+ Note that the constant {{{CommonInfo.WHIZBANG_FEATURE}}} is compiled down to a constant
integer, so there will not be runtime errors if the older version of the component has been
loaded.
+ 
+ '''NOTE:''' I still need to investigate to see if you can have a method call to a non-existent
method in your code as long as the code is never executed.
  
  === Deprecation Guidelines ===
  A method or an interface may be deprecated.  This is done using the @deprecated tag in the
method or interface Javadoc.  A method or interface must be available for 2 major releases
after it is deprecated.  For example, if it is deprecated in version 8.2, it can be removed
in version 10.0 or greater.  An exception to this rule may occur if it becomes clear that
there is still heavy use of this interface.
  
+ === Distribution of Shared Components ===
+ 
+ To help make explicit the various shared components within Derby and what is contained in
them, our internal build will create a seprate JAR file for each shared component. 
+ 
+ However, to keep a very simple user experience, when we create a release, the classes in
the shared component JAR files will be merged into derby.jar and derby-client.jar. 
+ 
    
  

Mime
View raw message