java/shared/org/apache/derby/shared/package.html - derby - Git at Google

 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to you under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <HTML>
 <HEAD>
 	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
 	<TITLE></TITLE>
 	<META NAME="CHANGEDBY" CONTENT="David Van Couvering">
 </HEAD>
 <BODY>
 <P>This package and its sub-packages provides functionality that is
 shared between top-level Derby jar files.
 <p>
 <b>NOTE - at this time, this code is not yet shared, but is used solely
 by derbyclient.jar.  The code placed here was to enable internationalization
 of the client.  It is put under the shared package because we expect
 a framework to be put into place soon that will allow sharing across
 jar files.</b>
 <P>
 <H2><A NAME="List of Shared Components"/>List of Available Shared Components</H2>
 Shared code is provided through one or more <I>shared components</I>.
 This section lists each shared component, providing essential information for
 the consumers of these components.
 <p>
 When you create a shared component, you need to add a section here to describe
 it for your consumers.
 <p>
 <b>NOTE: Introducing a new shared component requires a vote with
 consensus approval.  Adding a new package within an existing shared component
 requires a vote with lazy consensus. </b> 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.
 <H3>Common</H3>
 <b>Description:</b>
 <BR>
 This shared component is for code that is (or could be) used across all
 Derby jar files.  This is a good place for utility routines and services
 such as logging/tracing, internationalization, error handling, etc.
 <p>
 <b>Packages:</b>
 <br>
 The Common shared component contains the following packages, all under
 <code>org.apache.derby.shared</code>
 <br>
 <ul>
 <li><b>common.error</b> - utility code for error and exception handling
 <li><b>common.i18n</b> - utility code for internationlization
 <li><b>common.reference</b> - contains classes with shared constants
 <li><b>common.info</b> - utility code that provides runtime information
 </ul>
 <p>
 <b>Consumers</b>
 <br>
 The only jar file currently using (and thus including) the packages in this
 component is derbyclient.jar but it is intended to be used by other jar
 files once we have a working shared component infrastructure in place.
 <H2><A NAME="TermsAndDefinitions"/>Terms and Definitions</H2>
 <p>
 <b>Shared Component</b>
 <br>
 A <i>shared component</i> is a collection of one or more packages under
 <code>org.apache.derby.shared</code> that is used by code in more than one
 Derby jar file (for example, between derbyclient.jar and derby.jar, or between
 derbynet.jar and derbytools.jar).
 <p>
 There need only be one shared component
 in the system (e.g. the shared package and all its subpackages), but in some
 cases it may be desirable or necessary to split out some of these packages into
 a separate shared component.  For example, if there are packages that only need
 to be shared between the network client and the network server, there is no need
 to put these classes into derby.jar, and thus these should probably be
 pulled out as a separate shared component.
 <p>
 <b>Backward Compatibility</b>
 <br>
 A consumer built against version X of a shared component should
 work with version X' of a module where X' &gt; X. This is called
 <i>backward compatibility</i>.
 <p>
 <b>Forward Compatibility</b>
 <br>
 A consumer built against version X of a shared component should
 work with version X' of a module where X' &lt; X. This is called
 <i>forward compatibility</i>.
 <p>
 <b><A NAME="MixedVersionEnvironment"/>Mixed Version Environment</b>
 <br>
 If it is possible for two or more versions of Derby to be available to
 the same classloader, this is called a <i>mixed version environment</i>.
 It is a requirement that Derby continue to function correctly even in a
 mixed version environment.  In particular, a Derby class that consumes
 a shared component must continue to run without failure, regardless of
 the ordering of the search path of the classloader or any other factors.
 <p>
 Any shared code infrastructure that we implement must meet this
 requirement.
 <p>
 <H2><A NAME="Issus with Compatibility"/>Issues with Compatibility</H2>
 Using backward and forward compatibility can allow Derby to run
 <i>fairly well</i> in a mixed version environment.  However, there
 are a couple of significant issues with this approach.
 <p>
 First of all, maintaining compatibility, particularly forward compatibility,
 places a huge burden of responsibility on Derby engineers, and can also
 create some ugly code.  Basically, for forward compatibility, you are required
 to check to see if any new feature exists in the current runtime environment
 before actually using that feature.  This can get pretty ugly.
 <p>
 Maintaining backward and forward compatibility also does
 not solve the issue of
 <i>shadowing</i>.  Shadowing occurs when a particular application is upgraded
 to use the new behavior of an existing
 shared component, but this behavior is not available because it is shadowed by
 an older version of the component.
 <p>
 For example, say Application A and Application B are both deployed in the
 same application container.  The jar files for A (including Derby jars) are
 placed in directory A and the jar files for B (including Derby jars) are
 placed in directory B.  In this container environment, the jars for A are
 loaded before the jars for B.
 <p>
 B is running at version 10.4 of Derby and A is running at 10.3.  The Derby
 code for B depends upon functionality provided in a new shared package that
 does not exist in version 10.3.  B then upgrades to 10.4.1 to get a bug fix,
 and are quite happy.  Then A upgrades to 10.4.0, which includes the new
 shared package.  The shared package in A shadows the shared package in B,
 and all of a sudden B's bugfix disappears and regresses.
 <p>
 For these reasons, we need another approach that guarantees that the
 correct version of a shared class
 is loaded for each consumer.  We need to guarantee that Application B
 use 10.3 shared classes, and Application C uses 10.4 shared classes.
 <p>
 This can be solved in one of two ways.  Which approach we use has yet to
 be decided.
 <P>
 <ul>
 <li><b>Derby classloader</b> - in this approach a specialized classloader is
 written that loads only from the correct jar file.  This approach is
 currently under investigation and implementation by David Van Couvering.
 <p>
 <li><b>Code copying</b> - in this approach, at build time every shared class
 copied and given a different package name for each jar file that uses it.
 For example,
 <code>org.apache.derby.shared.common.i18n.MessageUtil</code> would be
 copied as
 <code>org.apache.derby.shared.engine.common.i18n.MessageUtil</code>
 for use by derby.jar and as
 <code>org.apache.derby.shared.client.common.i18n.MessageUtil</code>
 for use by derbyclient.jar.  In this way there is no chance of clashing
 or shadowing in a mixed version environment.
 <p>
 The problem with this approach is that developers must use discipline
 to modify the <b>original</b> source file and <b>not</b> the generated
 version.  For this reason, this approach will only be used if the
 classloader approach ends up being unfeasible.
 </ul>
 <p>
 Note that these solutions do <b>not</b> allow complete flexibility
 in terms of mixed version environments.  In particular, the application
 programmer or runtime administrator can not run two different versions of
 the embedded driver within the same classloader.  As a matter of fact,
 that exact configuration is currently not allowed.  The proposed solutions
 only guarantee that if you <b>do</b> have a mixed version environment
 (even by accident), nothing strange or unexpected will happen.  It also
 allows the network driver to run at
 a different version from the embedded driver within the same classloader.
 <H2><A NAME="LocationAndDistributionOfSharedComponents"></A>Location
 and Distribution of Shared Components</H2>
 <P>All shared components should comprise of one or more packages
 under the package <code>org.apache.derby.shared</code>
 (stored in the source tree under
 <code>java/common/org/apache/derby/shared</code>).
 </P>
 <P>Although it would be conceptually nice to have a separate JAR file
 for each shared component, it is a priority for us to keep a very
 simple user experience. For this reason, the classes of a shared
 components will be merged into the appropriate subset of the existing
 jar files.
 </P>
 <H2><A NAME="UserVisibleImpact"></A>User Visible
 Impact and Restrictions</H2>
 The intent is that the shared component infrastructure and code will have
 minimal to no visible impact to users.
 </BODY>
 </HTML>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to you under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<HTML>
	<HEAD>
	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
	<TITLE></TITLE>
	<META NAME="CHANGEDBY" CONTENT="David Van Couvering">
	</HEAD>
	<BODY>
	<P>This package and its sub-packages provides functionality that is
	shared between top-level Derby jar files.
	<p>
	<b>NOTE - at this time, this code is not yet shared, but is used solely
	by derbyclient.jar. The code placed here was to enable internationalization
	of the client. It is put under the shared package because we expect
	a framework to be put into place soon that will allow sharing across
	jar files.</b>
	<P>
	<H2><A NAME="List of Shared Components"/>List of Available Shared Components</H2>
	Shared code is provided through one or more <I>shared components</I>.
	This section lists each shared component, providing essential information for
	the consumers of these components.
	<p>
	When you create a shared component, you need to add a section here to describe
	it for your consumers.
	<p>
	<b>NOTE: Introducing a new shared component requires a vote with
	consensus approval. Adding a new package within an existing shared component
	requires a vote with lazy consensus. </b> 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.
	<H3>Common</H3>
	<b>Description:</b>
	<BR>
	This shared component is for code that is (or could be) used across all
	Derby jar files. This is a good place for utility routines and services
	such as logging/tracing, internationalization, error handling, etc.
	<p>
	<b>Packages:</b>
	<br>
	The Common shared component contains the following packages, all under
	<code>org.apache.derby.shared</code>
	<br>
	<ul>
	<li><b>common.error</b> - utility code for error and exception handling
	<li><b>common.i18n</b> - utility code for internationlization
	<li><b>common.reference</b> - contains classes with shared constants
	<li><b>common.info</b> - utility code that provides runtime information
	</ul>
	<p>
	<b>Consumers</b>
	<br>
	The only jar file currently using (and thus including) the packages in this
	component is derbyclient.jar but it is intended to be used by other jar
	files once we have a working shared component infrastructure in place.
	<H2><A NAME="TermsAndDefinitions"/>Terms and Definitions</H2>
	<p>
	<b>Shared Component</b>
	<br>
	A <i>shared component</i> is a collection of one or more packages under
	<code>org.apache.derby.shared</code> that is used by code in more than one
	Derby jar file (for example, between derbyclient.jar and derby.jar, or between
	derbynet.jar and derbytools.jar).
	<p>
	There need only be one shared component
	in the system (e.g. the shared package and all its subpackages), but in some
	cases it may be desirable or necessary to split out some of these packages into
	a separate shared component. For example, if there are packages that only need
	to be shared between the network client and the network server, there is no need
	to put these classes into derby.jar, and thus these should probably be
	pulled out as a separate shared component.
	<p>
	<b>Backward Compatibility</b>
	<br>
	A consumer built against version X of a shared component should
	work with version X' of a module where X' > X. This is called
	<i>backward compatibility</i>.
	<p>
	<b>Forward Compatibility</b>
	<br>
	A consumer built against version X of a shared component should
	work with version X' of a module where X' < X. This is called
	<i>forward compatibility</i>.
	<p>
	<b><A NAME="MixedVersionEnvironment"/>Mixed Version Environment</b>
	<br>
	If it is possible for two or more versions of Derby to be available to
	the same classloader, this is called a <i>mixed version environment</i>.
	It is a requirement that Derby continue to function correctly even in a
	mixed version environment. In particular, a Derby class that consumes
	a shared component must continue to run without failure, regardless of
	the ordering of the search path of the classloader or any other factors.
	<p>
	Any shared code infrastructure that we implement must meet this
	requirement.
	<p>
	<H2><A NAME="Issus with Compatibility"/>Issues with Compatibility</H2>
	Using backward and forward compatibility can allow Derby to run
	<i>fairly well</i> in a mixed version environment. However, there
	are a couple of significant issues with this approach.
	<p>
	First of all, maintaining compatibility, particularly forward compatibility,
	places a huge burden of responsibility on Derby engineers, and can also
	create some ugly code. Basically, for forward compatibility, you are required
	to check to see if any new feature exists in the current runtime environment
	before actually using that feature. This can get pretty ugly.
	<p>
	Maintaining backward and forward compatibility also does
	not solve the issue of
	<i>shadowing</i>. Shadowing occurs when a particular application is upgraded
	to use the new behavior of an existing
	shared component, but this behavior is not available because it is shadowed by
	an older version of the component.
	<p>
	For example, say Application A and Application B are both deployed in the
	same application container. The jar files for A (including Derby jars) are
	placed in directory A and the jar files for B (including Derby jars) are
	placed in directory B. In this container environment, the jars for A are
	loaded before the jars for B.
	<p>
	B is running at version 10.4 of Derby and A is running at 10.3. The Derby
	code for B depends upon functionality provided in a new shared package that
	does not exist in version 10.3. B then upgrades to 10.4.1 to get a bug fix,
	and are quite happy. Then A upgrades to 10.4.0, which includes the new
	shared package. The shared package in A shadows the shared package in B,
	and all of a sudden B's bugfix disappears and regresses.
	<p>
	For these reasons, we need another approach that guarantees that the
	correct version of a shared class
	is loaded for each consumer. We need to guarantee that Application B
	use 10.3 shared classes, and Application C uses 10.4 shared classes.
	<p>
	This can be solved in one of two ways. Which approach we use has yet to
	be decided.
	<P>
	<ul>
	<li><b>Derby classloader</b> - in this approach a specialized classloader is
	written that loads only from the correct jar file. This approach is
	currently under investigation and implementation by David Van Couvering.
	<p>
	<li><b>Code copying</b> - in this approach, at build time every shared class
	copied and given a different package name for each jar file that uses it.
	For example,
	<code>org.apache.derby.shared.common.i18n.MessageUtil</code> would be
	copied as
	<code>org.apache.derby.shared.engine.common.i18n.MessageUtil</code>
	for use by derby.jar and as
	<code>org.apache.derby.shared.client.common.i18n.MessageUtil</code>
	for use by derbyclient.jar. In this way there is no chance of clashing
	or shadowing in a mixed version environment.
	<p>
	The problem with this approach is that developers must use discipline
	to modify the <b>original</b> source file and <b>not</b> the generated
	version. For this reason, this approach will only be used if the
	classloader approach ends up being unfeasible.
	</ul>
	<p>
	Note that these solutions do <b>not</b> allow complete flexibility
	in terms of mixed version environments. In particular, the application
	programmer or runtime administrator can not run two different versions of
	the embedded driver within the same classloader. As a matter of fact,
	that exact configuration is currently not allowed. The proposed solutions
	only guarantee that if you <b>do</b> have a mixed version environment
	(even by accident), nothing strange or unexpected will happen. It also
	allows the network driver to run at
	a different version from the embedded driver within the same classloader.
	<H2><A NAME="LocationAndDistributionOfSharedComponents"></A>Location
	and Distribution of Shared Components</H2>
	<P>All shared components should comprise of one or more packages
	under the package <code>org.apache.derby.shared</code>
	(stored in the source tree under
	<code>java/common/org/apache/derby/shared</code>).
	</P>
	<P>Although it would be conceptually nice to have a separate JAR file
	for each shared component, it is a priority for us to keep a very
	simple user experience. For this reason, the classes of a shared
	components will be merged into the appropriate subset of the existing
	jar files.
	</P>
	<H2><A NAME="UserVisibleImpact"></A>User Visible
	Impact and Restrictions</H2>
	The intent is that the shared component infrastructure and code will have
	minimal to no visible impact to users.
	</BODY>
	</HTML>