[ http://issues.apache.org/jira/browse/DERBY-289?page=comments#action_12322900 ]
David Van Couvering commented on DERBY-289: ------------------------------------------- PROPOSAL FOR SHARING CODE IN DERBY Here are the outlines of how we plan to share code in Derby. This first version is a high-level description of the approach. After incorporating your feedback and piloting with the internationalization code, I will write up a more detailed proposal. PRINCIPLES AND REQUIREMENTS It's important to understand and agree upon the principles and requirements of this feature - Allow sharing of common code across all parts of the Derby codeline, in particular between the network client and the engine. - Make it easy to code agains common components (avoid onerous overhead) - Support the following binary compatibility rules. This is based off of the compatibility rules defined for the Apache Portable Runtime (APR) project (see http://apr.apache.org/versioning.html): * compatibility guaranteed against later versions until the major version number changes (e.g. a 10.1 consumer will work with with 10.2 common classes, but a 10.2 consumer is not guaranteed to work with 11.0 common classes). * compatibility guaranteed for all previous patch versions (e.g. a 10.1.2 consumer will work with 10.1.1 common classes). * compatibility will be strongly encouraged but not guaranteed against previous minor versions (e.g. a 10.2 consumer works with 10.1 common classes, but a 10.3 consumer has a hard dependency on new methods, it can not work with 10.2 common classes). * no expectation for compatibility for previous major versions (e.g. 10.1 is not guaranteed to work with 11.0). - Support for both direct creation of classes and pluggable infrastructure where this is needed. Some common classes are very simple, and not everything should require a pluggable infrastructure. IMPLEMENTATION PLAN - Create a new directory java/common - Create a new package directory under common, org/apache/derby/common - Classes created within the common package hierarchy needs to follow the guidelines for common components as described below - Provide a CommonVersion helper class (described further below) that allows consumers to detect what version of the common components is available and determine whether the version is compatible. - Modify the build script to create a new jar file, derby-common.jar, which contains all the common classes. - Update the documentation to describe the need for this new jar file in the classpath/ext directory/etc. COMMON CLASS CODING GUIDELINES These guidelines are for any classes in the common package with public methods. These guidelines should actually be applied to major releases as well, as much as possible, but compatibility is not required between major releases. Compatibility will be tested with a new suite of compatibility tests (currently being devised by Rick Hillegas) - Class names and package names should not change between patch or minor releases. - Existing public method names, method signatures, and public field names should not change between patch or minor releases. - Existing public fields or methods should not be removed between patch or minor releases. - Although the code of existing methods can change, the defined behavior, in terms of semantics and observable effects, should not change between patch and minor releases. - New classes, packages, public fields and methods can be added between minor releases, but not between patch releases, as this would break forward-compatibility for patch releases. VERSION DETECTION The Version class will be defined as a common class and is used to define a version and check for compatibility between a consumer and the common package. Here is a first pass at the methods on this class. public class Version { /** * return the String representation of the version of the * common package */ static Version getCommonVersion() /** * Create a version object. For 10.1.2 you would say * <code>new Version(10, 1, 2)</code> */ public Version(int major, int minor, int patch) int getMajor() int getMinor() int getPatch() /** * Check to see if a consumer is compatible with the common package. * This method should be called when the consumer is being initialized, * and an exception should be thrown if they are not compatible. * * If the consumer version is older than or the same as the common * package version, we have all the knowledge we need to determine * compatibility. * * If the consumer is newer than the common package, then we need * to check for forward compatibility (e.g. to see if the older common * package can work with the newer consumer). If only the patch * versions differ, then by our compatibility rules the two versions * must be compatible. If the major or minor versions differ then we * use the firstIncompatibleVersion parameter to determine forward * compatibility. If firstIncompatibleVersion is null then we * assume full forward compatibility (the consumer is saying "I can * work with anything"). * * * Usage example: * * checkCommonCompatibility(new Version(10, 1, 2), null); * checkCommonCompatibility(new Version(11, 0, 1), new Version(10, 9, 0) */ boolean checkCommonCompatibility(Version consumer, Version firstIncompatibleVersion) } > Enable code sharing between Derby client and engine > --------------------------------------------------- > > Key: DERBY-289 > URL: http://issues.apache.org/jira/browse/DERBY-289 > Project: Derby > Type: Improvement > Components: Network Client > Versions: 10.0.2.1, 10.0.2.0, 10.0.2.2, 10.1.1.0 > Environment: N/A > Reporter: David Van Couvering > Assignee: David Van Couvering > Priority: Minor > Fix For: 10.2.0.0 > > Right now, there is no way for the Derby network client to share code with > the Derby engine. We should have a separate jar file, e.g. derby_common.jar, > that contains shared code and is used by both the client and the engine. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
