--- schema_version: "1" id: 11a1560d57d484d192726c5e1ed61a281661c1a7613cfe0cc608d031dc642043 title: Forward Compatibility Patterns collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-sdk/latest/forward-compatibility-patterns.md canonical_url: https://docs.mulesoft.com/mule-sdk/latest/forward-compatibility-patterns source_site: docs.mulesoft.com content_type: documentation content_hash: 8de1bf390d30b9a6fc033136a81270a6d7cea5f1002e0dfe7fdef0678e8f7c00 description: MuleSoft Documentation Site release: "1.13" latest: true --- --- product: Mule SDK version: 1.13 is-latest-version: true keywords: mule, sdk, forward compatibility, RuntimeVersion, MuleVersion, conditional behavior --- # Forward Compatibility Patterns > For the full documentation index, see: https://docs.mulesoft.com/llms.txt When building forward-compatible modules, you often need to use newer SDK features while providing fallback behavior for older runtimes. The following patterns show how to implement conditional behavior based on the Mule runtime version. ## Check the Mule Runtime Version Use the `@RuntimeVersion` annotation to inject the current Mule Runtime version into your component. You can apply this annotation to fields of type `org.mule.runtime.api.meta.MuleVersion`. > [!NOTE] The `mule-sdk-api` artifact has a dependency on `mule-api` for basic APIs that aren’t > intended to evolve over time. `MuleVersion` is one of these stable APIs, so there’s no > `org.mule.sdk.api` counterpart for it. You can safely use `org.mule.runtime.api.meta.MuleVersion` > in forward compatible modules. ```java import org.mule.runtime.api.meta.MuleVersion; import org.mule.sdk.api.annotation.RuntimeVersion; public class MyOperations { @RuntimeVersion private MuleVersion runtimeVersion; public void myOperation() { if (runtimeVersion.atLeast("4.12.0")) { // Use newer feature } else { // Use fallback behavior } } } ``` The `MuleVersion` class provides methods to compare versions:
MethodDescription

atLeast(String version)

Returns true if the Mule runtime version is equal to or greater than the specified version.

atLeastBase(String version)

Returns true if the base version (ignoring patch level) is equal to or greater than the specified version.

The runtime version is constant across your module, so @RuntimeVersion applies only at the field level. Centralize your version-dependent logic in a shared field rather than checking in every operation. ## Call New Methods in Existing APIs SDK APIs can add new methods in later versions. If you call a method that doesn’t exist on an earlier Mule runtime version, you get a `NoSuchMethodError`. The SDK doesn’t introspect which methods your code actually calls. Even if a method has `@MinMuleVersion("4.12.0")`, using it doesn’t automatically raise your component’s Minimum Mule Version. You are able to deploy a module to earlier versions where the method doesn’t exist. For this reason, you must check the Mule runtime version before calling new methods, and provide fallback behavior for older versions. ### Example: Using a New Method with Fallback The following example shows how to conditionally call a method that exists in Mule 4.12.0 and later: ```java import org.mule.runtime.api.meta.MuleVersion; import org.mule.sdk.api.annotation.RuntimeVersion; import org.mule.sdk.api.runtime.streaming.StreamingHelper; public class MyOperations { @RuntimeVersion private MuleVersion runtimeVersion; public void processStream(InputStream stream, StreamingHelper streamingHelper) { if (runtimeVersion.atLeast("4.12.0")) { // Use new reset() method available in 4.12.0 streamingHelper.reset(stream); } else { // Implement fallback for older runtimes where reset() doesn't exist if (stream instanceof Cursor) { ((Cursor) stream).seek(0); } else { stream.reset(); } } } } ``` If no fallback is possible, explicitly annotate your operation with `@MinMuleVersion` to restrict it to compatible versions. ## Use Newer APIs Without Raising Minimum Version If you use a newer API but provide fallback behavior for older Mule runtime versions, you can prevent that API from raising your component’s Minimum Mule Version. Combine Mule version checking with `@DoNotEnforceMinMuleVersion` to keep your component available on earlier versions while using new features when available. ```java import org.mule.runtime.api.meta.MuleVersion; import org.mule.sdk.api.annotation.DoNotEnforceMinMuleVersion; import org.mule.sdk.api.annotation.RuntimeVersion; public class MyOperations { @RuntimeVersion private MuleVersion runtimeVersion; public void myOperation(@DoNotEnforceMinMuleVersion NewFeatureType input) { if (runtimeVersion.atLeast("4.12.0") && input != null) { // Use new feature when available } else { // Fallback behavior for earlier versions } } } ``` The `input != null` check is necessary because parameters with types from `org.mule.sdk.api` resolve to `null` on earlier versions that don’t recognize the type. By combining the version check with `@DoNotEnforceMinMuleVersion`, you: - Prevent the API from raising your component’s Minimum Mule Version - Safely use the feature on later Mule versions - Provide fallback behavior when the feature isn’t available ## Best Practices for Forward-Compatible Code Follow these guidelines when implementing version-dependent behavior: - Check versions before calling new methods Failing to do so causes `NoSuchMethodError` at runtime. - Centralize version checks Use a shared field annotated with `@RuntimeVersion` rather than checking in every method. - Test on multiple Mule runtime versions Verify your fallback logic works correctly on the earliest Mule version you support. - Document runtime-specific behavior If a feature behaves differently on earlier versions, document this for your users. ## See Also - [Controlling Version Propagation](https://docs.mulesoft.com/mule-sdk/latest/forward-compatibility-enforcement) - [Working with Minimum Mule Versions](https://docs.mulesoft.com/mule-sdk/latest/forward-compatibility-min-mule-version) - [SDK Forward Compatibility](https://docs.mulesoft.com/mule-sdk/latest/forward-compatibility) - [HTTP-Based Connectors](https://docs.mulesoft.com/mule-sdk/latest/http-based-connectors) for the forward-compatible `org.mule.sdk.api.http` client API