Skip to main content

Managing Dependencies

General Information​

The SAP Cloud SDK for Java is a set of libraries that itself depends on other libraries. To manage these relationships it relies on the dependency management functionality of Maven.

This article shows how to manage dependencies for the SAP Cloud SDK for Java specifically. For general information on how to deal with dependencies refer to the resources linked above and throughout this page.

The SAP Cloud SDK Bill-of-Material​

The SAP Cloud SDK provides a Bill-of-Material (BOM). It comprises all dependencies and their specific version that the SAP Cloud SDK relies upon.

It can be used in the dependency management as follows:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.sap.cloud.sdk</groupId>
            <artifactId>sdk-bom</artifactId>
            <version>use-latest-version-here</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

It helps in various ways:

  • Minimizing the effort for updating SAP Cloud SDK versions
  • Ensuring all SAP Cloud SDK components are used consistently with the same version
  • Compatibility with some other key SAP libraries or frameworks like XSUAA and CAP.
  • Avoiding some potential dependency conflicts
  • Checking which components & their respective version the SAP Cloud SDK depends upon

For these reasons we highly recommend using the BOM in your project.

Alternative: SAP Cloud SDK Modules Bill-of-Material

Besides the SAP Cloud SDK Bill-of-Material sdk-bom there is also the SAP Cloud SDK Modules Bill-of-Material sdk-modules-bom. It manages the version of all SAP Cloud SDK modules only. sdk-modules-bom does not manage versions of transitive dependencies and hence can be chosen to resolve dependency version conflicts.

SAP Cloud SDK Maven Plugins

Please be aware that neither the sdk-bom nor the modules-bom will manage the versions of any SAP Cloud SDK Maven plugins (like the odata-generator-maven-plugin) you may use. It is required to specify a version for such plugins explicitly, otherwise dependency conflicts may occur.

Dealing With Dependency Conflicts​

When using multiple libraries, you will probably run into a version conflict at some point. This is caused by the way dependencies are resolved. If you are using two libraries A and B where both depend on a different version of C you encounter a conflict.

This conflict can only be solved by you as the consumer be explicitly stating which version of C should be used.

This guide outlines this problem in more detail and provides general guidance on how to find and resolve such problems.

Updating the SAP Cloud SDK Version​

You may run into dependency related problems when updating SAP Cloud SDK versions since its dependencies are frequently updated. Here are some recommendations from our experience that should help to mitigate any problems:

We recommend increasing the SAP Cloud SDK version in a dedicated change e.g. a pull request.

  • This isolates the change and makes finding problems easier.

Look out for MethodNotFound and ClassDefNotFound exceptions.

  • They are common when a library is provided with an unexpected version.

Check out our release notes.

  • Under improvements, you will see all dependency changes.

Use mvn dependency:tree to analyze the dependency tree.

  • It shows where dependencies are used and in which version.

Google the error message.

  • Usually, you will at least get an idea which library is causing the problems.

Update the SAP Cloud SDK version frequently.

  • This mitigates the risk per update and ensures you are up to date.

Overriding Dependency Versions of the SAP Cloud SDK Bill-of-Material​

Sometimes you may want to override the version of a specific dependency the SAP Cloud SDK is using. You can achieve this by listing it in the dependency management.

For example to override the version of SLF4J:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.sap.cloud.sdk</groupId>
            <artifactId>sdk-bom</artifactId>
            <version>latest-sdk-version</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>your-slf4j-version</version>
        </dependency>
    </dependencies>
</dependencyManagement>
note

Remember that including a dependency in the <dependencyManagement> section only enforces its version and scope. It does not yet include it as a dependency in your project.

Notes on the SAP Java Buildpack​

Warning

The BOM for the SAP Java Buildpack (SJB) sdk-sjb-bom has been deprecated. From now on, whenever you switch to a newer version of the SJB, it might not be magically compatible with the SDK.

Alternatively, you can use BOMs provided by the SAP Java Buildpack directly, as described here.

Compatible Java and Spring Versions

Please note that the SAP Java Buildpack is only compatible with version 7 of the Java EE and the javax.* namespaace. Consequently, frameworks based on the newer Jakarta EE and the jakarta.* namespace are not supported.

In particular, Spring 6.X, Spring Boot 3.X and Java 17 are not compatible with the SJB.

The SAP Java Buildpack brings some dependencies that are also brought by the SAP Cloud SDK. This can lead to conflicts when using a war deployment.

To prevent any SAP Java Buildpack issues we recommend using the cf-tomee7-bom (or Tomcat or TomEE BOMs) followed by our sdk-bom.

tip

The SAP Java Buildpack generally does not affect typical Spring Boot applications which are packed into an executable jar by default.

Managing the Buildpack Version​

We recommend setting a fixed Buildpack version in the manifest.yml and updating it regularly. Use cf buildpacks to see which Buildpacks are currently available. Please note that usually only the last 3 Buildpack versions are kept alive, and usually every two weeks a new version is released. Consequently, with this strategy, you should update at least once a month.

In general, this is safer than using always the latest Buildpack. Because this strategy avoids that a simple restart can break your application due to a changed Buildpack.

In particular, it ensures that the specific Buildpack + SAP Cloud SDK combination has been tested.

Also see this note on Buildpack versioning.

note

There are no known dependencies in the Community Java Buildpack that could interfere with the ones provided by the SAP Cloud SDK. Still, the same strategy is also valid and useful for the community Buildpack.

Avoiding Scope Conflicts​

The BOMs will set the version and the scope of the dependencies the SAP Java Buildpack adds to your application at runtime. The scope of the those dependencies is set to provided.

You can verify the behavior by searching for the scope of, for example, the com.sap.cloud.security.xsuaa:token-client dependency in your application. When you use any of the BOMs provided by the SAP Java Buildpack directly the token-client should have the scope provided. If you are not using the BOMs, it should have the scope compile or test.

tip

Verify your dependency tree via mvn dependency:tree. The above dependencies should only be listed with scope provided.

note

Dependencies with the scope provided are not part of your .war file. This means you need to adapt the scopes if you want to run your applications without the SAP Java Buildpack. One common example for this is running your application locally.

Local deployment of TomEE is possible with a maven profile activated by the parameter -Ddeployment=local:

Maven profile

As a result the SAP Java Buildpack BOM is removed from the dependencyManagement.

<profiles>
    <profile>
        <id>cloud-deployment</id>
        <activation>
            <property>
                <name>deployment</name>
                <!-- Activate this profile when the 'local' is not defined -->
                <value>!local</value>
            </property>
        </activation>
        <dependencyManagement>
            <dependencies>
                <dependency>
                    <groupId>com.sap.cloud.sjb.cf</groupId>
                    <artifactId>cf-tomee7-bom</artifactId>
                    <version>use-latest-version-here</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
                <dependency>
                    <groupId>com.sap.cloud.sdk</groupId>
                    <artifactId>sdk-bom</artifactId>
                    <version>use-latest-version-here</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
            </dependencies>
        </dependencyManagement>
    </profile>
    <!-- Having 2 profiles ensures that the tomee bom will always be in front of the sdk bom-->
    <profile>
        <id>local-deployment</id>
        <activation>
            <property>
                <name>deployment</name>
                <!-- Activate this profile when the 'local' is defined -->
                <value>local</value>
            </property>
        </activation>
        <dependencyManagement>
            <dependencies>
                <dependency>
                    <groupId>com.sap.cloud.sdk</groupId>
                    <artifactId>sdk-bom</artifactId>
                    <version>use-latest-version-here</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
            </dependencies>
        </dependencyManagement>
    </profile>
</profiles>

Background: Dependency Version Conflicts​

The dependency versions from the sdk-bom and the Buildpack may differ.

Consider this example:

  • Buildpack version 1.43 contains java-security:2.10.5
  • SAP Cloud SDK version 3.59 contains java-security:2.11.2

If there are breaking API changes in java-security this can lead to runtime errors.

note

There is no way to solve this versioning problem on SAP Cloud SDK or Buildpack side. Generally, we try to keep the versions as consistent as possible.

However, the exact combination of Buildpack and SAP Cloud SDK depends on the release schedule of the two products. In addition to that, it also depends on the time an application updates the SAP Cloud SDK version & deploys it.

Background: Dependency Scope Conflicts​

In addition to potential version conflicts also scope problems can occur.

Consider this example:

  • Buildpack contains java-security
  • SAP Cloud SDK depends on java-security with scope compile

As a result, the classes from java-security will be on the classpath twice. Once from the Buildpack and once packaged by maven into the deployment artifact.