Custom Functions in OData V4 – SAP Cloud Application Programming Model

Functions are Custom operations exposed by an OData service that must always return data and must never modify data on the backend so that there are no observable side effects.

That is they’re always GET HTTP operations.

In this blog post, we will look into how to implement Custom Functions in the SAP Cloud Application Programming (CAP) model by leveraging CAP Java SDK Maven Plugin.

Create a CAP Java Application using SAP Business Application Studio (BAS)

Step1: Generate a Java project

1. Create a Dev Space in BAS with any name, select “Full Stack Cloud Application”. Start the DevSpace.
2. Open a terminal in the Development space and run the below command in the directory: /home/user/projects to create an initial java project.

mvn -B archetype:generate -DarchetypeArtifactId=cds-services-archetype -DarchetypeGroupId=com.sap.cds \
-DarchetypeVersion=RELEASE \
-DgroupId=com.sap.cap -DartifactId=function-import-service -Dpackage=com.sap.cap.functionimport

From the main menu, choose File > Open Workspace to open the project.

Step2: Create a CDS Service and define your Function

In srv folder, create a file named “customfunctions.cds”.

Add the following service definition to the file –

service CustomFunctionService {
    function getCurrentDateTime() returns Timestamp;
}

This creates an OData Function with the name getCurrentDateTime.

Step3: Compile the Service definition

In the terminal, run the following command to compile the project –

mvn clean install

During compilation, the CAP Java SDK Maven Plugin automatically generates Event Context objects for Functions defined in the CDS model, which provide type-safe access to the function parameters and allow to set the return values.

Check under srv/src/gen/java/cds/gen for the generated Event Context files. We would be utilizing the below-highlighted fields for implementing Event Handler in our next step.

Step4: Implement a Custom Event Handler

In SAP Cloud Application Programming Model, Functions are implemented through Event Handlers. For each function, an On phase is defined, which implements

• Business Logic
• Provides return value

Create a Java file “CustomFunctionsHandler.java” under srv/src/main/java/com/sap/cap/functionimport with the following content –

package com.sap.cap.functionimport;

import java.time.Instant;

import com.sap.cds.services.handler.EventHandler;
import com.sap.cds.services.handler.annotations.On;
import com.sap.cds.services.handler.annotations.ServiceName;

import org.springframework.stereotype.Component;

import cds.gen.customfunctionservice.CustomFunctionService_;
import cds.gen.customfunctionservice.GetCurrentDateTimeContext;

@Component
@ServiceName(CustomFunctionService_.CDS_NAME)
public class CustomFunctionsHandler implements EventHandler {
    @On(event = GetCurrentDateTimeContext.CDS_NAME)
     public void onGetCurrentDateTime(GetCurrentDateTimeContext context) {
         context.setResult(Instant.now());
     }     
}

Step5: Run the Application

Start the application with the below command in terminal –

mvn clean spring-boot:run

A notification saying “A service is listening to port 8080” will appear at the bottom right, choose Expose and Open. The application will be started at default port: 8080

Step6: Check OData metadata and Custom Function Response

Click on $metadata from the welcome page

1. $metadata of the CustomFunctionService returns the Function name getCurrentDateTime we defined in the CDS file

2. Replace the $metadata in the URL with the Function name getCurrentDateTime().

Response of the Custom Function is returned as shown below

Custom Functions with Parameters

Please follow the same steps as mentioned above, just replace the content as follows

1. Define a function with parameters in the CDS service file.

service CustomFunctionService {
    function displayUserName(userName: String) returns String;
}

2. Compile the project which auto-generates the following Event Context files. Notice the auto-generated getter and setter methods for the parameter userName.

 3. Create an Event Handler file with the following content –

package com.sap.cap.functionimport;

import com.sap.cds.services.handler.EventHandler;
import com.sap.cds.services.handler.annotations.On;
import com.sap.cds.services.handler.annotations.ServiceName;

import org.springframework.stereotype.Component;

import cds.gen.customfunctionservice.CustomFunctionService_;
import cds.gen.customfunctionservice.DisplayUserNameContext;

@Component
@ServiceName(CustomFunctionService_.CDS_NAME)
public class CustomFunctionsHandler implements EventHandler {
    @On(event = DisplayUserNameContext.CDS_NAME)
     public void onDisplayName(DisplayUserNameContext context) {
         String name = context.getUserName();
         context.setResult("Hello "+name);
     }     
}

4.  Start the application as done before, and open the $metadata endpoint.

The function displayUserName and the parameter userName is visible as shown below

     5. Replace $metadata in the URL with the Function and parameter name as /displayUserName(userName='Harry%20Potter')

Conclusion

• In this blog post, we’ve talked about how to implement OData (V4) Custom Functions along with parameters in SAP Cloud Application Programming Model.
• If you have any questions please submit them here in the relevant tag Q&A area. I will be happy to answer.
• You’re welcome to provide feedback in the comment section.