The following steps will explain how to include the SAP S/4HANA Cloud SDK in existing Java web application projects.
Note: This post is part of a series. For a complete overview visit the SAP S/4HANA Cloud SDK Overview.
Goal of this blog post
The goal of this post is to show the various options for a developer to include the public libraries to his newly created or already existing project.
* Software requirements and recommendations.
* Best practice for enabling SAP S/4HANA Cloud SDK
* Head start with Maven archetypes
* Library functionalities and software artifacts
* Example: Spring Boot
This blog post exists as part of general help articles outside of the continuous course starting from Step 1 (Setup). We highly recommend following this series in order to understand feature scope and expected usability of the SAP S/4HANA Cloud SDK.
Software requirements and recommendations
The compiled libraries of SAP S/4HANA Cloud SDK are publicly available and can be used in any Java web application which uses the Java Servlet API. The following properties may be applicable to your software project.
Required:
* Java Runtime version 1.7+
* Maven, Java dependency management tool to easily include SAP S/4Hana Cloud SDK artifacts. It dynamically downloads any required Java libraries to realize the build process.
Recommended:
* Multi module project setup for your software, to ensure a consistent application development structure.
* Supported Servlet 3.0 API to have all features activated automatically during application startup. It allows the web application to be configured by Java annotations.
Best practice
The SAP S/4HANA Cloud SDK provides an extensive set of tools to enable, organize and secure the communication between your web application and your ERP system. These tools are publicly provided as Maven artifacts.
How to start
* Add an entry to your dependencyManagement of your application POM. In case you have a multi-module Maven setup in place, please consider adding this to the parent module. This way inconsistencies and redundancies in your software can be avoided. … com.sap.cloud.s4hana sdk-bom LATEST pom import …
Now you can easily include any dependency of the SAP S/4HANA Cloud SDK to your respective Maven module. Specifying a dependency version is highly recommended, because LATEST could bring incompatibilities sometime in the future.
* Depending on your target deployment platform, you can choose between CloudFoundry (scp-cf) and Neo (scp-neo). Since you added the dependency import previously, you can omit any further version declaration of the SAP S/4HANA Cloud SDK. Notice the different artifact identifier on the first dependency each:
* CloudFoundry (scp-cf) … com.sap.cloud.s4hana.cloudplatform scp-cf com.sap.cloud.s4hana s4hana-all … …
* Neo (scp-neo) … com.sap.cloud.s4hana.cloudplatform scp-neo com.sap.cloud.s4hana s4hana-all … …
Unit tests and integration tests
For testing an application, the SAP S/4HANA Cloud SDK provides a test utility, which enables you to access real and mocked ERP systems. The recommended way is to have one or more dedicated modules for unit tests and integration tests.
* Each can have the following dependencies attached: … com.sap.cloud.s4hana testutil test com.sap.cloud.s4hana.quality listeners-all test … …
Head start with Maven archetypes
Boost your project building process with Maven archetypes!
When you consider starting a new project or migrating an already existing one, please find the SAP S/4HANA Cloud SDK archetypes. With these you can easily create a new Maven project and migrate your existing files to a clean environment. Currently there are four supported archetypes for different runtimes; three of them with a well-established CloudFoundry support.
Spring Boot
In case your application is or will be based on Spring Boot, we highly recommend using the dedicated Spring archetype which has already been prepared for SAP S/4HANA Cloud SDK. In an empty location run the following command: mvn archetype:generate -DarchetypeGroupId=com.sap.cloud.s4hana.archetypes -DarchetypeArtifactId=scp-cf-spring -DarchetypeVersion=LATEST
You will be asked for groupId, artifactId, package and uniqueHostname. The last one represents a unique identifier to determine your initial project URL on CloudFoundry. It can be easily changed later. The project stub which is generated from the archetype contains the best effort project architecture with most of Cloud SDK features already in place. It is a quick start to a deployable web application.
* Easy debugging, e.g. with executing main()
* Run application locally with mvn spring-boot:run
* Run packaged application anywhere with java -jar
Apache Tomee
If your application requires a Java Enterprise Edition of Apache Tomcat, you can use the following archetype: mvn archetype:generate -DarchetypeGroupId=com.sap.cloud.s4hana.archetypes -DarchetypeArtifactId=scp-cf-tomee -DarchetypeVersion=LATEST
* Run application locally with mvn package tomee:run
* Debug with remote debugging to localhost
Apache Tomcat
Probably the most popular application, to run Servlet based application, is Tomcat. You can create a new project stub with Tomcat support by running the following command: mvn archetype:generate -DarchetypeGroupId=com.sap.cloud.s4hana.archetypes -DarchetypeArtifactId=scp-cf-tomcat -DarchetypeVersion=LATEST
* Run application locally with mvn jetty:run
* Debug with remote debugging to localhost
Java EE6
If your target application platform is Neo, then you would need to create the software stub with the following archetype: mvn archetype:generate -DarchetypeGroupId=com.sap.cloud.s4hana.archetypes -DarchetypeArtifactId=scp-neo-javaee6 -DarchetypeVersion=LATEST
* Deploy and run application locally with mvn package scp:push
* Stop local application with mvn clean scp:clean
* Debug with remote debugging to localhost
Functionalities and library artifacts
The functionality of SAP S/4HANA Cloud SDK is provided by Maven artifacts. By specifying dependencies in your application, you can take advantage of most of its features. When including “s4hana-all” like shown before, you already have them attached. Most of the feature bearing artifacts are distributed by the following Maven artifacts:
Feature
Description
Maven Group ID
Maven Artifact ID
S/4HANA
Bundle of all S/4HANA modules, including OData V2 connectivity, can be used on both Neo and Cloud Foundry
com.sap.cloud.s4hana
s4hana-all
S/4HANA – Core
Basic functionality for S/4HANA such as data types and serialization
com.sap.cloud.s4hana
core
S/4HANA – Connectivity
Establish and manage connection to S/4HANA using customer-supplied information via Cloud Platform abstractions. Includes security, caching, resilience.
com.sap.cloud.s4hana
connectivity
S/4HANA – Data Model
Typed data model of OData and BAPI services (as exposed by S/4HANA Cloud), allows easy access via a fluent business object-oriented API.
com.sap.cloud.s4hana
datamodel
S/4HANA – Fluent Result API
Fluent interface for handling various types of query results, including type conversion components.
com.sap.cloud.s4hana
fluent-result
S/4HANA – RFC Queries
Call BAPIs / RFMs in S/4HANA easily with a high level of abstraction.
com.sap.cloud.s4hana
rfc
S/4HANA – Test Utilities
Utility classes for testing ERP-related functionality, also for easy mocking of Cloud Platform entities in general.
com.sap.cloud.s4hana
testutil
Please notice, that s4hana-all includes all the other artifacts from the table, except for testutil. The test utility should only be added to testing modules and environments. To enable the S/4HANA communication, please remember to also include either “scp-cf” or “scp-neo” from group “com.sap.cloud.s4hana.cloudplatform”.
Project examples
Good to know: If your software already relies on a set of dependency imports, it becomes important to structure the import order accordingly. The entries are enumerated with decreasing priority. Please find the example for a parent POM below: … com.sap.cloud.s4hana sdk-bom LATEST pom import …
As you can see, the original dependency versions given by your application will be in favor of the ones given by SAP S/4HANA Cloud SDK. To solve a potential Maven dependency conflict, you can also specify a preferred version above. This will enforce specific version numbers, if none is provided.
Spring Boot
If your software is built with the Spring Boot framework, make sure to also have the dependency spring-boot-starter-web from group “org.springframework.boot” included. Otherwise the required ServletContext will not be accessible internally. You can find a sophisticated Spring Boot example in our public repository: The Costcenter Controller for CloudFoundry. It follows our best effort principles.
The first thing to do, is to include the dependencyManagement entry to your Maven root POM just like it was showed above. Now it could look like this: … org.json json 20170516 org.mockito mockito-core 2.10.0 org.springframework.boot spring-boot-dependencies 1.5.7.RELEASE pom import com.sap.cloud.s4hana sdk-bom LATEST pom import …
A dependency version will be determined by the priority, the order in which dependency imports are enumerated. Here the dependency versions of Spring Boot will be preferred to the ones of the SAP S/4HANA Cloud SDK. The only exceptions are two dependencies listed above, they fix version conflicts. Also, remember to replace any LATEST version.
Spring Initializr
In case you are using the Spring Initializr, do not forget adding “Web” as dependency. This ensures having the required dependency in your web application:
If you have used the Spring initializr, you were given a very basic project stub. It is a single Maven module with a “starter-parent” definition in the top. Although this is not the recommended software architecture, it is an easy and straight forward starting point. Now with the additions discussed above, the single POM file could look like this: 4.0.0 com.example demo 0.0.1-SNAPSHOT jar demo Demo project for Spring Boot org.springframework.boot spring-boot-starter-parent 1.5.7.RELEASE UTF-8 UTF-8 1.7 com.sap.cloud.s4hana sdk-bom LATEST pom import org.json json 20170516 org.springframework.boot spring-boot-starter org.springframework.boot spring-boot-starter-web com.sap.cloud.s4hana.cloudplatform scp-cf com.sap.cloud.s4hana s4hana-all com.sap.cloud.s4hana datamodel org.springframework.boot spring-boot-starter-test test com.sap.cloud.s4hana testutil test com.sap.cloud.s4hana.quality listeners-all test org.springframework.boot spring-boot-maven-plugin
Stay tuned for further updates and integration examples. http://bit.ly/2hZ59Iy #SAP #SAPCloud #AI
