Getting started - SDK for Java

To get started with the SAP Cloud SDK for Java you can either create a new project or integrate the SDK into your existing one. You will need an installation of Java and Maven.

Java version compatibility

The SDK itself is compatible with Java 8 and 11. Other Java versions may work as well depending on your setup but are not yet tested by us. Note that SAP Cloud Platform Cloud Foundry environment only supports Java 8 out of the box but can be configured to also run with Java 11. SAP Cloud Plattform Neo only supports Java 8.

To start of with a clean, new project you can select one of our archetypes and build upon it. Alternatively you can follow these instructions to integrate the SDK into your existing setup.

Generating a Project from a Maven Archetype#

Spring
TomEE

mvn archetype:generate "-DarchetypeGroupId=com.sap.cloud.sdk.archetypes" \
    "-DarchetypeArtifactId=scp-cf-spring" \
    "-DarchetypeVersion=RELEASE"

Maven will ask you to provide the following:

groupId - usually serves as your organization identifier, i.e. foo.bar.cloud.app
artifactId - it's your application's name, i.e. mydreamapp
version - we recommend keeping 1.0-SNAPSHOT if you're just starting
package - by default this equals to groupId. Change it only if you know what you're doing

After providing all the interactive values to the CLI it will generate your first Cloud SDK based application:

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Interactive mode
[INFO] ....
[INFO] ....
Define value for property 'groupId': foo.bar.cloud.app
Define value for property 'artifactId' (should match expression '[^_]+'): mydreamapp
[INFO] Using property: artifactId = mydreamapp
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' foo.bar.cloud.app: :
[INFO] Using property: gitignore = .gitignore
[INFO] Using property: skipUsageAnalytics = false
Confirm properties configuration:
groupId: foo.bar.cloud.app
artifactId: mydreamapp
artifactId: mydreamapp
version: 1.0-SNAPSHOT
package: foo.bar.cloud.app
gitignore: .gitignore
skipUsageAnalytics: false
 Y: :
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: scp-cf-tomee:RELEASE
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: foo.bar.cloud.app
[INFO] Parameter: artifactId, Value: mydreamapp
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: foo.bar.cloud.app
[INFO] Parameter: packageInPathFormat, Value: foo/bar/cloud/app
[INFO] Parameter: package, Value: foo.bar.cloud.app
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: groupId, Value: foo.bar.cloud.app
[INFO] Parameter: skipUsageAnalytics, Value: false
[INFO] Parameter: gitignore, Value: .gitignore
[INFO] Parameter: artifactId, Value: mydreamapp
[INFO] Project created from Archetype in dir: /home/i531196/dev/temp/mydreamapp
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  02:28 min
[INFO] Finished at: 2020-04-19T19:25:33+02:00
[INFO] ------------------------------------------------------------------------

Congratulations! You've just setup a brand new application with the SAP Cloud SDK for Java.

tip

To change the Java version modify the <java.version> property in the root pom.xml.

Integrate the Cloud SDK for Java into your Project#

1. Adding Dependencies#

tip

The SAP Cloud SDK integrates with CAP projects! Simply follow the steps below or check out the dedicated tutorial on SAP Developers.

To get started with an existing project include the SDK BOM in the dependency management section of your project:

<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>

If your application is running on SAP Cloud Platform please add the appropriate dependency:

Cloud Foundry
Neo

<dependency>
    <groupId>com.sap.cloud.sdk.cloudplatform</groupId>
    <artifactId>scp-cf</artifactId>
</dependency>

If you want to connect to an S/4HANA system via the OData protocol you should also add a dependency to the client libraries of the SDK:

<dependency>
    <groupId>com.sap.cloud.sdk.s4hana</groupId>
    <artifactId>s4hana-all</artifactId>
</dependency>

In case you have a CAP application which uses multitenancy features and/or a protected backend your service will need the following dependency:

<dependency>
  <groupId>com.sap.cds</groupId>
  <artifactId>cds-integration-cloud-sdk</artifactId>
</dependency> 

Last but not least we recommend that you include the following plugin:

<plugin>
    <groupId>com.sap.cloud.sdk.plugins</groupId>
    <artifactId>usage-analytics-maven-plugin</artifactId>
    <version>use-latest-version-here</version>
    <executions>
        <execution>
            <goals>
                <goal>usage-analytics</goal>
            </goals>
            <configuration>
                <skipUsageAnalytics>false</skipUsageAnalytics>
                <generateSalt>true</generateSalt>
            </configuration>
        </execution>
    </executions>
</plugin>

It sends anonymized usage data such as the SDK version used and helps us with improving the SDK. Furthermore the plugin is capable of generating a report with useful information about the project setup. Invoking diagnosis-report will print out the SDK modules used and their version but also other information like the Java and Maven version. This is helpful when you are facing an issue and are reaching out to us for help.

2. Framework Integration#

In general, the Cloud SDK for Java integrates natively into the Spring Boot and TomEE frameworks.

In particular the SDK provides listeners that can extract tenant and principal information from an incoming request. To ensure these listeners are present please configure your project accordingly.

Spring
TomEE

For a Spring based project please ensure that the application is annotated to scan for components of the SDK:

@ComponentScan({"com.sap.cloud.sdk", "your.own.package"})
@ServletComponentScan({"com.sap.cloud.sdk", "your.own.package"})

Check the logs on application startup to ensure the listeners got registered. Also please check the Spring version declared in the SDK BOM doesn't clash with your version of Spring.

For a TomEE based project the filters should be registered automatically. They are part of the servlet module which comes into the dependency tree through scp-cf or scp-neo automatically. Check the logs on application startup to ensure the listeners are being registered.

Next steps#

Configure you IDE
Get and bind SAP Cloud Foundry CLI
Check tutorials for Cloud SDK for Java
Check out key Features and Guides sections
Check our release notes