Oracle® Retail Cloud Service Functional Artifacts Guide Release 19.1.000 F31992-01 |
|
Previous |
Next |
This chapter describes versioning strategies and standards.
The following describes types of versioning strategies, as explained in Thomas Erl's book, Web Service Contract Design and Versioning for SOA.
For strict versioning, any compatible or incompatible change results in a new version of the service contract. This type of versioning does not support backward or forward compatibility (for example, new change and new contract).
For flexible versioning, an incompatible change results in a new version of the service contract, and the contract supports backward compatibility but not forward compatibility.
For loose versioning, any incompatible change results in a new version of the service contract, and the contract supports backward and forward compatibility.
The following chart compares the types of versioning strategies listed above. The values in the Characteristics column are described as follows:
Strictness: The rigidity of the contract versioning strategy.
Governance Impact: The amount of governance burden imposed by the strategy.
Complexity: The overall complexity of the versioning process.
Characteristic | Strict Strategy | Flexible Strategy | Loose Strategy |
---|---|---|---|
Strictness | High | Medium | Low |
Governance Impact | High | Medium | High |
Complexity | Low | Medium | High |
For this proposal, there are two primary reasons to version an artifact:
To recognize that an artifact as changed.
To recognize whether the change is breaking or non-breaking, as described below.
A breaking change is also known as non-backward compatibility. For example, newer versions of producers based on the same Business Object will break existing consumers and require a regeneration of the client from the new wsdl.
Non-backward compatible changes include the following:
Removing an operation.
Renaming an operation.
Changing the parameters of an operation, such as data type or order.
A non-breaking change is also known as backward compatibility. For example, newer versions of producers based on the same Business Object can be deployed without breaking existing consumers.
Backward compatible changes include the following:
New operations.
New data types.
New optional fields to existing data types.
Type expansion.
This section provides examples of versioning Retail Business Objects (BO) schemas (XSD)s.
The XSD is versioned by an attribute (version) and the namespace. The namespace is the key versioning point.
Topic | Description |
---|---|
Recommendation | Each XSD has a version attribute. |
Rationale | The version attribute is used to indicate a change has occurred to the XSD. It is a simple counter that starts at 1.00 and bumps when any change is applied. |
Example | targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1"version="1.0"xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" |
Topic | Description |
---|---|
Recommendation | For any change, breaking or non-breaking, the version attribute is incremented. |
Rationale | For a non-breaking change, the version will increment the point. For a breaking change, the version will bump. The breaking version bump equates to the same version reflected in the namespace. |
Example - Non-breaking Change | Original
targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" version="1.0" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" Non-breaking Change targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" version="1.1" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" Breaking Change targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v2" version="2.0" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v2" |
Topic | Description |
---|---|
Recommendation | XSD namespace is versioned. |
Rationale | For breaking changes, the BO XSD namepsace is version controlled. |
Example | The following example shows how the versioning appears, before and after.
Before targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" version="1.0" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" After targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermDesc/v2" version="2.0" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v2" |
Topic | Description |
---|---|
Recommendation | For Parent/Child versioning, if a child version changes (a breaking change) the parent version also must change. |
Rationale | If a parent imports an XSD and it has a breaking change, the parent also will have a breaking change. So the versioning of the parent should reflect that. |
Topic | Description |
---|---|
Recommendation | The Retail Functional Artifacts directory structure does not support multiple versions of a considered XSD is any of its subdirectory. |
Rationale | Oracle Retail PL/SQL applications support only single version of a business object. |
Example | The following directory structure depicting multiple versions of a considered XSD is not allowed. Only one version directory can exist./retail/integration/base/ bo/ (Business Objects) BO (Object Name) v[1] (Version - latest) BO.xsd (BO Schema) v[2] (Version - latest) BO.xsd (BO Schema) |