Component Compatibility

Compatibility is a concern when you modify or create new versions of a component that has already been deployed. Each time you modify a component and check it in, you create a new version of that component. When you modify a component, you must ensure that other objects that use or reference that component are not broken as a result of the changes. The ways in which you can use or reference components are by using dependencies, component targeters, component containment, and inheritance.

The N1 SPS product supports the following types of component compatibility:

• Call compatibility describes the set of changes that you can make to a component and still ensure that relationships that exist through dependencies and component targeters are not violated.

• Install compatibility describes the set of changes that you can make to a component and still ensure that relationships that exist through inheritance and component containment relationships are not violated.

Different versions of components can be deployed to different parts of the data center at different points in time. Thus, you should be aware of compatibility requirements and understand the way in which changes to one component might affect other existing components. In certain cases, the N1 SPS product enforces compatibility requirements, while in other cases you must ensure that the new component is compatible.

For a list of the types of changes that can be made to a component, see Appendix A, Component Change Compatibility.

Call Compatibility

A component is call compatible with another component if uses of the first component can be safely replaced with uses of the other in these cases:

• When making a call to a <control>, <uninstall>, or <snapshot> block of the first component

• When checking for dependencies of the first component by using <checkDependency> or <createDependency>

• When referring to a variable of the first component, by using configuration generation :[component:AB:var]

Call compatibility is also known as API compatibility or interface compatiblity.

Usually, two call-compatible components are different versions of a component that are in the same version tree. However, the second component can also be in a distinct version tree if it is an instance of the first component.

The N1 SPS product enforces call compatibility for components that provide system services. When a system service is updated to refer to a new component, the new component must be call compatible with the original component. This policy ensures that clients of the system service can continue to function properly when the system service is upgraded.

The N1 SPS product also optionally verifies call compatibility when it resolves components that are referenced by certain installed component targeters. See Installed Component Targeters.

Though not required, ensure that a component is call compatible with earlier versions of itself.

Install Compatibility

A component can be install compatible with another component. The first component must be call compatible with the other component. Uses of the other component must also be able to be replaced safely with uses of the first component in these cases:

• When making a call to an install block of the other component

• When a component extends from the other component

• When a component contains a reference to the other component

Install compatibility is also known as structural compatibility.

Any existing installed component can be safely replaced by another install-compatible component. You do not have to modify the data structures that describe how the original was installed. Call compatibility is a much weaker statement, because the call-compatible component might need to be reinstalled to properly update the data structures.

For install compatibility to hold, both components must belong to the same version tree. They cannot be components from two distinct version trees.

The N1 SPS product only enforces install compatibility for components that serve as types, which are called component types. When a component type is updated to refer to a new version of a component, the new version is install compatible with the original version. Thus, you can make install-compatible updates to component types without rebuilding and reinstalling all of the existing components that have been derived from that type.

If you make a change to a component type that is not install compatible, you must create a new component type in a new version tree with a new name. In such cases, the new component type can maintain call compatibility with the original by extending from the original component type. To easily identify the relationship between types, use a versioning system to encode component type names. For example, the component names EJB-1.0 and EJB-1.1 are an easy way to indicate that EJB-1.1 is a later version of the EJB-1.0 component type.

Install compatible implies call compatible, but the reverse is not true. Also, if a component is not call compatible, it cannot be install compatible.