jrsapjee

Accessing BAPIs Using the SAP Java Resource Adapter Motivation This tutorial is designed for all Java Developers who want to call function modules and BAPIs in their J2EE Application and who may already have used the SAP Java Connector (SAP JCo) for this task. However, the SAP JCo – which can be used in any Java application – is not closely integrated in the J2EE Application Server and does not follow the J2EE standards for integrating enterprise information systems. Therefore, if you have a J2EE application, we recommend using the SAP Java Resource Adapter 1.0 (SAP JRA) instead. SAP JRA 1.0 is implemented in compliance with the J2EE standard 1.3 for integrating enterprise systems: - the Java Connectivity Architecture (JCA) 1.0 – and offers the same functions as SAP JCo. You can call function modules and BAPIs in the ABAP backend. Since SAP JRA uses SAP JCo for the calls, SAP JRA is basically a thin software layer between SAP JCo and your J2EE application that maps the SAP JCo API to the standard interface. But this is not all. Since SAP JRA is closely integrated with the J2EE Application Server, SAP JRA makes use of J2EE Services, which are not as easily accessible through SAP JCo.

In this tutorial, we will demonstrate an example of a Web application that allows you to book flights in the ABAP backend. This application makes use of the SAP JRA to get information from the backend – for example, a list of available flights – and to enter data in the database of the backend in a transactional context when a flight is booked. As you may already have noticed, we only use calls from Java to ABAP in our example. This is based on the fact that version 1.0 of SAP JRA does not support calls from ABAP to Java. This function will be available with SAP JRA 1.5 and delivered with J2EE 1.4. Task In the first section of this tutorial, you will learn how to deploy the SAP JRA using the deployment tool of the J2EE Application Server. Then you will use the Visual Administrator to configure the ABAP System where you wish to call the BAPIs. In the next section, the Web application “Book Your Flight” will be deployed. You can choose between the Developer Studio and the Visual Administrator for deployment. The procedure is described for both cases. As soon as SAP JRA and the Web application are successfully deployed, the application can be started. The next section describes how you run the “Book Your Flight” application and tells you what items are worth having a look at. Finally, in the last section, we will look at the “Book Your Flight” application in detail in order to see why it is better to use SAP JRA in the context of a J2EE application instead of SAP JCo. We will look at the source code of the application “Book Your Flight” and the deployment descriptor of SAP JRA, and also see how transaction management and the user definitions of the security service can be easily applied in applications using SAP JRA. Prerequisites In order to run the application „Book Your Flight“, the following prerequisites are required:

1. An ABAP system with a maintained flight module is available. This means that in the ABAP transaction bapi you can find the Business Objects Flight, FlightCustomer, and FlightBooking. In addition, flights are defined for the system and at least one flight has already been booked. The two last requirements can be checked by calling the function Flight → GetList and FlightBooking → GetList without input parameters. If the size of the flight list and the booking list is not zero, the requirements are fulfilled.

2. A user exists for the ABAP system that is authorized to call the function modules

of the Business Object Flight, FlightCustomer, and FlightBooking using RFC. For more information about RFC authority checks and which authorization object is relevant for RFC calls, as SAP Customer you can refer to SAP OSS Note 93254.

3. A second user exists for the ABAP system with authorization to retrieve metadata of function modules through RFC. In SAP OSS Note 460089, the function groups provide a list of which function modules should be accessible through RFC in this context.

4. An SAP J2EE Application Server is installed and started, and you can access the

machine where it is installed.

5. A J2EE application user exists whose name and password correspond to the name and password of the ABAP user authorized to call BAPIs for Flight, FlightCustomer, and FlightBooking. You can create this user with the help of the security service API of the J2EE Application Server. In addition, you have to perform the subsequent steps:

a. Start the Visual Administrator using go.bat from the directory //<SAP J2EE Engine Installation Directory/… /j2ee/admin and connect to the SAP J2EE Application Server.

b. Switch to Cluster → <Server Node> → Services → Security Provider on the navigation tree.

c. Select the User Management tab on the right. d. To switch to edit mode, choose the icon Switch to edit mode. e. Choose Create User and enter the user and password. f. Set also the flag No password change required.

If the user has been created successfully, you will receive the entry shown below:

6. A Developer Studio is installed that is compatible with the SAP J2EE Application

Server. Deploying the SAP JRA First of all, a Java Resource Adapter with the JNDI name SAPJRADemoFactory must be deployed to the J2EE Application Server and configured. Since the SAPJRA is delivered as an sapjra.rar file, either telnet or the deploy tool can be used for deployment. In the following, deployment using the deploy tool is described Prerequisites

You are logged on to the computer where the J2EE Application Server is installed and running. Note: SAP JRA is an add-on for SAP JCo and is delivered together with SAP NW AS as a sapjra.rar file. You can find this file in the installation directory: //<SAPJ2EE Engine Installation>/usr/sap/<System ID>/sys/global/ra/sapjra.rar.

Procedure

1. Start the deploy tool of the SAP J2EE Application Server with the DeployTool.bat

in the directory //<SAP J2EE Engine Installation Directory/.../j2ee/deploying. 2. Choose Project → New Project and enter a name for the new project. 3. Click on the Deployer tab. 4. From the menu path, choose Deploy → EAR → Load Module and select the

sapjra.rar file. 5. For the newly created node sapjra.rar, choose Server Settings → Identity Subjects

and select Caller Impersonation as authentication type, so that the J2EE user data is used to log on to the ABAP system.

6. Make sure that the J2EE Application Server is running. Connect to the J2EE

Application Server with Deploy → Connect. 7. Deploy the sapjra.rar using the menu Deploy → Deployment → Deploy Module. 8. Enter SAPJRADemo as application name and start the application.

9. Close the deploy tool. 10. Start the Visual Administrator again. 11. Select the Cluster tab and switch to <Server Node> → Services → Connector

Container. 12. Click on the Runtime tab and choose sap.com/SAPJRADemo →

eis/SAPJRADemoFactory. 13. Choose Managed Connection Factory → Properties.

On this page, you need to specify the logon data for the ABAP system. There is already some dummy data visible in the property list if no real system data has been specified so far.

14. To change the value of a property, select the property in the list, change the value underneath it, and add the changes using the Add button. At the end, do not forget to save all changes by pressing the button Save Changes. The user configured for the SAP JRA must be the user authorized to read metadata of function modules.

Result If the SAP JRA has been deployed correctly, you also should see a corresponding node in the Deploy Service in the Visual Administrator. To check it, proceed as follows: Click the Cluster tab and choose <Server Node> → Services → Deploy. Click the Runtime tab, expand the tree node Deploy Service → Server * → connector, and check if the node sap.com/SAPJRADemoFactory is visible. A flag mark should also be set denoting that the application has started successfully.

Deploying the Sample Application “Book Your Flight” Now that the SAP JRA has been successfully deployed, we are going to deploy the sample application “Book Your Flight” that uses the SAP JRA. Typically, you perform this step from within the Developer Studio. In the following Procedure A, we describe how this works. For those of you who have no chance to use the Developer Studio, we also describe in Procedure B how you deploy the application using the Visual Administrator. Prerequisites

• You have downloaded the archive JRA_FlightBooking.zip from the SAP WebAS Tutorial and Samples page of the SAP Developer Network.

• The J2EE Application Server must be started and you must have authorization

either to start the Visual Administrator or to use the Developer Studio. Procedure A The deployment comprises two steps. Firstly, we need to import the prepared sample projects into the Developer Studio. Secondly, we will deploy the application to the J2EE Server. Importing into the Developer Studio Workspace

1. Extract all files of the JRA_FlightBooking.zip to any directory of your choice. 2. Launch the SAP NetWeaver Developer Studio and open the J2EE Development

Perspective (Window → Open Perspective → J2EE Development). Then choose File → Import.

3. To start the import wizard, choose Multiple Existing Projects into Workspace and then Next.

4. Select as base folder the directory where you have extracted the files for JRA_FlightBooking.zip.

5. Select the sample projects FlightBookingWeb, FlightBookingEjb, FlightBookingEar and FlightBookingUtil.

6. Check also Open Projects after import and choose Finish to confirm. 7. If you switch to the Package Explorer view, you will also see the Java Project

FlightBookingUtil containing the helper classes.

Deploying the Ear

1. Launch the SAP NetWeaver Developer Studio, if required 2. Specify the SAP J2EE Server where you want to deploy the application by

choosing Window → Preferences → SAP J2EE Engine.

3. Open the J2EE Development perspective and then the J2EE Explorer view. 4. Select the project node FlightBookingEar and then the Ear file

FlightBookingEar.ear. 5. Choose Deploy to J2EE engine from the context menu.

Procedure B You can also deploy the “Book Your Flight” example through the Visual Administrator. The following steps are necessary:

1. Launch the Visual Administrator, if this has not already been done. 2. Choose Cluster → <Server Node> → Services → Deploy. 3. Click on the button Deploy & Start, choose as ear file the file

FlightBookingEar.ear, and start the deployment using the OK button.

Result If you have not received any error message during deployment time, you should see the deployed application in the Deploy Service. In order to check this, follow the steps described below.

. 1. In the Visual Administrator, choose Cluster → <Server Node> → Services →

Deploy. 2. Click on the Runtime tab and choose Server * → EJBContainer. There you should

find the node sap.com/FlightBookingEar and see a flag mark indicating that the application has been started successfully.

3. Click also on the Runtime tab and choose Server * → servlet_jsp. Here you

should see the sap.com/FlightBookingEar node with a checkmark for a started application.

Run Application “Book Your Flight” The application “Book Your Flight” allows you to book flights for given dates and airports. As the information about available flights and the booking is on the ABAP side, the application makes use of the connections provided by the SAP JRA in order to call the relevant BAPIs for Flight, FlightCustomer, and FlightBooking. This section explains how you run this Web Application “Book Your Flight”. Prerequisites The J2EE Application Server is running, and the SAP JRA and the application “Book Your Flight” are deployed successfully. Procedure

1. Enter the URL http://<host>:<http_port>/jrademos/servlet/bookyourflight in your Web Browser. For example, for a J2EE Application Server that runs on your local host and has 50000 as HTTP port, this would be http://localhost:50000/jrademos/servlet/bookyourflight.

2. A logon module pops up. Enter the name and password of the J2EE application user whom you have defined as prerequisite for this tutorial.

3. Enter a flight date and destinations, and press the Select button. If you always get the message “Regrettably, no flight was found for the current selection!” or the message “BAPI_FLIGHT_LIST call returned with error - City Anywhere unknown”, log on to the ABAP system and run the BAPI GetList for Business Object Flight in the ABAP System in order to see which flights were defined for the flight model on the ABAP side.

4. As soon as you have received a list of flights, select a flight from this list and press the Continue button.

5. Now you either roll back the booking transaction or complete it by choosing the Cancel or Confirm button. If you choose Confirm, the booking data will be displayed on the next screen.

6. To check the list of flights, return to the first page using the Select your Flight button.

Result If the SAP JRA and the application work correctly, you will see the following two features.

1. If you have chosen Confirm and booked a flight in the sample application, the number of available seats should be reduced by one for the selected flight when you return to the first page in step 6.

2. If you have chosen Confirm, you also should see, in step 5, that the customer name corresponds to the logon user. This should be the case because the application “Book your Flight” takes as the customer name the name of user that the SAP JRA has applied in order to call the BAPIs. In addition, the user that calls the BAPIs corresponds to the logon user since you have chosen “Caller Impersonation” as authentication type during the SAP JRA deployment.

SAP JRA Features in Detail Now might be a good time to have a look at how the application is implemented. We have chosen a three-tier architecture to perform the “Book Your Flight” example. The User Interface is based on the servlet and the JSPs. These serve to display flight dates and flight destinations. A list of available flights and the booking data are also displayed on the UI. On the ABAP side, the Flight Model is used. This includes the BAPIs for Flight, FlightBooking, and FlightCustomer and some database tables – for example, a table with all available flights. The middle-tier layer consists of three EJBs, associated with the three BAPIs in the ABAP system. This layer forms the interface to the ABAP system and here the SAP JRA is used for the connection. SAP JRA is closely integrated with the SAP J2EE Application Server. In our sample application “Book Your Flight”, the SAP JRA uses features from transaction management and from the security service of the J2EE Application Server. This section shows how these features were applied in the application “Book Your Flight”. Transaction Management The booking of the flight on the ABAP side should be done in a transactional context. If you use the SAP Java Connector (SAP JCo) for booking, you have to call the BAPIs BAPI_TRANSACTION_COMMIT or BAPI_TRANSACTION_ROLLBACK for the rollback or commit of the transaction. In the case of SAP JRA, you have to do nothing – provided you have chosen “Container” as transaction type, because the container handles the transaction and calls the BAPIs accordingly. However, in the example “Book Your

Flight”, we have chosen “Bean” as transaction type in order to demonstrate how simple transaction handling is performed using the SAP JRA. To take a look at how the transaction handling is implemented, start the Developer Studio and proceed as follows:

1. Open the J2EE Development Perspective (Window → Open Perspective → J2EE Development) and open the Package Explorer view.

2. Expand the project node for the EJB project FlightBookingEjb, which contains the EJBs Flight, FlightBooking, and FlightCustomer.

3. Open the Java Editor for the FlightBookingBean class. 4. Have a look at the methods openConnection(), startTransaction(),

confirmTransaction() or rollbackTransaction() and closeConnection(), respectively. These are called one by one during flight booking.

In the openConnection method, you see how to get a connection from your deployed SAP JRA. In startTransaction, the transaction for the current transaction is started using the call “connection.getLocalTransaction().begin()”. The confirmTransaction method contains the call connection.getLocalTransaction().commit() to commit the transaction. The rollbackTransaction method contains the call connection.getLocalTransaction().rollback() to roll back the connection. As you probably have already noticed, the method confirmTransaction is called when you press the “Confirm” button of the application “Book Your Flight” and the method rollbackTransaction is called when you press the “Cancel” button. In closeConnection, the connection is finally closed in order to avoid an accumulation of open connections.

Security Services As mentioned in step 2 of the Result, when you run the application “Book Your Flight”, the customer name corresponds to the logon user. This is only one of several options of how security features of the J2EE Application Server can be used with SAP JRA. For example, you can configure the SAP JRA in such a way that the user data defined in the Connector Container is applied to call the BAPIs. The authentication for application “Book Your Flight” can be split into two steps. First, you authenticate yourself in order to be permitted to run the Web Application. Then you have to authenticate yourself to get access to the ABAP System. The way these two steps are related is defined by the parameter “authentication type” in the deployment descriptor of the SAP JRA.

To have a look at the deployment descriptor, open the sapjra.rar and double-click the file connector-j2ee-engine.xml. There you see that “Caller Impersonation” has been chosen as the authentication type, which results in the fact that the logon user is applied to call the BAPIs. If you had chosen “Configured Identity” as authentication type, the user defined for the SAPJRADemoFactory would have been used.

Summary In the last section, we described how SAP JRA effectively makes use of integration in the J2EE Application Server. Besides transaction management and the security service, SAP JRA also benefits from the thread management, the functions of the connector container, and the GUIs for configuration. If you are interested in additional information about the SAP JRA, refer to the SAP NetWeaver documentation in the SAP Help Portal: http://help.sap.com/saphelp_nw04/helpdata/en/6f/1bd5caa85b11d6b28500508b5d5211/frameset.htm As SAP Customer OSS note 861752 keeps you informed as to where to find the current documentation.