Upgrade Compatibility Requirements

This is a set of guidelines for keeping the application server releases backward compatible and upgradable as we move forward with V3. All app server components should review their design changes in relation to these guidelines.

Backward compatible in this case means the ability to run unaltered the domains of a previous product release with the new appserver bits. For example, AS10 bits should be able to run AS9.1x domains unaltered. Likewise GlassFish V3 should be able to run GlassFish V2.x domains unaltered.

Common changes that break version backward compatibility.

• Changing the signature of methods in the public API. This can cause an exception to be

thrown on method access.
Any public API changes must be presented to and accepted by the CCC.

• Changing the structure of key configuration files. (e.g. domain.xml), causing parsing

errors or adding new required values to config files could cause problems.
Anything new must be treated as optional and not required.

• Changing the meaning of configuration file data in a significant way. (For example, the

text value of element 'a' represented the number of allowed connections. Now it means
number of times to retry a connection.)
Old and new interpretations must be supported.

• Moving the location of a predefined file and not adding a rule to the new code to look

in the old location.
Both the old and new locations must be supported.

• Changing of default database usually means some revision is needed to the domain.xml

data.
Be mindful to minimize the impact of this type of change.

• Changes to auto-generated code (e.g., the APIs in JSP code generation).

Generated code must be backward compatible or it must be detectable and regenerated.

The general tests for verifying appserver code is backward compatible are:

• Can the new appserver bits point to the old domain and run everything in it without error or changes?

• Can the old domain be copied to a new location and the new appserver bits run it without error or changes?

• Can the new appserver bits configure and deploy a new app to the old domain and run it successfully? It is only required that the altered domain run with the new appserver bits.