Copyright © 2001–2002 ARAsoft GmbH (http://www.arasoft.de). All rights reserved. 1
Version 0.8.1
Thomas G. Schuessler,
www.ARAsoft.de:
Developing Applications
with the
"SAP Java Connector"
(JCo)
Sponsor programme and close down.
James Joyce: Finnegans Wake, p. 531.27
The more complex the system and the more expert the users,
the more their technical conversation sounds like the plot of a soap opera.
Steven Pinker: How the Mind Works, p. 78
Copyright © 2001–2002 ARAsoft GmbH (http://www.arasoft.de). All rights reserved. 2
Version 0.8.1
1. Introduction
1.1. New in this Version (0.8.1)
I have added Appendix A-8 which contains a full-blown, annotated example of how to
create a sales order.
1.2. Disclaimer
This text is a preliminary, incomplete version of a book that I will publish on
programming with JCo. The complete book will have much more information. No
guarantee is given for the technical accuracy of any information in this text. We are not
responsible for any damage resulting from the use of the presented information or
running the associated sample programs.
1.3. What is JCo?
SAP's Java middleware, the SAP Java Connector (JCo) allows SAP customers and
partners to easily build SAP-enabled components and applications in Java. JCo supports
both inbound (Java calls ABAP) and outbound (ABAP calls Java) calls in desktop and
(web) server applications.
1.4. Goal and Scope of This Text
This text wants to teach you how to build client applications using JCo. You are supposed
to already know Java. Some understanding of SAP would also be helpful, but you should
be able to get by even if you do not know much about SAP yet. We will cover all relevant
aspects of client programming (where Java calls SAP). The final version of this text will
also introduce outbound (server) programming.
This text does not make the study of the JCo documentation superfluous. It is probably a
good idea to look at the Javadocs for the various classes in a separate window while you
work through this text.
To try out the accompanying sample programs, you need only
1
a JDK and JCo installed,
but a decent development environment (like JBuilder
2
) would make your life a lot easier.
1.5. Organization of This Text
In order not to confuse beginners, advanced material is presented in Appendix A. The
text will tell you which chapter in this appendix will give you more in-depth information
about a topic. Appendix B is a listing of the sample programs associated with this text.
1
Unless specifically stated otherwise.
2
We now offer a nice proxy generator integrated into JBuilder, see Appendix A-7.
Copyright © 2001–2002 ARAsoft GmbH (http://www.arasoft.de). All rights reserved. 3
Version 0.8.1
2. SAP Remote Function Call (RFC)
Before you can start with JCo programming, you need to understand the SAP architecture
to a certain extent, particularly how you can invoke SAP functionality from the outside
(client programming) and how ABAP applications can invoke your components (server
programming).
The basis for all communication between SAP and external components (as well as for
most communication between SAP components) is the Remote Function Call (RFC)
protocol. RFC comes in three flavors.
Most client programs want to use regular, Synchronous RFC (sRFC), but SAP also
supports Transactional RFC (tRFC) and Queued RFC (qRFC). tRFC is used mainly to
transfer ALE Intermediate Documents (IDocs). Currently, this text covers only sRFC, but
JCo also supports tRFC and qRFC.
2.1. BAPIs and Other RFMs
ABAP Function Modules can only be called from an external client if they are marked as
RFC-enabled. R/3 contains several thousands of such RFC-enabled Function Modules
(RFMs). Amongst them are the BAPIs. BAPIs are RFMs that follow additional rules and
are defined as object type methods in SAP's Business Object Repository (BOR). Use
transaction codes BAPI and SE37 to investigate the metadata of the BAPIs and other
RFMs in SAP. If you do not have access to an SAP system, or you want to look up
interfaces in a different release, use the SAP Interface Repository
(http://ifr.sap.com).
An RFM can be released for customer use or not.
3
Most BAPIs are released RFMs, only
very new ones may be unreleased at first so that SAP and the customers can test them for
a while before they are released in a subsequent release. On the other hand, there are
quite a few extremely useful RFMs that are not officially released for customer use.
Many of these RFMs are not documented (or only in German), which makes it harder to
figure out exactly how they work. Additionally, SAP has reserved the right to make
incompatible changes to unreleased RFMs. Using these directly in your applications
could thus result in a huge maintenance effort. Hence all access to unreleased RFMs must
be done through components in order to limit maintenance to this one component as
opposed to potentially many individual applications.
2.2. RFC-enabled Function Modules (RFMs)
RFMs can have three types of parameters, import (the client sends these to the RFM),
export (RFM sends these back to the client), and tables (bi-directional). Import and
export parameters can be simple fields (a.k.a. scalars) or structures.
4
A structure is an
ordered set of fields.
3
Actually, there are three states: not released, released within SAP, released for customer use. For people
outside of SAP, the two former categories can be subsumed under unreleased.
4
Since some time SAP now also allows complex structures and tables as parameters. The BAPIs do not use
this capability, as far as I know (nothing is ever really certain in BAPI land). JCo supports complex
parameters, but this text ignores them for now.
Copyright © 2001–2002 ARAsoft GmbH (http://www.arasoft.de). All rights reserved. 4
Version 0.8.1
A table parameter has one or more columns (fields) and contains zero or more rows.
Import and table parameters can be mandatory or optional, export parameters are always
optional. You can check these attributes in SAP or even at runtime.
Some people assume that table parameters are somehow magically linked to the database
tables in SAP. That is not the case. If you change a table that an RFM call returned,
nothing happens in SAP. A table is really just a form of glorified array (glorified because
we have metadata for the columns). Changes in SAP will only happen if you call an RFM
that uses a table parameter you pass to it in order to update the database.
RFMs can also define ABAP exceptions. An ABAP exception is a string (e.g.
NOT_FOUND) with an associated language-dependent message text. We will discuss
exception handling below.
2.3. The SAP Data Dictionary
In RFC programming, eventually we always deal with fields. These fields can be scalar
parameters themselves or contained in a structure or table row. Most, but not all, fields
used in RFMs are based on Data Dictionary (DD) definitions. Each field in the DD is
based on a Data Element (which in turn is based on a Domain) or a built-in DD data type.
The Domain defines the basic technical attributes (data type, length, conversion routine,
check table, etc.), whereas the Data Element contains the more semantical information
(texts and documentation).
There is a lot of metadata available for each field in SAP. I will now introduce the most
important attributes and how they affect your applications (more details can be found in
the next section):
• Data type, length, number of decimals: These are essential for dealing with fields
correctly and building nice user interfaces that are aware of the field attributes. JCo
makes these attributes available to the client program.
• Check table: Many fields contain codes. End-users do not want to deal with them, at
least not without the associated descriptions. When you call a BAPI and display the
returned country code, the users will not be happy. They need the name of the country
instead of – or together with – the code.
If users have to enter codes, they do not want to guess; they want a list of available
codes (Helpvalues) with their descriptions.
• Fixed values: This is similar to check tables, but the information about the codes is
stored in the Domain, not in a separate table.
• Conversion exit: Many fields use conversion exits in SAPGUI to translate between
the internal and external representations of data. Most BAPIs return and expect the
internal format, which makes little to no sense to your users.
• Texts and documentation: SAP stores multiple texts per field and also extended
documentation in many cases. This documentation is available in all installed
languages and therefore an easy way to provide multi-lingual capabilities in your
applications.
• Mixed case support: Many text fields in SAP are uppercase only. If users exercise
care in entering data in mixed case, they will not be too happy to discover later that
everything was capitalized in SAP. Your user interface should exploit the mixed case
attribute to indicate to the users which fields are uppercase only.
Copyright © 2001–2002 ARAsoft GmbH (http://www.arasoft.de). All rights reserved. 5
Version 0.8.1
The ARAsoft JCo Extension Library allows easy access to all the required metadata that
JCo does not expose. The library also offers services that solve all the practical problems
associated with the metadata, including Helpvalues, conversions, text retrieval. See below
for details.
2.4. BAPI Specifics
As stated above, a BAPI is an RFM that follows additional rules (defined in the SAP
BAPI Programming Guide
5
) and is defined as a method of an object type in the BOR. An
example for a BAPI, as defined in the BOR, is SalesOrder.CreateFromDat1. The actual
RFM implementing this BAPI is BAPI_SALESORDER_CREATEFROMDAT2. When
comparing the metadata shown by the BAPI Explorer (transaction code BAPI) and those
in the Function Builder (transaction code SE37), you will notice that there can be
discrepancies like different parameter names. When writing your actual application code,
you need to use the names presented by the Function Builder. It is best to use the BAPI
Explorer just as a convenient starting point to find suitable BAPIs and then review the
actual metadata of the RFM in the Function Builder (unless you use proxies, see below).
The BOR presents certain attributes not available in the Function Builder:
• Is the BAPI obsolete? When SAP wants to change a BAPI in a way that would be
incompatible with the existing version, they create a new BAPI instead, e.g. Create1
would be the new version of Create. The old BAPI becomes obsolete. An obsolete
BAPI is guaranteed to exist and work in the release in which it is marked as obsolete
and the subsequent functional release. For example, a BAPI made obsolete in 4.0A
would still be valid in 4.5B (the maintenance release for the functional release 4.5A),
but might disappear in 4.6A.
• Is the BAPI released? Checking this is of utmost importance. SAP sometimes creates
new BAPIs without releasing them yet. Only released BAPIs are guaranteed to be
upward-compatible, though, so you should only use unreleased BAPIs if you have no
other choice.
• Does the BAPI pop up SAPGUI dialogs? These BAPIs were built mainly for the
communication between SAP components, they rarely make any sense in a Java
application. SAPGUIs are difficult to pop up from a web application running in a
browser…
If you want to use BAPIs in a more object-oriented way, you need to utilize proxy
classes. These proxies have the following advantages:
• A business object type in the BOR is represented by one Java class, the BAPIs are
methods of the class.
• Instead of the somewhat ugly function and parameter names in the SAP Function
Builder you use the nice names in the BOR.
• You can exploit additional BOR metadata. One example is that the BOR knows
which table parameters are import, which are export, and which are import and
export. The Function Builder has no notion of this.
5
Not all BAPIs follow all the rules, though. This can lead to a lot of confusion and frustration for
developers. This texts points out some of the deviations and their consequences.
