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 "SharedComponentVersioningGuidelines" by DavidVanCouvering
Date Sun, 30 Oct 2005 05:35:48 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/SharedComponentVersioningGuidelines

------------------------------------------------------------------------------
  
  Forward compatibility must be guaranteed between patch revisions (from X.Y.Z to X.Y.Z')
and minor revisions (from X.Y to X.Y').  We should strive for forward compatibility between
major releases, but it is not a guarantee.
  
- 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.  
+ 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 calling
a static method to see if the the feature or features are available in the version of the
shared component that has been loaded at runtime.  
  
+ The details of how this is accomplished will be documented in the package-level javadoc
for the {{{org.apache.derby.common}}} package. 
- A shared component must provide a class called {{{<ComponentName>Info}}} that provides
a static method called {{{hasFeature}}}.  This class should be at the top level of the package
for that component, e.g. the info class for the common component should be {{{org.apache.derby.common.CommonInfo}}}.
- 
- 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.S
  
  == 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.
@@ -95, +47 @@

  
  == User Visible Impact and Restrictions ==
  
- With these guidelines in place, there will be no visible impact or restrictions for Derby
users.  
+ The intent is that the shared component infrastructure and code will have minimal visible
impact to users.  
  
+ There may be some unavoidable impact to users who are running in an application environment
where multiple instances of the Derby jars can be loaded by the same classloader.  In particular,
it is possible that one version of the common code may "shadow" another version such that
changes/bugfixes can be hidden in unexpected ways.  Note that these problems already exist
where users are running with two different versions of the engine or two different versions
of the network client within the same classloader context.  Adding common code also makes
it possible for these problems to occur for users who are running different versions of the
network client and embedded client within the same classloader context.
- No visible impact  implies the following checkin requirements for any
- common code.
  
+ In these mixed version environments, users can avoid shadowing issues by (a) ensuring that
the right version is loaded first or (b) using multiple classloaders so that no one classloader
has a mixed version situation.
-    * Derby jar files of the same major version can continue to be mixed within the same
JVM classpath without any difference in behavior from loading these jars in separate classloaders.
-    * Jar file growth is commensurate with functionality improvement.
-    * Replacing any jar with a jar of the same major version will not require any user classpath
changes.
  
- The only exception is if for some reason (and this is to be avoided) a change is made between
major revisions that is not compatible, then if the user is running in a mixed version environment
in the same VM, he or she should attempt to ensure that the jar files from the newer version
are loaded first.  If for some reason this is not possible, the user will need to separate
the two versions by using separate classloaders within the same VM.
+ To help alleviate the confusion and debugging time for these users, we will be providing
documentation describing the potential problems for these kinds of environments and how they
can be solved, and we will output runtime information at startup to show exactly what versions
of each jar file a user is running with and log a warning if the versions are not the same.
+ 
+ We will strive to minimize the impact in mixed version environments using mechanisms such
as support for forward-compatibility and compatibility tests.  
+ 
+ There should be '''no''' visible impact in user environments where there are no mixed versions.

  
  == Testing Impact ==
  
@@ -117, +70 @@

   
  == Introducing New Shared Components and Shared Packages ==
  
- When a developer wishes to introduce a new shared component or a new package within an existing
shared component, this should be put up for a vote.  This is to help ensure that what we are
sharing makes sense and does not accidentally paint us into some kind of architectural corner.
 Adding new classes or methods to an existing shared package does not need to be put up for
a vote but should be reviewed using the standard patch review mechanism.
+ When a developer wishes to introduce a new shared component or a new package within an existing
shared component, this should be put up for a vote requiring at a minimum lazy consensus,
with consensus approval required for large changes to the structure of Derby.  This is to
help ensure that what we are sharing makes sense and does not accidentally paint us into some
kind of architectural corner.  Adding new classes or methods to an existing shared package
does not need to be put up for a vote but should be reviewed using the standard patch review
mechanism.
  

Mime
View raw message