Component Compatibility

Compatibility is a concern when you create new versions of a component that has already been deployed. When you create a new version of a component, you must ensure that the other objects that use or refer to the component are not broken as a result of the changes. You can use and refer to components by using dependencies, component containment, inheritance, and component targeters.

The provisioning software 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.

Because different versions of components can be deployed to different parts of the data center at different points in time, you should be aware of compatibility requirements and understand the way that changes to one component might affect other existing components. In certain cases, the system will enforce compatibility requirements, in other places 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 the same 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 provisioning software 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 provisioning software also optionally verifies call compatibility when it resolves components that are referenced by certain installed component targeters. See Installed Component Targeters.

Though not required, try to make a component 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 the same as structural compatibility.

The constraints imposed by install compatibility mean that 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 provisioning software 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. A change made to a component type that is not install compatible must be encoded as a new, distinct component version tree with its own type 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 components are not call compatible, they are not install compatible.