Hibersap Reference Documentation

The Hibersap framework is divided into the following libraries:

When using Hibersap in conjunction with a JCA compatible resource adapter, both the hibersap-core and the hibersap-jca jars must be on the application’s classpath. When using Hibersap with the SAP Java Connector (JCo), the hibersap-core and the hibersap-jco libraries are needed.

When using Hibersap with EJBs, you may consider using the EJB tools provided by the hibersap-ejb library. The EJB tools provide an EJB3 interceptor which takes care of opening and closing sessions as well as injecting them into your EJBs at a special injection point denoted by a @HibersapSession annotation. See section Hibersap EJB Tools for more information.

Hibersap has a few dependencies on third-party libraries, which you need to add to your application’s classpath. The easiest way to achieve this is to build your projects with Maven. See section Building Hibersap Applications with Maven.

Depending on which interfacing technology is actually used, you also need the SAP Java Connector (JCo) or a JCA compatible resource adapter.

If you are using Hibersap with a resource adapter in a managed environment, the preferred choice is the Cuckoo Resource Adapter for SAP. The project’s web site can be found under https://sourceforge.net/p/cuckoo-ra/home.

You need to deploy the resource adapter to your application server. Since it uses the SAP Java Connector internally, the previous section also applies to this scenario, i.e. the SAP JCo has to be installed for use within the application server.

Being the only open source resource adapters for SAP, Hibersap was tested with Cuckoo as well as the SAP BAPI JCA Adapter (see https://sourceforge.net/projects/sapbapijcaadapt). Nevertheless, commercial alternatives do exist. We would be glad to get your feedback when using one of these. Note that a resource adapter must implement the JCA Common Client Interface (CCI) to be supported by Hibersap.

Integrating another Resource Adapter in combination with application-managed authentication includes writing a Resource Adapter specific implementation of the interface org.hibersap.execution.jca.cci.ConnectionSpecFactory. This is due to a limitation in the JCA specification which specifies the javax.resource.cci.ConnectionSpec as an empty interface, letting it up to the vendor-specific implementation to define which properties it contains. Hibersap’s aim to support different resource adapters means that there must be a layer on top of the ConnectionSpec interface which makes it possible to adapt to different JCA implementations without having explicit dependencies to each of them. Hibersap implements ConnectionSpecFactories for Cuckoo as well as the SAP BAPI JCA Adapter that use reflection for setting and getting the ConnectionSpec’s parameters in order to reduce (compile-time) dependencies to the individual resource adapters.

However, an implementation of the ConnectionSpecFactory is not needed if the application uses only container-managed authentication, because in this case Hibersap does not need to use a ConnectionSpec.

The Hibersap libraries are deployed to the Maven Central repository, so the dependencies are downloaded by Maven when you specify them in your project.

The following listing shows how to specify the dependencies to the Hibersap libraries in your pom.xml.

If you use Hibersap directly with JCo you need to declare the following dependencies in your project:

When using Hibersap with JCA you need to declare the following dependencies:

Due to Maven’s dependency management capabilities, all transient dependencies are automatically resolved so that there is no need to specify any of the above mentioned third-party libraries. One exception to this is the dependency to the SAP Java Connector (JCo) which you need when using Hibersap directly with JCo. This dependency in declared as optional in the pom.xml of the hibersap-jco module. Because of this it is explicitly declared in the above example.

The format of the XML configuration file is inspired by JPA’s persistence.xml. If you have to access different SAP systems, you can define more than one SessionManager by multiplying the session-manager XML element.

The following example shows XML file configuration when using Hibersap with JCo. Note that you may use the Hibersap XML schema definition as shown in the hibersap element to get validation and auto-completion in your IDE or XML editor.

The following example shows the XML file configuration when using a JCA compatible resource adapter.

Following is a complete list of Hibersap’s configuration parameters.

To build a SessionManager using XML file configuration, you simply have to create an object of class org.hibersap.configuration.AnnotationConfiguration, specifying the SessionManager name as an argument. Note that there is also a default constructor for AnnotationConfiguration which can be used if there is only one configured SessionManager. Hibersap will issue a warning when there are more than one `SessionManager`s configured, but the no-args constructor is used.

After creating a Configuration object which will be used to build the SessionManager, configuration can be set or overwritten programmatically.

The information from the XML file is internally converted into a Java data structure reflecting the structure of the XML document. All configuration classes have Java Bean style accessor methods (get.. and set..) for their fields.

When using programmatic configuration you have to change or create SessionManagerConfig for each SessionManager you want to use. You can use method chaining to build the object. The following example creates a SessionManagerConfig object that is equivalent to the one created internally when using XML file configuration.

Since Hibersap maps SAP Remote Function Modules to plain Java classes, an application must define one class for each function module that acts as a kind of proxy. This class is called a BAPI class and has to be annotated with the @Bapi annotation. (a BAPI, Business Application Programming Interface, is actually a subset of all Remote Function Modules in a SAP ERP system but provides a more handy term). The annotation’s value property defines the name of the corresponding function module:

A function module’s interface usually has a set of parameters which are either of a scalar data type (such as a number, a text or a date) or of a complex data type (in ABAP a complex type is called structure, and provides a set of attributes of scalar or complex data type). In Hibersap, scalar parameters can be mapped directly to a field of the BAPI Java class, whereas structures are mapped to complex Java types, i.e. classes with a set of fields. The classes representing an ABAP structure may be annotated with the @BapiStructure annotation, but this is not mandatory. Since Structure class instances need to be created by Hibersap, they must have a default constructor.

To map parameters of a function module to fields of Java classes, those fields have to be annotated with the @Parameter annotation. Here, Hibersap needs to know the name of the function module’s parameter as well as its type (scalar or complex) using the annotation’s value and type properties respectively. The Enumeration ParameterType defines the types ParameterType.STRUCTURE and ParameterType.SIMPLE for parameters of a complex or scalar type:

Since the interface parameters of ABAP functions are divided into import, export and table parameters, Hibersap has to know where to find the corresponding parameters. The @Import, @Export and @Table annotations provide this information.

ABAP tables are lists of complex parameters. As such they are mapped to a Java array or a java.util.Collection field. Hibersap again needs to know the name of the ABAP parameter as provided by the @Parameter annotation and its type as provided by the @Table annotation. It is a special characteristic of table parameters in ABAP that they import and export data in both directions.

An import or export parameter can also be a table, in which case the parameter needs to be annotated with @Import or @Export and @Parameter(…​, type = ParameterType.TABLE_STRUCTURE).

Tables that import data to the function module are filled by the Java application, Hibersap will use the application-provided array or collection to populate the table. Tables that export data from the function module will be read by Hibersap and copied to the corresponding array or collection. Hibersap detects the type of its elements by the array type if it is declared as an array, or by its generic type if it is declared as a collection. When using a collection, it is crucial to declare it with a generic type (the class Flight in the example), otherwise Hibersap will throw an error because it cannot determine the element type:

The field representing a table does not need to be defined as a concrete implementation of the java.util.Collection interface. When Hibersap creates a collection, it instantiates a java.util.HashSet for fields defined as java.util.Set and a java.util.ArrayList for fields defined as java.util.Collection or java.util.List.

The following list shows an overview of the Hibersap annotations.

Java Bean Validation (JSR 303) is a Java EE standard which defines an API and metadata model (in the form of Java annotations) to validate Java Beans and their attributes. If a Bean Validation provider is on the classpath of your application, Hibersap will validate the BAPI and Structure classes each time before a function gets executed.

To configure Bean Validation for your Hibersap application you may specify the validation element in the hibersap XML configuration file:

If using programmatic configuration, just set the validationMode property of the SessionManagerConfig:

The validation element may contain any of the values defined in org.hibersap.configuration.xml.ValidationMode:

Chapter Configuration explains in detail how to configure Hibersap. The following code snippet assumes that there is the /META-INF/hibersap.xml configuration file defining a session manager named "A12" in the application’s classpath and shows how to build a SessionManager instance:

The SessionManager should be created only once in an application’s lifetime since its creation is It depends on the kind of application how to store the SessionManager instances. In a web application they may be created and closed in a ServletContextListener when starting and stopping the application, putting them into the servlet context. In an EJB application this may be done using a Singleton EJB and its life-cycle methods and binding the individual SessionManager instances to JNDI. In a stand-alone application the SessionManager might be simply passed around or managed by some dependency injection framework.

Calling a remote function module in SAP is as easy as opening a new Session with the SessionManager, creating an instance of the BAPI class with the required parameters and passing it to the Session.execute() method.

When calling Session.execute(), Hibersap populates the given Bapi object with the SAP function’s return parameters as defined in the parameter mappings.

A physical connection to the SAP system is created during the first call of Session.execute(). It is crucial to close the Session when it is no longer needed. If sessions are not closed, the connection pool (as managed by JCo or the resource adapter) may get exhausted. Therefore it is strongly recommended to close the Session in a finally block like in the above example. This makes sure the session gets closed even if an exception is thrown during execution of the try block.

Keep in mind that, if the application keeps sessions open for a long time, connections may also be shut down by the SAP system after some timeout period or there is some possibility that they may get broken due to network problems. Thus, a session should have a short lifetime (just like a database session) and should only be used for a single unit of work.

Hibersap sessions are inexpensive to create, the Java Connector’s or Resource Adapter’s connection pool takes care of an efficient connection management (if properly configured), and Hibersap will not akquire a SAP connection before it is needed.

There are two kind of interceptors that intercept calls to SAP function on different levels. Both interceptor types make it possible for applications to apply additional logic which is related to cross-cutting concerns like e.g. logging. Both interceptors are registered with a session manager in the Hibersap configuration and apply to all function calls using this session manager.

The Hibersap Session has a method beginTransaction() which must be called when starting the transaction. beginTransaction() returns a Transaction object on which you can later call the methods commit() or rollback() to tell SAP to commit or rollback all changes made during the transaction.

In Java EE applications that make use of EJBs and Bean Managed Transactions (BMT) it is also necessary to explicitly start, commit and rollback transactions like in the code example.

Applications running in an application server and using EJBs and a Java EE compatible Resource Adapter can profit from the application server’s capability to automatically handle transactions. This is called Container Managed Transactions (CMT).

In case of using CMT, the application code does not have to take care of starting, committing and rolling back transactions.

See section Java EE Integration for a detailed discussion on Container Managed Transactions.

The most common way to interact with a SAP system in enterprise applications is to use a central SAP user that is shared by all users of the application. Using this kind of authentication is a matter of configuration. When using Hibersap with JCo, the user credentials are provided through Hibersap configuration, namely the JCo properties defined for a SessionManager. When using Hibersap with JCA, the credentials are usually defined in the resource adapter configuration.

If the application has to provide user credentials, e.g. when each application user logs on to the SAP system using his own SAP account, you can specify logon credentials for each Hibersap session you create.

In this case, when obtaining a Session from the SessionManager, the method openSession( org.hibersap.session.Credentials ) must be used. The authentication information is specified in the Credentials object.

Hibersap simply passes the attributes defined in the credentials object to SAP. The following table lists the available attributes of the Credentials class including the corresponding JCo parameter as defined in interface com.sap.conn.jco.ext.DestinationDataProvider of the SAP Java Connector version 3.

Using this method with JCo mode, Hibersap will internally create a custom JCo destination setting the specified credential attributes. Note that in this case, every user needs to have the proper permissions in SAP to use the function modules that are called via Hibersap.

In addition to calling the function modules itself, JCo makes calls to the SAP system to obtain meta data on function modules, the so-called repository calls. Those calls depend on different sets of permissions which the specific user might or might not have. Therefore, JCo uses a configured user to do repository calls instead of the current user supplied with the Hibersap credentials object when creating custom destinations. This user may either be configured via the JCo parameter jco.client.user, or with a separate user for repository calls using the parameter jco.destination.repository.user. The latter is recommended for applications which make use of per-session authentication, for this makes sure the functions are always called with the session user and the repository calls are done with the repository user. In this case, the property jco.client.user should not be set.

When using Hibersap with JCA, the configuration should be done accordingly, but is resource adapter specific. The Cuckoo Resource Adapter defines almost all possible JCo properties and passes them on to the Java Connector.

A special case of per-session authentication is the use of single sign-on. In a SAP environment it is common to use SAP Logon Tickets issued by SAP systems. In a web application / portal scenario the ticket is stored in a cookie named MYSAPSSO2 in the HTTP user session. After obtaining this ticket it can be passed to the Hibersap session by setting the `Credentials.ssoTicket' field object like described in the previous section.

In an application server the JTA transaction manager handles transactions. In combination with EJBs and container managed transactions (CMT), the application code does not need to care about transaction demarcation because the container sets the transaction boundaries implicitly. This simplifies development and reduces the probability of errors.

If using CMT, all the function calls to SAP which take place during a call to an EJB business method are running in one transaction. When the EJB method returns normally, the transaction manager commits the transaction while in case of an error the transaction is automatically rolled back. In this context, error means that either a RuntimeException is thrown or a Java EE application exception configured with the rollback=true attribute. (Note that Hibersap itself only throws unchecked exceptions.)

In EJB3, container managed transaction is the default transaction management demarcation. However, can be explicitly declared using the @TransactionManagement annotation with a transaction management type of CONTAINER or BEAN. The transaction semantics are further defined by the @TransactionAttribute annotation on the EJB class or the individual EJB methods where TransactionAttributeType.REQUIRED is a sensible default value.

With a resource adapter there are two different methods to authenticate with the SAP R/3 system: container managed and component managed authentication. Hibersap supports both authentication methods.

With component managed authentication, an application passes credentials each time a connection is obtained from the resource adapter. This method may be used when each user of the application signs in using its own SAP user, e.g. by entering the user name and password in the application or when using single sign-on with logon tickets. In JCA, the credentials are passed with a javax.resource.cci.ConnectionSpec instance. Internally, Hibersap will create this instance and fill it with information passed with the credentials object when a new session is opened. (The code is the same as in Per-session authentication.)

With container managed authentication the sing-on information is either obtained from a JAAS login module or — in the simplest case — a central user and password is taken from the resource adapter’s configuration. Using a login module, the sign-on information is passed by the container to the resource adapter with a javax.security.auth.Security object. Login module configuration is container specific.

Another advantage of using a resource adapter over using JCo directly is that a resource adapter can be deployed and configured independently of the applications that use it. Thus it is not necessary to reconfigure and redeploy all applications that connect to a SAP system whenever connection parameters (e.g. the SAP system’s host name) change. Instead, only the resource adapter has to be reconfigured. Since the configuration of the resource adapter specifies all the necessary properties to access the SAP system, in the Hibersap configuration you just need to specify the JNDI name that is used to look up the resource adapter’s connection factory.

If using Hibersap in a Java EE environment with Enterprise Java Beans, consider using the Hibersap EJB tools. The EJB tools help in automatically creating Hibersap Sessions, injecting them into your EJBs and closing them.

The following code implements a Stateless Session EJB with a business method to search for Customers in SAP. The EJB’s business methods are intercepted with the HibersapSessionInterceptor. It has a field named session which is annotated with @HibersapSession to tell the interceptor which SessionManager to inject into the EJB. The annotation’s value parameter specifies a JNDI name to which the SessionManager is bound.

CustomerSearch is a Hibersap BAPI class. As can be seen, the code can directly use the injected Hibersap session to call functions in the SAP backend. There is no need to close the Session, this is done by the interceptor. The example uses container managed transactions and the method is called with transaction attribute REQUIRED (the default behaviour). This makes sure the SAP call is transactional and will be committed or rolled back by the transaction manager after the EJB business method was executed.

Internally, the interceptor adds each created Hibersap session to the EJB’s session context to make sure that subsequent calls to other EJBs use the same session. When the HibersapSessionInterceptor is executed, it first checks if a session of the specified session manager is already in the session context. If so, it uses the existing session, else a new session is created.

On returning from the business method for which the session was opened, the interceptor will close the session, thus making sure the underlying JCA connection will be returned to the connection pool.

To make the example complete we need a way to create a SessionManager and bind it to JNDI where it can be looked up by the interceptor. The following code implements a singleton EJB with the @Startup annotation that is created when the application gets deployed. The container will automatically call the lifecycle method rebindSessionManager() which is annotated with @PostConstruct when the EJB is started. The method creates a session manager from a Hibersap XML configuration file and binds it to JNDI. When the application gets undeployed, the method unbindSessionManager() is called which removes the session manager from JNDI. To actually bind and unbind the session manager to and from JNDI, the helper methods in class JndiUtil are used which is a part of the hibersap-ejb module.

When using Maven add the hibersap-ejb module to your application by defining the following dependency: