First, we will take a look at the SAP function module we will call. The following is the function module’s interface. The function is written in SAP’s programming language ABAP.

The function’s interface defines some parameters that represent search criteria to look up flights in SAP’s database. The matching flights are returned in the FLIGHTLIST table, which contains information such as the airline carrier id, a flight connection code and departure / destination data. In the RETURN structure the function may return extra messages like errors, warnings, etc.

In this function, the import parameters are simple types, whereas the export and table parameter are complex data types (ABAP structures). The RETURN parameter is of type BAPIRET2, which is a standard structure that can be found in many function modules' interfaces and is not specific to this BAPI. This are the individual elements:

The FLIGHTLIST table’s lines are of type BAPISFLIST which contains the following elements:

Our goal is to map all those parameters to Java classes and their fields which we will achieve using Java annotations defined by Hibersap.

Next, we will write a BAPI class that acts as an adapter to the JCo function. The BAPI class is a simple Java class with a number of fields representing the BAPI’s import, export and table parameters. In case the BAPI parameter being a scalar parameter, the Java field itself is of a simple Java type. In the case of a structure parameter, the Java field’s type is of a complex type. A table parameter maps to an Array or a Collection of a complex type.

All setup related to the function module’s interface is done via Java annotations. A BAPI class is defined using the Hibersap class annotation @Bapi, which has an argument specifying the name of the SAP function module we want to call. (All Hibersap annotations can be found in the package org.hibersap.annotations.)

The Java fields that will be mapped to the function module’s parameters are annotated with the @Import, @Export or @Table annotations to tell Hibersap which kind of parameter it shall handle. Additionally, we have to specify the function module’s field name to which it relates, using the @Parameter annotation. The @Parameter 's second argument, type, tells Hibersap if the parameter is mapped to a simple or complex type. The enumeration ParameterType defines possible values, the default type for element type being SIMPLE. In most cases we have to specify a parameter’s name only. In case of table parameters the type argument will be ignored by Hibersap since tables always have a complex type for each table line.

The Java type of each simple field is related to the SAP field’s data type. Hibersap relies on the Java Connector’s conversion scheme.

The @Convert annotation on the field afternoon in the listing above tells Hibersap to use a Converter of type BooleanConverter to convert the parameter AFTERNOON (which is a character field of length 1 in SAP) to a Java boolean value. See section Type Conversion in the Hibersap Reference Manual for a deeper discussion of custom converters.

To conclude the example, we write a constructor which has all the import parameters as arguments, initializing the corresponding fields:

Finally, we add a getter method for each field. Hibersap itself does not need setter methods, because all fields are set using reflection. Additional fields and methods may of course be added.

There are two more classes we need to write: One for the complex export parameter RETURN, which is named BapiRet2, after the SAP data type. It is another annotated simple Java class with fields related to some of the function module’s parameter. To keep the example simple, we do not map all the fields of the RETURN parameter.

The class is annotated with @BapiStructure to tell Hibersap that it maps to a complex parameter on the SAP side. Each particular field is annotated with the already known @Parameter annotation that defines the name of the corresponding structure field. The BapiRet2 class is already part of Hibersap, since this structure is used by a lot of SAP function modules. This means, you don’t have to implement it yourself.

The second class we need to implement is a Java class that Hibersap will map to each row in the table parameter FLIGHTLIST, which in our example is simply called Flight. The table FLIGHTLIST will be filled by SAP with the flight information matching our request.

Please note that the method getDepartureTime() does not simply return the field departureTime but calls a utility method DateUtil.joinDateAndTime(). This is done here because ABAP — unlike Java — does not have a data type that contains date and time. In ABAP such a timestamp is separated into two fields, one of type Date, the other of type Time. Therefore the Java Connector returns a java.util.Date for the SAP date field containing the date fraction (date at 00:00:00,000) and another java.util.Date for the time field containing the time fraction (i.e. Jan. 1st, 1970 plus time). The utility method joins those two dates into one.

To configure Hibersap, we create an XML file named hibersap.xml in the project’s src/main/resources/META-INF folder. The configuration file contains information for Hibersap itself, plus properties for the SAP Java Connector.

In the example we use a minimal set of JCo properties to be able to connect to the SAP system. All valid JCo properties are specified in the interface com.sap.conn.jco.ext.DestinationDataProvider of th JCo library (for details see javadoc provided with JCo).

The values of the JCo client, user, passwd, ashost and sysnr properties must match the SAP system we are connecting to. This means, you need to adopt the values to your specific SAP system and user account.

To interact with Hibersap, an instance of type SessionManager must be aquired. For each SAP system which the application interacts with a SessionManager is needed. The SessionManager should only be created once in an application because it is rather expensive to create.

The SessionManager is responsible for creating Sessions. A Session represents a connection to the SAP system. The first time we call a function module on a Session, Hibersap aquires a connection from the underlying connection pool. When closing a session, the connection is returned to the pool. The application has to take care of closing the session whenever it is not needed anymore, preferably in a finally block. If the application keeps open too many sessions, the connection pool may get exhausted sooner or later. Any further attempt of opening another session would thus fail.

The following function configures a Hibersap SessionManager. First, an instance of type AnnotationConfiguration is created for the named SessionManager, as specified in hibersap.xml. Finally, the SessionManager is built. In a real application this should be done once, reusing the SessionManager throughout the application’s lifetime.

Now it is time to call the function module in SAP. After creating the SessionManager and opening a new Session, we create an instance of our BAPI Class, passing all parameters needed to execute the function. Then we simply call the Session.execute() method, passing the BAPI class which actually performs the call to SAP. Now the flightListBapi object is enriched with all the values returned by the function module which we have mapped to Java fields in our BAPI Class.

To see the result of the function call, we simply print the BAPI class' fields to the console in the showResult() method. Finally, we create a main method that calls the showFlightList() method.