This package and its sub-packages provides functionality that is shared between top-level Derby jar files.

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.

## List of Available Shared Components

Shared code is provided through one or more shared components. This section lists each shared component, providing essential information for the consumers of these components.

When you create a shared component, you need to add a section here to describe it for your consumers.

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. 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.

### Common

Description:
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.

Packages:
The Common shared component contains the following packages, all under `org.apache.derby.shared`

- common.error - utility code for error and exception handling
- common.i18n - utility code for internationlization
- common.reference - contains classes with shared constants
- common.info - utility code that provides runtime information

Consumers
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.

## Terms and Definitions

Shared Component
A shared component is a collection of one or more packages under `org.apache.derby.shared` 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).

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.

Backward Compatibility
A consumer built against version X of a shared component should work with version X' of a module where X' > X. This is called backward compatibility.

Forward Compatibility
A consumer built against version X of a shared component should work with version X' of a module where X' < X. This is called forward compatibility.

Mixed Version Environment
If it is possible for two or more versions of Derby to be available to the same classloader, this is called a mixed version environment. 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.

Any shared code infrastructure that we implement must meet this requirement.

## Issues with Compatibility

Using backward and forward compatibility can allow Derby to run fairly well in a mixed version environment. However, there are a couple of significant issues with this approach.

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.

Maintaining backward and forward compatibility also does not solve the issue of shadowing. 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.

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.

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.

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.

This can be solved in one of two ways. Which approach we use has yet to be decided.

- Derby classloader - 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.

- Code copying - 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, `org.apache.derby.shared.common.i18n.MessageUtil` would be copied as `org.apache.derby.shared.engine.common.i18n.MessageUtil` for use by derby.jar and as `org.apache.derby.shared.client.common.i18n.MessageUtil` for use by derbyclient.jar. In this way there is no chance of clashing or shadowing in a mixed version environment.

  The problem with this approach is that developers must use discipline to modify the original source file and not the generated version. For this reason, this approach will only be used if the classloader approach ends up being unfeasible.

Note that these solutions do not 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 do 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.

## Location and Distribution of Shared Components

All shared components should comprise of one or more packages under the package `org.apache.derby.shared` (stored in the source tree under `java/common/org/apache/derby/shared`).

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.

## User Visible Impact and Restrictions

The intent is that the shared component infrastructure and code will have minimal to no visible impact to users.