Use JBoss Forge to generate Hibersap Classes that call SAP Functions

This blog post describes how to use JBoss Forge to easily generate interface classes for your Java application and use these classes with the Hibersap framework to connect to a SAP system. At the end of the post you will find a screen-cast showing you how easy and straight-forward it is to call SAP functions using the Hibersap-Forge-Plugin.

What is JBoss Forge?

Let’s take the description from the Forge homepage to answer this question:

A core framework and next-generation shell for tooling and automation at a command line level; with APIs for integration in IDEs, extending built in functionality with plugins, and scripting for automating repetitive tasks, Forge is a tool every open-source developer should be looking at.

A core framework for rapid-application development in a standards-based environment. Plugins / incremental project enhancement for Java EE, and more.

What is Hibersap?

is a Java middleware framework, which simplyfies SAP Business Interface usage in your Java application. Under the hood, Hibersap uses the SAP Java Connector version 3 or a JCA compatible resource adapter to connect to SAP. It makes use of Java annotations to map Java classes and fields to remotely callable ABAP function modules and their parameters and offers a Hibernate-like API to execute those function modules.

Thanks to the Hibersap Framework and JBoss Forge Hibersap-Plugin, there’s an easy way to generate annotated Hibersap-POJOs for calling SAP functions.

Prerequisites

To use JBoss Forge with the Hibersap-Plugin you need a Java 6 runtime on your machine, a Maven installation and a suitable SAP Java Connector for your operating system (Version 3.0.7 is needed by the plugin).

You need to install JBoss Forge and the plugin, configure your SAP system properties (like user, password and IP) and a Maven-Java project as a target for the generated classes. That’s it!

Installation

Download and install the latest version of JBoss Forge (1.0.5.Final by now), make sure that you have the SAP Java Connector installed on your machine and that a sapjco3.jar is available in your local Maven repository.

To get a jar file to your local repository, use the mvn install:install command:

mvn install:install -file -DgroupId=com.sap -DartifactId=sap -jco -Dversion=3.0.7 -Dpackaging=jar -Dfile=./sapjco3.jar

To install the Hibersap-Plugin run forge and use the forge git-plugin command:

forge git-plugin git://github.com/forge/plugin-hibersap.git --ref 1.0.0

Configuring the SAP properties

Before configuring the SAP connection properties, have a look at the default property values.

Navigate into an existing Maven project (in the example the project is called wicketsap) and run the generate-sap-entities list-properties command to show the properties on the command-line.

W:\workspaces\workspace_forge >forge
 _____
|  ___| __  _ __ __ _  ___
| | _ / _ \| ‘__/ _‘ |/ _ \ \\ 
|   _| (_) | | | (_| |  __/ // 
|_|   \___/|_| \__,  |\___|
                |___/
Windows? Really? Okay...

[no project] workspace_forge $ cd wicketsap
cd wicketsap
[wicketsap] wicketsap $
[wicketsap] wicketsap $ generate-sap-entities list-properties
jco.destination.pool_capacity=1
jca.connectionspec.factory=org.hibersap.execution.jca.cci.SapBapiJcaAdapterConnectionSpecFactory
session-manager.name=SM001
jco.client.lang=en
jco.client.ashost=some.sap-system.com
jco.client.user=sapuser
jco.client.sysnr=00
jco.client.passwd=password
jco.context=org.hibersap.execution.jco.JCoContext
jca.context=org.hibersap.execution.jco.JCAContext
jco.client.client=001
jca.connection.factory=java:/eis/sap/A12
[wicketsap] wicketsap $

You may choose a different session manager name according to your SAP system, but for the first run SM001 will do the job. Configure the connection properties depending on your SAP system. For a first try username, password and hostadress might be sufficient due to the default values, if necessary change language, system number and client number as well.

[wicketsap] wicketsap $
[wicketsap] wicketsap $ generate-sap-entities set-property --key jco.client.ashost --value my.sap.system
[wicketsap] wicketsap $
[wicketsap] wicketsap $ generate-sap-entities set-property --key jco.client.user --value myUserName 
[wicketsap] wicketsap $
[wicketsap] wicketsap $ generate-sap-entities set-property --key jco.client.passwd --value myPassword 
[wicketsap] wicketsap $
[wicketsap] wicketsap $ generate-sap-entities list-properties
jco.destination.pool_capacity=1 
jca.connectionspec.factory=org.hibersap.execution.jca.cci.SapBapiJcaAdapterConnectionSpecFactory 
session-manager.name=SM001
jco.client.lang=en
jco.client.ashost=some.sap.system
jco.client.user=myUserName
jco.client.sysnr=00
jca.context=org.hibersap.execution.jco.JCAContext
jco.context=org.hibersap.execution.jco.JCoContext
jco.client.passwd=myPassword
jco.client.client=001
jca.connection.factory=java:/eis/sap/A12 
[wicketsap] wicketsap $

Usage Example

Start JBoss Forge, navigate into your project or create a new project via Forge.
Use the generate-sap-entities command to search for SAP interfaces matching the given name pattern, e.g. BAPI?FLC*. (Use ? and * as wildcards.)

[wicketsap] wicketsap $
[wicketsap] wicketsap $ generate-sap-entities --name-pattern BAPI?FLC*
Select a function to generate the necessary Java classes:
 1 - [BAPI_FLCONN_GETDETAIL]
 2 - [BAPI_FLCONN_GETLIST]
 3 - [BAPI_FLCUST_CHANGE]
 4 - [BAPI_FLCUST_CHANGEPASSWORD]
 5 - [BAPI_FLCUST_CHECKPASSWORD]
 6 - [BAPI_FLCUST_CREATEFROMDATA]
 7 - [BAPI_FLCUST_ENABLEWEBUSE]
 8 - [BAPI_FLCUST_GETLIST] 
 9 - [Cancel]
? Choose an option by typing the number of the selection:

The list shows all the remote function modules in your SAP system whose names match your name pattern. Choose the function you want to use in your Java application. In the next steps, enter a class name and a package name for the interface class or use the plugins suggestions.

? Choose an option by typing the number of the selection: 8
? Please enter a class name. Leave empty for default
 [BapiFlcustGetlist]
? Please enter a Java package. Leave empty for default [org.hibersap.example.hibersap] org.hibersap.example.wicketsap.sap

The classes needed by the Hibersap framework to call the SAP function will be generated. In the next step, Forge asks you to choose the versions of the dependencies needed for your project. After the dependency configuration the Hibersap XML configuration file will be added to your project.

Created SAP entity [org.hibersap.example.wicketsap.sap.CustomerList]
Created SAP entity [org.hibersap.example.wicketsap.sap.ExtensionOut]
Created SAP entity [org.hibersap.example.wicketsap.sap.Return]
Created SAP entity [org.hibersap.example.wicketsap.sap.CustomerRange]
Created SAP entity [org.hibersap.example.wicketsap.sap.ExtensionIn]
Created SAP entity [org.hibersap.example.wicketsap.sap.BapiFlcustGetlist]
? Would you like to use JCo or JCA adapter for the current session manager?
Leave empty for default [JCo]
Checking and updating dependencies...
Which version do you want to install?
1 - [org.hibersap:hibersap-core:::1.0]
2 - [org.hibersap:hibersap-core:::1.1.0Beta01]
3 - [org.hibersap:hibersap-core:::1.1.0Beta02]
? Choose an option by typing the number of the selection: 3
Dependency added [hibersap-core]
Which version do you want to install?
1 - [org.hibersap:hibersap-jco:::1.0]
2 - [org.hibersap:hibersap-jco:::1.1.0Beta01]
3 - [org.hibersap:hibersap-jco:::1.1.0Beta02]
? Choose an option by typing the number of the selection: 3
Dependency added [hibersap-jco]
Which version do you want to install?
1 - [com.sap:sap-jco:::3.0.0]
2 - [com.sap:sap-jco:::3.0.7]
3 - [com.sap:sap-jco:::3.0.8]
? Choose an option by typing the number of the selection: 3
Dependency added [sap-jco]
? Do you want to use bean validation in your project? [y/N]
Session manager [SM001] added...
Wrote configuration file [hibersap.xml]
Wrote W:\/workspaces/workspace_forge/wicketsap/src/main/java/org/hibersap/example/wicketsap/sap/CustomerList.java
Wrote W:\/workspaces/workspace_forge/wicketsap/src/main/java/org/hibersap/example/wicketsap/sap/ExtensionOut.java
Wrote W:\/workspaces/workspace_forge/wicketsap/src/main/java/org/hibersap/example/wicketsap/sap/Return.java
Wrote W:\/workspaces/workspace_forge/wicketsap/src/main/java/org/hibersap/example/wicketsap/sap/CustomerRange.java
Wrote W:\/workspaces/workspace_forge/wicketsap/src/main/java/org/hibersap/example/wicketsap/sap/ExtensionIn.java
Wrote W:\/workspaces/workspace_forge/wicketsap/src/main/java/org/hibersap/example/wicketsap
/sap/BapiFlcustGetlist.java
Wrote W:\/workspaces/workspace_forge/wicketsap/pom.xml
[wicketsap] wicketsap $

The class representing the SAP function (BapiFlcustGetlist) and the classes representing the complex data types are now in your project:

You can use Hibersap to access data from your SAP system, e.g. using a Data Access Object.

Just a few lines of code are necessary to access the SAP interface.

Create a new session manager from your preconfigured Hibersap XML:

final AnnotationConfiguration config = 
      new AnnotationConfiguration(&quot;SM001&quot;);
final SessionManager sessionManager =       
      config.buildSessionManager();

Create a new SAP interface object, e.g. BapiFlcustGetlist:

final BapiFlcustGetlist bapi = 
      new BapiFlcustGetlist(&quot;John Doe&quot;, null, 10);

Open a new session and execute the interface request:

final Session session = sessionManager.openSession();
session.execute(bapi);
session.close();

Use the getter methods of the BapiFlcustGetlist to access the results of your request.

Further Information

Also watch the screen-cast that shows the usage of the Hibersap-Forge-Plugin:

JBoss Forge Hibersap Plugin Screencast on Vimeo.

Summary

In this post we showed how to generate easily SAP interfaces with Hibersap and the JBoss Forge Hibersap Plugin. Making use of Java Annotations and a Hibernate-/JPA-like API, Hibersap fits well into the range of state-of-the-art Java EE technologies that make writing enterprise applications much more fun, compared to the rather verbose and technical API of the SAP Java Connector.

For more information about Hibersap read also the Introducing Hibersap post and see the Hibersap web site.

If you have any problems, questions or remarks, feel free to contact us via email:

maxxschwaab [at] arcor.de
carsten.erker [at] akquinet.de