Core Service versioning
To support backward compatibility, new releases of SDL Tridion return data that an old client can handle gracefully. For Java, the XmlBeans proxy generator is most reliable to handle compatibility issues.
Every SDL Tridion release aims to expose Core Service endpoints that are backward compatible with existing Core Service clients (the service contract is maintained). This means that typically, if you upgrade to a new release of SDL Tridion, you can leave your code that interacts with the Core Service unchanged. Your existing calls to the Core Service interface continue to work, because the existing service contract is still supported.
Of course, if you want to make use of new functionality offered by a new release (new parameters, new methods, and so on), you must modify and recompile your existing code, and explicitly connect to the new end points.
Thus far, only the service contract with version number 2010, introduced in SDL Tridion 2011, has been dropped.
- Because the SDL Tridion 2011 SP1 endpoints are still supported, your existing 2011 service contract calls to the Core Service still work.
- Because the SDL Tridion 2011 endpoints are no longer supported, you must update and recompile code that uses the 2010 service contract.
| Service contract version number | Supports endpoints introduced in | Introduced in |
|---|---|---|
| 2010 | SDL Tridion 2011 | SDL Tridion 2011 |
| 2011 | SDL Tridion 2011, SDL Tridion 2011 SP1 | SDL Tridion 2011 SP1 |
| 2012 | SDL Tridion 2011 SP1, SDL Tridion 2013 | SDL Tridion 2013 |
| 2013 | SDL Tridion 2011 SP1, SDL Tridion 2013, SDL Tridion 2013 SP1 | SDL Tridion 2013 SP1 |
In addition, what a Core Service call returns (the data contract) is not versioned and will change over time. As a result, a new release of SDL Tridion may change the data returned by a Core Service call. For example, the same command may result in data being returned that is of a data type that did not exist in a previous release.
You can guard against this by checking for specific types of data being returned that indicate a compatibility issue. If you detect such data being returned, you can then choose how to handle the unsupported return data.
Specifically, this means the following:
- Existing properties will have the same type in the new release.
- New properties will be optional and only affect an old interface call if the client cannot handle the new property. Deserialization of such unexpected data may fail on some Web service proxies (though not on the recommended proxies: WCF and Java Axis XmlBeans).
- New enumeration (enum) values will be returned to an old interface call as a reserved enum value called
UnknownByClient. - New subclasses will be downgraded to the nearest base class that exists in the release to which your interface call belongs.
In addition to the service contract and data contract, when calling the Core Service from Java, compatibility also depends on your choice of proxy generator. SDL recommends using Java XmlBeans to generate your proxy.