Chapter 3
Installation

3.1 The Hibersap libraries

The Hibersap framework is divided into the following libraries:

• hibersap-core-1.0
• hibersap-jco-1.0
• hibersap-jca-1.0

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.

3.2 Third party libraries

Hibersap has a few dependencies on third-party libraries, such as apache-commons or JAXB, which you have to add to your application’s classpath. The easiest way to achieve this is to build your projects with Maven, see section 3.3. Depending on which interfacing technology is actually used, you also need the SAP Java Connector (JCo) or a JCA compatible resource adapter.

3.2.1 Hibersap dependencies

Please see the project’s dependencies page under the following URL to get a list of libraries needed and add these to your application’s classpath: http://hibersap.sourceforge.net/dependency-convergence.html

3.2.2 The SAP Java Connector (JCo)

The SAP JCo library is provided by SAP to their customers and comes with its own license. Please check the following URL for more information and downloads: http://service.sap.com/connectors. You need to have a user and password for this URL, which is free for SAP customers. Valuable help regarding SAP technologies can also be found on the SAP Developer Network SDN: http://sdn.sap.com.

After downloading SAP Java Connector 3.0, extract the sapjco3.jar and the sapjco3 native library. The native library must be on your application’s library path. You may copy it to a global lib path, to a special directory such as C:/WINDOWS/SYSTEM32 on Windows systems or to the execution directory of the application (e.g. the bin folder of your application server or the folder from which you run your application). Additionally, the JCo jar file must be on the application’s classpath.

3.2.3 The SAP BAPI JCA Adapter

If you are using Hibersap with a resource adapter in a managed environment, the preferred choice is the SAP BAPI JCA Adapter. The project’s web site can be found under http://sourceforge.net/projects/sapbapijcaadapt/. By the way, the SAP BAPI JCA Adapter seems to be the only Open Source adapter for SAP R/3.

For your application, 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.

3.2.4 Using other JCA compatible Resource Adapters

The Hibersap JCA part was written using the SAP BAPI JCA Adapter and Hibersap was not yet tested with other resource adapters. Nevertheless, you are welcome to test Hibersap using other resource adapters and we would be glad to get your feedback.

Integrating a different 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. For a framework like Hibersap whose aim is to support different implementations this 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. The ConnectionSpecFactory implementation for the SAP BAPI JCA Adapter uses reflection for setting and getting the ConnectionSpec’s parameters in order to reduce (compile-time) dependencies to the resource adapter.

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

3.3 Building Hibersap applications with Maven

If you are building your application with Maven, you need to specify the Hibersap repository for your module. Adding the following part to the repositories section of your pom.xml gives your project access to the libraries you need when using Hibersap.

This is how you can specify the dependencies to the Hibersap libraries in your pom.xml. Depending on which interfacing technology you use, you generally need to depend from either hibersap-core and hibersap-jco or from hibersap-core and hibersap-jca.

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. However, since the SAP JCo and the SAP BAPI JCA Adapter can not be found in a (public) Maven repository due to its commercial license model, you have to manually add these libraries to your local repository.

The latest version of the SAP Java Connector can be downloaded from the SAP Service Marketplace at http://service.sap.com/connectors. There you will find different distribution packages for the supported platforms. To install the JCo jar to your local Maven repository, unpack the downloaded zip file (e.g. version 3.0.1) and issue the following command from your console.

After installing the JCo library to your local repository or alternatively deploying it to your project’s or company’s repository, you can include the JCo lib in your project by declaring the following dependency.

The other important file from the JCo distribution is the JCo native library which you must put into your application’s library path.