JAVA Hibersap 框架调用 SAP

In this example we will create a simple Maven project which uses Hibersap to call a function in SAP and print the result to the command line.

Download and install the SAP Java Connector

Download SAP Java Connector 3 from http://service.sap.com/connectors and extract the sapjco3.jar and the sapjco3 native library.

The native library implements the underlying communication protocol (SAP RFC, Remote Function Call) and is needed by the sapjco3.jar at runtime. Since native libraries are different for each operating system and processor architecture, there are different distributions for the JCo, e.g. Windows on Intel x86, 64 bit JVM or Mac, 32 bit JVM. Make sure to download the correct distribution for the OS/architecture combination on which your application will be running.

Install the sapjco3 jar to your local Maven repository from the command line. In the example we assume you use version 3.0.12, if not so, replace to version number with the correct value:

mvn install:install-file -DgroupId=org.hibersap -DartifactId=sapjco3 -Dversion=3.0.12 \\
                         -Dpackaging=jar -Dfile=/path/to/sapjco3.jar

Create a Maven project with the required dependencies

Create a Maven project with the following dependencies:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.mycompany</groupId>
    <artifactId>hibersap-example</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <dependencies>
        <dependency>
            <groupId>org.hibersap</groupId>
            <artifactId>hibersap-core</artifactId>
            <version>1.2.0</version>
        </dependency>
        <dependency>
            <groupId>org.hibersap</groupId>
            <artifactId>hibersap-jco</artifactId>
            <version>1.2.0</version>
        </dependency>
        <dependency>
            <groupId>org.hibersap</groupId>
            <artifactId>sapjco3</artifactId>
            <version>3.0.12</version>
        </dependency>
    </dependencies>
</project>

Implement the application

Our little application will call the SAP function BAPI_SFLIGHT_GETLIST. This function is part of a demo application in SAP that implements a simplified flight-booking system.

Examine the function module

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.

FUNCTION BAPI_SFLIGHT_GETLIST.
  IMPORTING
     VALUE(FROMCOUNTRYKEY) LIKE  BAPISFDETA-COUNTRYFR
     VALUE(FROMCITY)       LIKE  BAPISFDETA-CITYFROM
     VALUE(TOCOUNTRYKEY)   LIKE  BAPISFDETA-COUNTRYTO
     VALUE(TOCITY)         LIKE  BAPISFDETA-CITYTO
     VALUE(AIRLINECARRIER) LIKE  BAPISFDETA-CARRID DEFAULT SPACE
     VALUE(AFTERNOON)      LIKE  BAPI_AUX-AFTERNOON DEFAULT SPACE
     VALUE(MAXREAD)        LIKE  BAPI_AUX-MAXREAD DEFAULT 0
  EXPORTING
     VALUE(RETURN)         LIKE  BAPIRET2 STRUCTURE  BAPIRET2
  TABLES
     FLIGHTLIST            STRUCTURE  BAPISFLIST

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:

Component name	Type	Description
TYPE	Character	Message type: S Success, E Error, W Warning, I Info, A Abort
ID	Character	Messages, message class
NUMBER	Numeric character	Messages, message number
MESSAGE	Character	Message text
LOG_NO	Character	Application log: log number
LOG_MSG_NO	Numeric character	Application log: Internal message serial number
MESSAGE_V1	Character	Messages, message variables
MESSAGE_V2	Character	Messages, message variables
MESSAGE_V3	Character	Messages, message variables
MESSAGE_V4	Character	Messages, message variables
PARAMETER	Character	Parameter name
ROW	4-byte integer	Lines in parameter
FIELD	Character	Field in parameter
SYSTEM	Character	Logical system from which message originates

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

Component name	Type	Description
CARRID	Character	Airline carrier ID
CONNID	Numerical character	Flight connection code
FLDATE	Date	Flight date
AIRPFROM	Character	Airport of departure
AIRPTO	Character	Destination airport
DEPTIME	Time	Departure time
SEATSMAX	4-byte integer	Maximum capacity
SEATSOCC	4-byte integer	Occupied seats

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

Implement the BAPI class

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

package org.hibersap.examples.flightlist;

import java.util.List;
import org.hibersap.*;

@Bapi("BAPI_SFLIGHT_GETLIST")
public class FlightListBapi {
  // ...
}

The Java fields that will be mapped to the function module’s parameters are annotated with the @Import, @Export or @Tableannotations 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 typeargument will be ignored by Hibersap since tables always have a complex type for each table line.

@Import
@Parameter("FROMCOUNTRYKEY")
private final String fromCountryKey;

@Import
@Parameter("FROMCITY")
private final String fromCity;

@Import
@Parameter("TOCOUNTRYKEY")
private final String toCountryKey;

@Import
@Parameter("TOCITY")
private final String toCity;

@Import
@Parameter("AIRLINECARRIER")
private final String airlineCarrier;

@Import
@Parameter("AFTERNOON")
@Convert(converter = BooleanConverter.class)
private final boolean afternoon;

@Import
@Parameter("MAXREAD")
private final int maxRead;

@Export
@Parameter(value="RETURN", type = ParameterType.STRUCTURE)
private BapiRet2 returnData;

@Table
@Parameter("FLIGHTLIST")
private List<Flight> flightList;

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:

public FlightListBapi(String fromCountryKey,
                        String fromCity,
                        String toCountryKey,
                        String airlineCarrier,
                        String toCity,
                        boolean afternoon,
                        int maxRead) {

    this.fromCountryKey = fromCountryKey;
    this.fromCity = fromCity;
    this.toCountryKey = toCountryKey;
    this.toCity = toCity;
    this.airlineCarrier = airlineCarrier;
    this.afternoon = afternoon;
    this.maxRead = maxRead;
}

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.

public boolean getAfternoon() {
    return this.afternoon;
}

// ...

There is one constraint in the current version of Hibersap you should take into account: The mapping between SAP parameters and Java classes works as expected only if the SAP function module complies to the BAPI standard. As of now, this means: Deep tables (i. e. tables in tables or tables in structures) are not supported. Changing parameters can not be mapped.

Implement structure classes for complex parameters

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.

package org.hibersap.bapi;

import org.hibersap.annotations.*;

@BapiStructure
public class BapiRet2 {

    @Parameter("TYPE")
    @Convert(converter = CharConverter.class)
    private char type;

    @Parameter("ID")
    private String id;

    @Parameter("NUMBER")
    private String number;

    @Parameter("MESSAGE")
    private String message;

    public char getType() { return this.type; }

    public String getId() { return this.id; }

    public String getNumber() { return this.number; }

    public String getMessage() { return this.message; }
}

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.

package org.hibersap.examples.flightlist;

import java.util.Date;
import org.hibersap.*;

@BapiStructure
public class Flight {

    @Parameter("CARRID")
    private String carrierId;

    @Parameter("CONNID")
    private String connectionId;

    @Parameter("AIRPFROM")
    private String airportFrom;

    @Parameter("AIRPTO")
    private String airportTo;

    @Parameter("FLDATE")
    private Date flightDate;

    @Parameter("DEPTIME")
    private Date departureTime;

    @Parameter("SEATSMAX")
    private int seatsMax;

    @Parameter("SEATSOCC")
    private int seatsOccupied;

    public String getAirportFrom() { return this.airportFrom; }

    public String getAirportTo() { return this.airportTo; }

    public String getCarrierId() { return this.carrierId; }

    public String getConnectionId() { return this.connectionId; }

    public Date getDepartureTime() {
      return DateUtil.joinDateAndTime( flightDate, departureTime );
    }

    public Date getFlightDate() { return flightDate; }

    public int getSeatsMax() { return this.seatsMax; }

    public int getSeatsOccupied() { return this.seatsOccupied; }
}

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.

Configure Hibersap

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.

<?xml version="1.0" encoding="UTF-8"?>
<hibersap xmlns="urn:hibersap:hibersap-configuration:1.0">
  <session-manager name="A12">
    <properties>
      <property name="jco.client.client" value="800" />
      <property name="jco.client.user" value="sapuser" />
      <property name="jco.client.passwd" value="password" />
      <property name="jco.client.lang" value="en" />
      <property name="jco.client.ashost" value="10.20.30.40" />
      <property name="jco.client.sysnr" value="00" />
      <property name="jco.destination.pool_capacity" value="5" />
    </properties>
    <annotatedClasses>
      <class>org.hibersap.examples.flightlist.FlightListBapi</class>
    </annotatedClasses>
  </session-manager>
</hibersap>

Call the function module and show the results

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.

public class HibersapTest {

    public SessionManager createSessionManager() {
        AnnotationConfiguration configuration = new AnnotationConfiguration("A12");
        return configuration.buildSessionManager();
    }
}

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.

public void showFlightList() {

    SessionManager sessionManager = createSessionManager();

    Session session = sessionManager.openSession();
    try {
        FlightListBapi flightList = new FlightListBapi( "DE", "Frankfurt",
                                                        "DE", "Berlin",
                                                        null, false, 10 );
        session.execute( flightList );
        showResult( flightList );
    }
    finally {
        session.close();
    }
}

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.

private void showResult( FlightListBapi flightList ) {

    System.out.println( "AirlineId: " + flightList.getFromCountryKey() );
    System.out.println( "FromCity: " + flightList.getFromCity() );
    System.out.println( "ToCountryKey: " + flightList.getToCountryKey() );
    System.out.println( "ToCity: " + flightList.getToCity() );
    System.out.println( "AirlineCarrier: " + flightList
                                             .getAirlineCarrier() );
    System.out.println( "Afternoon: " + flightList.getAfternoon() );
    System.out.println( "MaxRead: " + flightList.getMaxRead() );

    System.out.println( "\nFlightData" );
    List<Flight> flights = flightList.getFlightList();
    for ( Flight flight : flights ) {
        System.out.print( "\t" + flight.getAirportFrom() );
        System.out.print( "\t" + flight.getAirportTo() );
        System.out.print( "\t" + flight.getCarrierId() );
        System.out.print( "\t" + flight.getConnectionId() );
        System.out.print( "\t" + flight.getSeatsMax() );
        System.out.print( "\t" + flight.getSeatsOccupied() );
        System.out.println( "\t" + flight.getDepartureTime() );
    }

    System.out.println( "\nReturn" );
    BapiRet2 returnStruct = flightList.getReturnData();
    System.out.println( "\tMessage: " + returnStruct.getMessage() );
    System.out.println( "\tNumber: " + returnStruct.getNumber() );
    System.out.println( "\tType: " + returnStruct.getType() );
    System.out.println( "\tId: " + returnStruct.getId() );
}

public static void main( String[] args ) {
    new HibersapTest().showFlightList();
}

Run the application

Build the project with maven on the command-line using mvn compile and run the main class, or run it directly from your IDE.

Make sure the application can access the JCo native library. The folder in which the native lib file is located must be on the application’s library path. The library path is defined by the Java system property java.library.path which can be passed as a JVM option with the -D command line switch.

-Djava.library.path=/path/to/sapjco-native-lib/

When running from an IDE like IntelliJ or Eclipse, you can add the JVM option by editing the run configuration. When running from the command line you can directly add it to the java command.

In the example, we are looking for all flights from Frankfurt to Berlin. The result should look like follows, in this example, there were two flights found.

AirlineId: DE
FromCity: Frankfurt
ToCountryKey: DE
ToCity: Berlin
AirlineCarrier:
Afternoon: false
MaxRead: 10

FlightData
	FRA  SXF  LH  2402  220  191  Thu Dec 30 10:30:00 CET 2010
	FRA  SXF  LH  2402  220  207  Fri Dec 31 10:30:00 CET 2010

Return
	Message:
	Number: 000
	Type: S
	Id:

If there were no flights found which is usually the case when you didn’t create test data in SAP yet, SAP will return something like the following:

Return
	Message: No corresponding flights found
	Number: 150
	Type: E
	Id: BC_BOR

Further examples can be found in the Hibersap Github repository, including a Java EE application using Hibersap with the Cuckoo Resource Adapter for SAP.

hibersap-example-simple-master