05 Architektur Payment Engine Eng

Jrg Wegener
IBS FS, NAD OS II
Payment Engine Software Architecture

- Version 3.0 24th July 2003
Distribution:
Payment Engine Project
Table of Contents:
1 Introduction.......................................................................................................................4
2 Conceptual Architecture..................................................................................................4
2.1 Object Orientation..................................................................................................................................... 4
2.2 Collections................................................................................................................................................. 4
2.3 Components.............................................................................................................................................. 4
2.3.1 Structure of Components: Internal Layer Model.....................................................................................5
2.3.2 Coupling of Components........................................................................................................................ 7
3 Basics of the Structures of Methods and Classes........................................................8

3.1 Basic Properties of Classes..................................................................................................................... 8
3.2 Basic Properties of Methods.................................................................................................................. 10
4 Business Process Control Classes..............................................................................11

4.1 Properties of Business Process Control Classes................................................................................11
4.2 Properties of Methods for Business Process Control Classes...........................................................11
5 Process Classes.............................................................................................................12
5.1 Properties of Process Classes............................................................................................................... 12
5.2 Methods of Process Classes.................................................................................................................. 13
5.3 Using Process Classes........................................................................................................................... 13
6 Entity Classes.................................................................................................................14
6.1 Properties of Entity Classes................................................................................................................... 14
6.2 Methods of Entity Classes...................................................................................................................... 14
7 Persistency Classes.......................................................................................................15
8 Technical Topics.............................................................................................................16
8.1 The Standard Header.............................................................................................................................. 16
8.2 Transaction Control................................................................................................................................ 16
8.2.1 Implementation of Transaction Control in (Business) Process Control Methods..................................17
8.2.2 Check Method CHECK_TA_CONTROL............................................................................................. 18
8.2.3 Transaction Method TA_CONTROL................................................................................................... 18
/var/www/apps/conversion/tmp/scratch_7/273893563.doc
Page
8.3 Logging.................................................................................................................................................... 18
8.4 Main Memory Synchronization............................................................................................................... 18
8.4.1 Standard memory synchronisation behaviour.......................................................................................19
8.4.2 Memory synchronisation without reference deletion.............................................................................20
8.4.3 Memory synchronisation without buffer deletion for persistency classes..............................................20
8.5 Access to External Components........................................................................................................... 21
8.6 BAPI Wrapper.......................................................................................................................................... 23
8.7 Error Handling......................................................................................................................................... 23
8.7.1 Exception Hierarchy.............................................................................................................................. 23
8.7.2 Reactions to Exceptions....................................................................................................................... 24
8.7.3 Processing Exceptions in the Calling Channel.....................................................................................31
8.7.4 Conventions for Using Exceptions at Different Software Layers...........................................................32
9 Standard Frameworks and Cookbooks........................................................................32

9.1 Business Process Control Classes....................................................................................................... 32
9.1.1 Standard Frameworks.......................................................................................................................... 32
9.1.2 Cookbook............................................................................................................................................. 32
9.2 Process Classes...................................................................................................................................... 32
9.2.2 Cookbook............................................................................................................................................. 33
9.3 Entity Classes.......................................................................................................................................... 33
9.3.2 Cookbook............................................................................................................................................. 33
9.4 Persistency Classes................................................................................................................................ 33
9.4.2 Cookbook............................................................................................................................................. 33
10
Appendix....................................................................................................................33
10.1
Target System of the Payment Engine Architecture.....................................................................33
10.1.1
Aims that Can Be Derived from the Application.............................................................................33
10.1.2
Aims that Can Be Derived from the Software Creation Process....................................................34
10.2
Basic Understanding of the Architecture......................................................................................35
10.2.1
Business Concept.......................................................................................................................... 35
11
Literature....................................................................................................................35
Page
1 Introduction
This document describes the architecture in the Payment Engine project from the point of view of the
concept and the technical software. The application architecture, that is, an overview of the technical
components, does not form part of the concept. The document describes in detail how technical components
are usually created, how the responsibilities are split between the parts of the components, and how the
components are integrated and work together.
The document is a working document that can be changed or added to by the author at any time as a result
of practical experience in the project. The latest version will be stored on the Banking server and the different
versions will be maintained in a CVS repository by the author.
Firstly, the document describes the conceptual architecture. At a general level, this defines the elements of
the architecture and the understanding of business applications on which the elements are based. Then the
different elements and layers are described in detail and cross-level global topics are also covered. The last
section deals with the progress from architecture to realization using "Cookbooks" and standard frameworks.
The concept is based on the document "Software Architecture in IBU Banking (BCA View)", version 0.4. This
is perhaps not evident at first, since the terminology used is sometimes different to the BCA terminology.
Section 2.3.1 contains a comparison and more detailed description. The document mentioned above can be
used as a cross-product guideline for the IBS FS and therefore some areas where the details are to be
created according to the requirements of specific products may not be covered in great detail. Topics such as
logs, standard headers, transaction control, and so on are therefore specified separately for the Payment
Engine in this document.
2 Conceptual Architecture
In this document, the term "Conceptual architecture" describes the software elements of the Payment Engine
(and some relevant operational systems) and its relationships. These are "abstract 1 objects and components
- the content of these objects and components are described here, but not the form of the program
technology.
2.1 Object Orientation

The architecture and realization of the Payment Engine are generally object-oriented. Unified Modeling
Language (UML) is used for the design and modeling, and ABAP is used for the implementation. A basic
knowledge of the concepts of object orientation is required to understand the following sections.
2.2 Collections
ABAP objects themselves is not provided with a standard library of collection classes (as is the case with
Java). Instead, it is possible to use internal tables as a way of replacing collections. The key definitions of the
internal tables can be used to determine whether an element in a collection may appear a number of times
(bag, vector) or only once (set).
2.3 Components
The Payment Engine is made up of a number of independent, technical components that cooperate with one
another to complete their tasks. Examples of such components are Payment Order Processing, Route
Processing, or Clearing Processing.
Components are larger functional units than classes. They consist of several classes and provide
persistence mechanisms. Internally, they are structured according to a uniform model.
1
"Abstract here does not mean "abstract in the sense of a class from which no instances may be created",
but "not exactly corresponding to runtime elements".
Page
The components are decoupled from each other and only communicate via defined interfaces (component
interfaces). In some cases, one component may have to access another component directly. One example is
the payment order component that has to access the other components in read and write mode. In this case,
a defined indirection within the calling component ensures that the payment order can be replaced by an
external system if necessary without affecting the other components.
Generally, the functions that a component provides are nuclear from a business view (see also section 10.2).
These functions are linked to a business process such as "Processing a tape with a large number of
payment items" or " Direct processing of a payment order for a cash machine" in a dedicated component
responsible for linking individual business steps in a process. In addition, this component, called BPC (for
Business Process Control; see section 4), is also responsible for the type of coupling of other components
(direct sequential method access, workflow, pipes and filters with load distribution over several process
instances,...). It can be delivered with the core Payment Engine or created specifically for the requirements of
individual customers within an implementation project.
The components presented here correspond to the SAP Business Object. In exactly the same way as the
SAP business objects, the components are completely responsible for ensuring internal consistency and for
persistence (storage in a database).
2.3.1 Structure of Components: Internal Layer Model

The Payment Engine components always have the same structure. This aids recognition and simple
enhancement and maintenance of components.
The interface that the outside world uses to access the components consists of a number of methods from
one or more Process Classes. These represent business-nuclear operations (see section 3 for a definition of
process classes and section 10.2 for a technical, theoretical background). Process classes are responsible
for ensuring that all technical objects managed by its components (open collectors during clearing, payment
orders in payment order management) have the correct business status, and not just individual objects.
Example: For a payment order, the process classes are responsible for ensuring that as well as the payment
items, the payment order itself has the correct status. The process classes use the functions programmed for
the entity classes (see section 6).
Entity classes represent the business objects of payment transactions. They are encapsulated by process
classes from the outside world and are integrated with one another more closely than the process classes by
means of relationships. They do not contain any logic for storing the object status through their lifetime until
runtime, but use persistency classes instead (see section 7). Objects from entity classes ensure their own
internal consistency, but not the consistency between them and objects from other entity classes (the
methods of the process classes are responsible for this).
Persistency classes contain the access to the persistency mechanisms (database; theoretically, systems
such as MQSeries are also possible) that save the status of the objects over their lifetime in the main
memory. Lock management is also situated here, as well as a database table-related buffer mechanisms.
The following generally applies:
Database tables are always the responsibility of exactly one component and are written and read
exclusively by persistency methods of the owner component. Exception: Customizing tables.
Persistency objects are accessed exclusively by entity objects of their own component.
Entity objects are accessed by methods of process objects of their own component.
Process object methods are accessed by component-internal or component-external methods and

represent the external interfaces of the component.
Customizing tables are combined in a central component and can be read by all components that need the
settings made there.
Graphically, you can portray a component as follows:
Page
Representation of a component
External access
Component
Process
Classes
Process
Object
Entity
Classes
Entity
Object
Persistency
Classes
Persistency
Object
Process
Object
Process
Object
Entity
Object
Entity
Object
Persistency
Object
Entity
Object
Entity
Object
Persistency
Object
Database
SAP AG 2001, Title of Presentation, Speaker Name 2
Note that this layer structure corresponds considerably to the layer structure of the BCA in the document
"Software Architecture in IBU Banking (BCA View)" version 0.4, from a content view if not from a terminology
view. The terminology used for the Payment Engine here is described in section 5.2 of the above-mentioned
document (process and entity classes).
The following table compares the component layers of the Payment Engine to the layer architecture of the
BCA:
BCA Layer Architecture
Payment Engine-Component Layer
MAPI layer
Public methods of the process classes
API layer
Public methods of the entity classes
Object layer
Private methods of process, entity, and persistency

classes (no direct equivalent in the form of a layer).
The buffering of technical objects that transfer the
object layer is done by buffering entity classes.
DB layer
Public methods of persistency classes
From the above table, you can see that the difference between the layer structure of the BCA architecture
and the Payment Engine architecture is primarily one of terminology. One main difference however is that the
BCA architecture permits an external access to the API layer, whereas the Payment Engine architecture
does not permit external access to entity classes. The reason for this is the strict separation of tasks between
the methods of the process class and the methods of the entity class (see sections 3 and 6). Further
differences arise from the use of the Business Data Toolset (BDT) in BCA, but not in the Payment Engine.
The object term on which the BCA architecture concept is based is oriented on the SAP business object that
is responsible for communication with the outside world and for ensuring internal and external consistency
and persistence. These are generally units that are larger than programmable technical objects and
correspond more to components. In the concept described in this document, "objects" are technical software
units (frequently in fine detail); the corresponding abstract level in the Payment Engine is the component
(see also [Szyperski97] and [HerzumSims00]).
2.3.2 Coupling of Components
Page
One aim of using a component architecture is the exchangeability of components with other components that
have the same functions. In practice however, this is not possible without additional effort, since the similar
external components in the business functions only very rarely have exactly identical interfaces. You can,
however, make the exchangeability easier by using specific additional encapsulation measures.
One such measure is that the components access each other directly as little as possible and that functions
are summarized via a superordinate independent component. This independent component is called
Business Process Control (see section 4). The process methods then only represent the individual steps of a
superordinate transaction and can be combined to create new transactions without modifying the
components.
The independent component can ensure the coupling via various mechanisms, dependent on the
requirements of the individual customer. The customer can use standard SAP mechanisms or implement the
independent component himself as part of an implementation project.
In some cases, however, direct access from one component to another without using independent
components is useful. One example is the component "Payment Order Processing. It is useful to access
process methods of "Payment Order Processing" directly from subsequent components such as "Route
Processing" or "Clearing Processing" in order to post and read payment orders. However, even here, the
access is exclusively to the methods of the process class and not to methods of the entity class or
persistency class or directly to database tables of the payment order. Special classes are defined for this
case. These special classes generate the instances of the process class of the component "Payment Order
Processing" for the using component. Here, you can also use "Proxies" instead of direct process objects so
that you can connect an external system instead of the SAP payment order component if necessary. See
also section 8.4.2.
When accessing external components (SAP or non-SAP components) it is not usually possible to work in a
LUW. In such scenarios you need to analyze how the connection to the external components should be
made:
Synchronous versus asynchronous
Safety requirements (guaranteed message delivery)
Mechanisms for recognizing and tracing errors (logging, restart)
SAP technology (RFC, tRFC, qRFC, IDOC, XI, ) or non-SAP technology (MQSeries, CORBA, )
The decisions made will be specified in the design of the connection proxy for each connection of external
components.
The following two figures show the procedure for direct access to other process classes and for using
external components.
Page
Access to external components I:

Other Payment Engine components
Factory
s_instance
P-object in
external
component
getReference
doSomething
Client object
Access to external components II:

Non-Payment Engine components
Factory
s_instance
Proxy for
access to
external
system
getReference
doSomething
doSomething
External
system
Client object
3 Basics of the Structures of Methods and Classes

3.1 Basic Properties of Classes
Classes appear in two forms in the Payment Engine: Singletons and Multi-instance classes. Singletons are
classes with a maximum of one instance and which typically have no status. Examples are the persistency
classes (section 7), typical process classes (section 5) and business process control classes (section 4).
Page
Multi-instance classes are "classic" classes of which there can be more than one object. Examples are entity
classes (section 6) and atypical process classes (section 5).
All classes have an "s_instance" class method that is responsible for creating instances from the classexternal view. You are not permitted to access a constructor from outside a class. You always specify a
business key for the object to be created for the "s_instance" method.
For singletons, the "s_instance" method follows the classic pattern [Gamma+95]:
:
SingletonClass
: Client
s_instance( )
theInstance :
SingletonClass
[no instance available] constructor
[no instance available] storeRef

returnInstanceRef
method1( )
method2( )
For multi-instance classes, there is a reference table at class level. This table contains the object reference
for each business key. The "s_instance" method checks this table to determine whether the object with the
transferred business key already exists in the main memory. If it does, the reference is returned. If the key
does not exist in the main memory, an instance is created, stored in the reference table, and the reference is
returned.
This means that if two different objects access an object of a multi-instance class with the same business
key, both receive the same reference returned, provided they are running in the same work process. You
want this to happen since, within the work process, no competing parallel access can occur. The classic
problem of having several instances of "Customer 4711" in the memory of one work process does not occur.
Page
:
MultiInstanceClass
: Client
anInstance :
MultiInstanceClass
s_instance( )
lookupInTable( )
[instance found] returnRef
[instance not found] constructor

instanceReference
storeInstanceInTable( )
returnRef
method1( )
method2( )
These two procedures ensure that references to all objects can be found again centrally. This is, for example,
important for main memory synchronization.
3.2 Basic Properties of Methods

The following basic properties apply for all public methods of process classes, entity classes, and
persistency classes. They are described in more detail for each of the layers in the following sections and
converted via standard frameworks in the form of code in section 8.6.
All public methods at one level (process classes, entity classes, persistency classes) basically have the
same structure. The responsibility for the selected technical topics (see section 8) always lies at the same
points within the software architecture. Direct access to the standard header (see section 8) is never
permitted - central technical services must be used; for example, you are not permitted to implement your
own transaction handling (ABAP commands "commit work", "rollback work ).
Private methods only provide help functions. They are used to structure the coding and are subject to less
strict requirements regarding the formal structure. Central technical functions, as described in section 8, are
not to be stored in private methods but in places where they are expected according to the standard
framework of the method types. Private methods should only be used in the context of the business logic
areas of methods (unless the standard framework explicitly states otherwise). They should therefore only
contain parts of the business logic.
Page
10
4 Business Process Control Classes

Component coupling was mentioned in section 2.3.2. The control component "Business Process Control
contains methods that correspond to subprocesses in ARIS-eEPCs. These methods access one or more
methods of process classes sequentially. They represent the interface for the entire Payment Engine as an
application, in the same way as the role of the process classes for the individual components.
The methods of these classes are technically contained in themselves, but are not nuclear. That means, that
any changes you make in the database do not have to adhere to the all or nothing principle. For example, it
is possible to conceive a method that reads a payment order from a tape and saves this in the Payment
Engine. If one of the possible hundred thousand payment items had errors, a rollback would not be triggered
and the other, correct payment items would be deleted from the database 2; the logic would be different (for
example, logging of payment items with errors and notifying a supervisor).
Business process control classes have no status. They have no technical status that they save for all method
executions. It may, however, be useful to save references to instances of process classes intermittently.
The methods of the business process control classes are the basis for parallelization in the Payment Engine.
The highest level of the business process control classes (that is called up externally, not by other business
process control classes) is responsible for parallelization.
4.1 Properties of Business Process Control Classes

All business process control classes have the same properties, as follows:
They are singletons, that is, there must be only one instance of each class. For details, see
section 5.
They have a class method "s_instance" that returns a reference to the singleton.
They have a class method "s_memory_synch" that is used for main memory synchronization (see
section 8.4).
They only access their own methods (if a business process of a higher rank is a summarization of
subprocesses) and methods of process classes.
A business process control class is always completely responsible for one business process.
Examples would be a class for the mass processing of payment orders (reading and processing
tape) or a class for quick individual access (online scenario with customers at cash machines). The
business process control classes always have a public method that starts the processing of the
complete process and possibly also private methods that are responsible for subsections of the
business process.
Each business process control class decides from the technical and subject context for which it is
defined, whether and how transaction control takes place. Options are one transaction for a
complete business process (useful for individual processing) or a commit/rollback after
subprocesses (private methods) for mass processing.
4.2 Properties of Methods for Business Process Control Classes

The methods of business process control classes have the following responsibilities and properties:
They ensure that the standard header is filled correctly before the first process method is accessed.
This means that they initialize some fields, derive other fields from general conditions, and so on.
They decide the type of transaction control as described above.
Independently of this, the rollback segment of most databases would overflow with such large quantities of
data; for this reason alone packaging is necessary.
Page
11
5 Process Classes
Process classes are the technical software equivalent of collections of business process activities that
belong together. They provide the component interface for the outside world: If you want to use a component
of the Payment Engine, you have to do this by using process classes, since each access to business objects
takes place as part of a business process (see 10.2 for a basic overview).
Process classes summarize several process methods that belong together from a technical view. The
following can be used as criteria to judge whether methods belong together:
Sequence within a process: Example: All methods that you need when you read a payment order
(save payment order in status "Not completed", add payment items, close payment order).
Standard accesses to an entity class, particularly read accesses that are always required by different
components. Example: Read payment items, read accompanying sheet.
A typical characteristic of a process class is that it has no status that persists over the life of the software
object. This means that the process classes do not write their own attribute to the database3. However, they
are not necessarily without status in the sense that they have no attributes. References to entity objects can
also be held for the duration of the method execution if this is useful from a performance point of view.
If it is necessary for process classes to save a status in the main memory for longer than the lifetime of the
process class, you can either connect a workflow or build entity classes that represent the process as a
business object and so trigger the persistence of the necessary information in the database layer.
Due to the fact that the process objects have no status with regard to their technical functions and save the
references to the entity objects within a process, it makes sense to permit only one instance of a process
class for each user. Basically, you can either define all methods of process objects as class methods, or use
a "singleton pattern". Class methods have the disadvantage that they cannot be overwritten in subclasses in
ABAP objects, or rather, that in subclasses, the methods of superclasses cannot be accessed using
"subclass name => method name" (the user must know the inheritance structure and use "superclass =>
method name. This should be avoided from the view of object orientation). Instance methods can be
overwritten. Process objects are therefore implemented as singletons as standard. This enables you to
create inheritance structures in the process class area as well. It also enables you to manage several
instances of process classes should such a need arise.
5.1 Properties of Process Classes

Process classes have the following properties:
Process classes have a class method "s_instance" that returns a reference to the singleton if the
process class is realized as a singleton. See also the description of the singleton pattern in
[Gamma+95] and section 3.1. If the process class is not realized as a singleton, the "s_instance"
method searches for a reference and if necessary, uses a constructor access to create a new
instance and defines a reference to the instance in the global reference table in the same way as
entity classes (see section 6).
The constructor of process classes must not be accessed from outside the class.
Process classes that are not implemented as singletons have a global table that contains a
temporary access key for the instance (sequential number, GUID, or similar) that is the technical key
for the instance, plus a reference to the instance for which the technical key is valid. If the global
table is accessed from outside, the "s_instance" method checks whether an instance already exists
for the technical key transferred for the method. If this is the case, the reference is returned. If this is
not the case, a new instance is created, defined in the global table, and its reference is returned to
the initiator.
They have a class method s_memory_synch that is responsible for main memory synchronization.
Naturally, they trigger the writing of attributes of entity classes to the database by accessing the
corresponding entity class methods.
Page
12
They have a class constructor that registers the method s_memory_synch as the event handler for
main memory synchronization (see section 8.4).
5.2 Methods of Process Classes

The methods of the process classes have the following responsibilities:
Executing transaction control after the execution of the technical logic if they are the owner of the
transaction; see section 8.2.
Ensuring that all entity objects changed by the methods of the class are consistent. If you have to
reset the status of an entity object here, you can do this by using the reset method, which enables a
clean, encapsulated history function.
Methods of process classes can be defined with a BAPI wrapper and can be released as BAPIs for
use by (SAP internal and external) external systems. BAPIs of the Payment Engine always map to
methods of process or BPC classes.
5.3 Using Process Classes

A client who wants to access the process classes of a component must first obtain a reference to a process
object. This is not done by accessing the constructor but by accessing the class method "s_instance", which
returns a reference to the instance of the process class. Once this access has been executed, the client can
then access the actual process methods via the reference.
The following graphic explains the connections4:
: Client
:
ProcessClass
s_instance( )
provides reference
theInstance :
ProcessClass
[first access to class] constructor

provides reference to singleton
method( )
Strictly speaking, the constructor is a class method, but to explain it more clearly here, the arrow points to
the instance.
Page
13
6 Entity Classes
Entity classes correspond to business objects in the real world. The individual entity objects always
correspond to exactly one form of such a business object. This means that here, in contrast to the process
classes, it does not make sense to reflect the functions of an entity object via class methods or via a
singleton. Within payment order processing, for example, several payment items are processed
simultaneously. Therefore the "classic" object-oriented procedure of instance methods is used here with
several permitted instances.
The criterion for the definition of entity classes is that they reflect concrete or abstract concepts from the real
world. They therefore correspond more to the "classic" objects from object orientation than the process
classes.
It is important here that each business object, that is, each payment item, must only be created once as an
instance in the memory of a role area. Thus, several payment orders can be managed simultaneously, but
for each payment order "4711", there must always be only one software object. This is guaranteed by locking
the constructor and by using an "s_instance" class method.
6.1 Properties of Entity Classes

Entity classes have the following properties:
They generally have extensive attribute lists. These are always private. "Public attributes are not
permitted. "Protected attributes should only be used in justifiable cases. The aim must be to
decouple the classes within an inheritance hierarchy as much as possible.
The attributes of an object are not created individually, but rather as single attributes of a structure
type.
They are generally not singletons (see above).
An internal table is managed as the class attribute at class level. All objects previously created are
defined in this table with their business key and reference. This table is used by the "s_instance" and
s_memory_synch class methods (see below).
6.2 Methods of Entity Classes

The constructor, or the "s_instance" method of entity classes, has the following properties:
You are not permitted to access the constructor from outside. This is established in a special setting
in the Properties tabstrip of the class.
Instead, in the same way as for process classes, an "s_instance" class method that delivers a
reference to an entity object is provided. To do this, the method receives the business key of the
object that it is to provide and uses it to check whether the entity object being accessed exists. If this
is the case, the reference defined in the class attribute table is returned. If this is not the case, the
constructor is accessed with the business key.
The "s_instance" method receives a parameter that specifies whether the entity object is to be
accessed in read or write mode (including creation and deletion). This is required for lock
management and defined in an instance attribute for the entity object. It is then checked if methods
change. The process method is responsible for selecting the mode that the entity object requires. If
the entity object is accessed via "s_instance" by a process object that the first process object of the
business process does not recognize, and a stricter lock is set, the entity object tries to set the strict
lock (using a "reload" from the persistency object). If this attempt is successful, the stricter lock then
exists for all users, since there is only one instance of the same entity object (the payment order
"4711") in the memory of a work process.
The general methods of the entity classes have the following properties:
They are not responsible for transaction handling. The process classes (or an even higher level) are
responsible for transaction handling.
Page
14
For each form of persistence (read, insert, update, delete), they access the methods of the
persistence classes; that is, they do not access the database in any way.
7 Persistency Classes
Persistency classes provide the access mechanisms of the persistent attributes of the entity classes in
relational database tables.
Persistency classes each map onto specific entity classes. They each facilitate the persistence of an entity
class that requires this. It is, however, also possible that there are entity classes that do not have to be saved
persistently because they only have a temporary character during the execution of a process. An example of
this is classes that represent technical objects that are in other systems (current account systems).
Persistency classes have the following properties:
They store the information read from the database for access purposes.
Write accesses take place in the internal buffers until they are flushed to the database.
For each database table, there is an internal table with identical structures "at the front" at class
level. This table is managed by the persistency class. It is used as a buffer mechanism. In addition to
the attributes of the database table(s), a substructure is included which includes technical
management information of the persistency class. For example, indicators of the type of locks
(previously) set, possible "dirty" flags, or similar.
There is exactly one instance of each persistency class (singleton).

Inheritance mechanisms are not used for persistency classes. You could therefore also work with
class methods. However, for consistency and uniformity, the singleton pattern with the "s_instance"
method is used. This ensures a uniform object creation behaviour in all component layers (principle
of "minimal surprise" for the developers).
The initial access to the database (when creating an entity object) takes place via the technical key
attributes.
Locks from the enqueue process are only requested in persistency classes.
The methods of persistency classes have the following properties:
When changes are made to data records that are stored in the internal table, the system first checks
which lock was requested for the data record. If necessary, a "stricter" lock will be requested. If
another process has already requested a write lock for the object, an error is triggered.
The input parameter for the read method has the business key attribute of the entity class plus a
GUID and an indicator as to whether a read, a write/read, or no lock is to be requested.
In the first step, the system checks whether the data record already exists in the internal table. If it
does, it is returned from here. If the entity object requests a stricter lock than the one set, the system
tries to create a relevant enqueue order. If this attempt is successful, the lock indicator in the internal
table is updated.
If the business key attributes are filled and the system does not find the data record in the internal
table, the SQL access is carried out via the filled attribute(s). If the business key attributes are filled,
the system searches using the business attributes.
The insert method first checks whether a data record with the relevant business key already exists in
the ITAB. If this is the case, an error is triggered. If no error occurred, a GUID is created for the new
data record. The system then tries to create a write lock for the data record. If this attempt is not
successful, an error is triggered. In a third step, the data record is written to the database. In the
case of an error (typically because there is a unique index to the technical key which is being
violated), an error is triggered. If the procedure is successful (no error up to this point), the data
record is written to the internal table. The insert into the database table happens if the corresponding
event is triggered; see section ???.
The update method first checks whether the data record is defined in the internal table. If it is not, a
write lock is requested. If this is not successful, an error is forwarded to the caller. If on the other
Page
15
hand, this request is successful, the data record is read and placed in the internal table. Then the
update to the internal table is executed.
The delete method first checks whether the object to be deleted is defined in the internal table. If this
is not the case, an error is triggered. Reason: Deletion should only take place as part of the technical
deletion of an entity object. To do this, you have to access an instance method of the entity object. In
order for the instance to be deleted to exist, you must have accessed the constructor. To be
successful, the constructor must have read the attributes of the instance via the persistency class.
The object to be deleted should therefore normally be in the internal table.
If the method finds the object, it checks whether the lock has the required level (write lock). If this is
not the case, the system tries to raise the lock level. If this attempt is successful, the deletion in the
internal table is executed.
The following applies for all writing methods: The actual SQL access (and no other logic!) is packed in a
function module. Before the function module is accessed, the database method accesses the method
GET_FLG_UPDATE_TASK of the standard header. This results in an indicator that shows whether accesses
to write to the database should be made in the update task or locally. Dependent on this, the function module
containing the SQL command is accessed in the update task or without an update task.
8 Technical Topics
This section covers selected general technical topics. It provides a quick introduction to the basic technical
properties of the architecture.
8.1 The Standard Header

All methods have a central, mandatory IMPORT parameter, a reference to the Standard Header. This is
always passed on when you access stored methods, that is, from the access to a process method up to the
persistency layer and back, the same standard header instance is used.
The standard header is a technical container for transporting attributes that are used generally for managing
the system. You can access it only via dedicated methods. Direct access to the attributes is not permitted.
In the standard header you can only store technical information that is needed centrally. Business data is not
permitted here.
If you subsequently have to include global control attributes that were not considered in an earlier project
phase, you can do this by enhancing the standard header without changing the source code at the points
concerned. In this way you have increased flexibility for later changes to the basic design.
Examples of data transported in the standard header are:
The technical organizational unit.
User name if known. This can be provided externally if the user does not log on to the system
directly but creates the link to the R/3 system via a middleware and then holds the link open
centrally; in this case the name in SY-UNAME may no longer correspond with the user name.
Transaction control information. This tells the process method whether it is to execute the transaction
control itself or whether the caller of the process method does this (see section 8.2).
An indicator for whether database accesses occur in the update task.
Additional fields and attributes determined during the design of the central services.
8.2 Transaction Control

The transaction control takes place in either the process methods, the BPC methods or the external systems
(business process control independence; see section 2.3.2, or external systems that access the Payment
Engine via BAPI interfaces). Depending on the type of component coupling, it can be useful for process
methods to carry out the transaction control themselves (workflow connection or pipes and filters multiplexer
Page
16
coupling), or that the transaction control is carried out centrally as described above (obligatory if you use
BAPIs).
After processing the technical logic, all the process methods 5 access a method that handles the transaction
control. This is a method in the standard header. You can specify another parameter for this method - this
parameter indicates whether a rollback is necessary from the view of the process method (the process
method can determine this by evaluating the exceptions of the entity method and/or the error structures in
the standard header).
The transaction control method evaluates whether the process method is responsible for the transaction
control or not. The first method that declares itself responsible for the transaction control sets a
corresponding indicator in the standard header and notes the method name in a text field. If a process
method in which no method has declared itself responsible for the transaction control is accessed, the
process method takes over the transaction control, enters itself in the field and triggers a commit or a
rollback after the technical logic.
When a commit/rollback is triggered, all locks are removed by means of DEQUEUE_ALL. This happens in
the method provided by the Payment Engine which calls up the main memory initialization of the Tools &
Technology group (see section 8.4).
If a process method is to be accessed using a BAPI, the BAPI wrapper must enter an ID in the transaction
control field (for example, "BAPI", or the name of the BAPI wrapper module) and thus ensure that no
subsequent process method accessed takes over the transaction control. You can use this simple
mechanism to ensure that the BAPI program model is adhered to.
8.2.1 Implementation of Transaction Control in (Business) Process Control Methods

Transaction control takes place in two steps: a check step that contains the technical logic of the method and
that determines whether the method is responsible for control (see section 8.2.2); and a triggering step that
may initiate a commit/rollback (see section 8.2.3). The general process is as follows:
method whatever.
* Some data declaration etc. ...
data: l_taowner_flg type /pe1/dte_bpe_boolean.
call method i_rcl_standardheader->check_ta_control
exporting
i_ta_owner = <mymethodname>
receiving
r_caller_is_responsible = l_taowner_flg.
* Begin of business logic

*
* End of business logic
if l_taowner_flg = con_true.
call method i_rcl_standardheader->ta_control
exporting
i_ta_owner = <mymethodname>
i_rollback_flag = <true or false>.
endif.
endmethod.
Here, you should note that TA_CONTROL must also be accessed if the method is exited by triggering an
exception.
5
All process methods except for the "s_instance" class methods and private "help methods" used for better
source code structures.
Page
17
8.2.2 Check Method CHECK_TA_CONTROL

This method is accessed before the technical logic of the method. The input parameter is the name of the
calling method (this should be a combination of class name and method name to ensure that the name
remains unique). The method reacts as follows:
If the transaction control was already taken over by another method, this other method retains
control. The return parameter R_CALLER_IS_RESPONSIBLE has the value FALSE.
If the transaction control was already taken over by the same method (cyclical access; see
section 8.2.3), nothing is changed and the value FALSE is returned.
If transaction control is not yet filled, the content of the import parameter is entered in the control field
of the standard header and the value TRUE is returned.
The returned value R_CALLER_IS_RESPONSIBLE should be stored in a method-local variable (see

section 8.2.3).
8.2.3 Transaction Method TA_CONTROL

This method leads to either a commit or a rollback, depending on whether the rollback indicator is returned
as TRUE or FALSE. As a check parameter, this has the name of the method that calls it up (this must be
identical with the parameter that is transferred to the method CHECK_TA_CONTROL from section 8.2.2).
The method compares the name that is transferred to the name that is saved in the transaction control field.
If they are identical, a commit or a rollback is carried out, depending on the rollback indicator.
This comparison is a safety mechanism that prevents any other method triggering a commit or rollback, apart
from the one whose name has been entered in the control field. In most cases, this is sufficient. However, if
there are cyclical accesses (M1->M2->M1), the second access of the same method would take over
transaction control, not the method instance that originally filled the field! If a commit takes place in the
second method access, a rollback in the (surrounding) first method access would at least be partly ineffective
and could result in inconsistencies in the database.
For this reason, the return parameter R_CALLER_IS_RESPONSIBLE (see there) was incorporated into the
method CHECK_TA_CONTROL (see section 8.2.2). The method TA_CONTROL should only be accessed
if this return parameter has previously returned the value TRUE. The example coding in section 8.2.1
demonstrates this.
8.3 Logging
Parameters and error codes are logged using central modules. These are accessed at defined points in the
layers (see section 8.6).
The logging is controlled by various logging levels. These specify whether and to what extent logs are to be
created. They are defined centrally in Customizing. In the standard framework, you can set an (optional)
indicator that overwrites the indicator defined in Customizing. This can be used to specifically test individual
methods.
See also the design paper on the Payment Engine application log.
8.4 Main Memory Synchronization

Releasing the main memory is a potential problem with temporary storage (buffers) of data, either in global
tables such as in the persistency classes, or in the instances of classes such as in the entity classes. As
described in section 8.2, when the LUW ends, the locks are released. This means that from this moment, all
buffered data can be invalidated by access by third parties. You must therefore delete the buffered data. This
leads to the situation that all data has to be re-read, and new locks have to be requested. This ensures
cross-process synchronization.
The procedure used for this is the procedure defined by the "Tools & Technology" group for cleaning up the
main memory. At the time of a commit or rollback, there is a reaction to an event that basis has provided.
This signals the completion of an SAP LUW using a commit or rollback.
Page
18
In "typical" object-oriented systems, it is often difficult to reach all objects of a class. This problem does not
occur in this form in the Payment Engine. Each business process control class, process class, entity class,
and persistency class has a "s_memory_synch" class method that acts differently in each of the different
classes. This global memory clean up function works as follows for the different levels:
1. There is a maximum of one instance of the business process control or process classes. The
reference for this instance is defined in a class variable (singleton pattern). After the instances of the
business process control have been deleted, this is the only reference to the instance. An
"s_memory_synch" class method initializes this reference; the garbage collector takes care of the
rest.
2. After the first two steps, there are no further references to entity objects outside of the entity layer.
The "s_memory_synch" method of the entity classes deletes the global (class) reference table where
the references to the technical key are stored (see section 6). The entity objects can no longer be
reached from outside and the garbage collector deletes them.
3. The persistency objects are singletons, just like the process objects. However, these do not have to
be deleted. Since the buffering takes place exclusively in class tables (see section 7), it is sufficient
to initialize them using the "s_memory_synch" method in order to "reset" the classes. You can retain
the instance of the process class.
8.4.1 Standard memory synchronisation behaviour

For standard business-oriented classes the following behaviour is the standard behaviour. For exceptions
and how to handle them see section 8.7.
The functions for main memory synchronization are implemented as follows:
There is a central class /pe1/cl_bpe_memory_synch that triggers main memory synchronization. At

the end of a SAP-LUW, the basis triggers the event TRANSACTION_FINISHED of class
CL_SYSTEM_TRANSACTION_STATE. Method ON_AFTER_TRANSACTION_END of
class/PE1/CL_BPE_MEMORY_SYNCH receives this event and reacts to it.
First, any blocks set by the database methods are removed (using dequeue_all).
Then, an internal Payment Engine event is triggered that also has the name
TRANSACTION_FINISHED.
A Payment Engine-specific event is triggered because the name and class of the basis event
changed between releases 4.6C and 6.10. The additional encapsulation protects the Payment
Engine from any future changes.
The classes of the Payment Engine use class methods that react to the event mentioned above.
These bear the name s_memory_synch and have the following properties:
They are private class methods.
They are defined as event handlers for the event TRANSACTION_FINISHED of class
/PE1/CL_BPE_MEMORY_SYNCH.
They delete the buffer mechanisms of the relevant class. For singletons, the class-global
instance reference is deleted. For multi-instance classes, the internal reference table is
deleted6. For database classes, the database buffer is also deleted 7.
The methods s_memory_synch must also be registered for definition as event handlers. For this, a
class constructor is defined in all classes which takes carries out this registration. For example:
method class_constructor.
set handler s_memory_synch.
endmethod.
See also section 8.4.3 for an alternative to reference table deletion.
For singletons with no status, you can consider whether the instance reference should be deleted or kept.
Page
19
8.4.2 Memory synchronisation without reference deletion

Creating objects and deleting the references to them will sooner or later result in the garbage collector being
activated. This is especially likely in the case of big payment orders, with hundreds of thousands of payment
items.
For classes for which a lot of objects will have to be created and discarded, an alternative way of memory
handling can be used. Here, the objects are created but never deleted. In order to achieve this, the reference
table is never deleted; therefore the garbage collector cannot free the memory of the instances.
This recycling of object instances is relevant for the case of large files, where loops over packages of orders
and / or items are necessary. The maximum number of objects is determined by the package size of the
business process. After each loop iteration, the business process has to commit, forgetting all objects (from
a business point-of-view).
In order to implement such a logic, the following changes to the instance management methods (s_instance,
constructor, s_memory_synch) and the reference tables will have to be done:
The reference table contains a field flg_instance_in_use. This flag is TRUE if the reference to the
instance is used. In this case the business key must be filled as well. If the instance is not used, the
business key is to be cleared and the flag contains the value FALSE.
The constructor is empty (except for possible calls to super->constructor). The logic for the
initialisation of objects has to be callable directly from the s_instance-method, because if an instance
is to be recycled, the constructor cannot be called.
All initialisation logic resides in a method called constructor_logic. This protected method is part of
an inheritance hierarchy similar to the one in the constructor: each constructor_logic in a subclass
overrides the method from its superclass and has to call super->constructor_logic (plus whatever
local initialisation is required).
In the s_instance-method, if a new instance is required (because the business key of the object
was not found in s_reftab), the method differentiates between two cases:
The total number of instances in s_reftab is less than the package size from the BPC loop.
In this case, a new instance is created normally via create object and inserted into
s_reftab. The business key is entered normally, and the field flg_instance_in-use is set to
TRUE. Note: because the initialisation logic resides in constructor_logic, this method must
be called
The total number equals the package size of the BPC loop. This can only happen when a
second or later package is processed. Here, the method s_instance does not create a new
instance. Instead, it looks for an entry in s_reftab where the flag flg_instance_in_use is
FALSE. Note that the business key of this row of s_reftab will also be empty. The method
constructor_logic is called for this instance, and the business key filled as well. Then the
flag flg_instance_in_use is set to TRUE.
In the s_memory_synch-method, the reference table is not deleted. Instead, a loop is performed
over all the entries which does the following:
o
Clear the business key.
Keep the instance reference unchanged.
Set the flag flg_instance_in_use to FALSE.
Because the method s_instance will only access this line in s_reftab if it needs to create an
instance which is new from the business-point-of-view, and will call constructor_logic on the
instance, thereby initialising it, there is no need to clear the instance variables of the instances.
8.4.3 Memory synchronisation without buffer deletion for persistency classes

In some cases it makes sense not to delete the buffers of entity or persistency classes. An example are
system tables or customizing tables which rarely change. Other examples are entity classes which are
relatively expensive to create, and whose underlying data also rarely changes. However, detecting changes
Page
20
to the buffered data and handling locks are issues which have to be considered. This section provides some
hints on how to handle this. It is relevant mainly for the persistency layer, as most of the issues raised
concern database access, database locks etc.
The important thing to remember about not deleting the buffer is that all locks will have been released by the
time the S_MEMORY_SYNCH method is called. If the buffer is deleted, this is no problem. However, if the
buffer is to be retained and locks are needed, then the method S_MEMORY_SYNCH must ensure that the
locks are reacquired. To do so, the method has to loop over the internal table of buffered entries and call the
corresponding ENQUEUE function module for each entry with the lock level stored in the internal table. What
happens if this fails is dependent upon the context and has to be left to the class implementer.
8.4.3.1 Tables which never change
There are tables which never change during the runtime of the Payment Engine. These are system tables
which are shipped by SAP, and which are the basis upon that some of the coding is built. An example are
tables which define object types (payment item type, payment order type) or system tables defining the
payment item states and transitions.
In this case, it is save never to delete the buffer in the database classes. It is also not necessary to use locks.
Therefore the aforementioned problems will not arise.
8.4.3.2 Tables which rarely change, and where changes are not time-critical
Some tables, e.g. customising tables, change only rarely. Under the condition that changes to such a
customising table are not time-critical, i.e. that it is not a major problem if some work processes use the old
version of the table entries for a few minutes, the following scheme can be used.
If the table has been read in one select and then stored in the buffer of the persistency class, an additional
static, private attribute of the type timestamp will be added. If the table entries are read and stored in the
buffer individually, another column timestamp will be added to the internal buffering table.
In the timestamp field(s), the point in time of the filling of the buffer or the line in the buffer with the entry is
noted. If the method S_MEMORY_SYNCH is executed, it will check the timestamp(s) for entries which are
older than a specified amount of time. All those values are reread; the other values are treated as described
in section 8.4.2 (i.e. the locks are reacquired).
8.4.3.3 Tables where changes must be effective immediately
For such tables, there are basically two approaches imaginable:
Do not buffer them at all; do reads from the database instead.
Design a cross-workprocess or even cross-application-server approach. This will be detailed later.
8.5 Access to External Components

Direct access to the process classes of external components from your own process or entity objects is not
permitted. A factory class is set between the different components. This is part of the components that the
other components want to use (client components). A class that wants to access a process class of the other
component obtains the reference to this external process class via the factory class. There are two different
cases:
1. The external component is a Payment Engine component and may therefore be accessed directly. In
this case, the factory class gets a reference to the instance of the external process class by
accessing the "s_instance" method of the external component and then returns this to the caller. The
caller uses this reference for further access without indirection. The only additional overhead in
comparison to the direct access to the external process class is the one indirection when you first
access the process class.
Page
21
2. The external component is an not a Payment Engine component. In this case, the internal (client)
class assumes a defined behavior of the external partner (for example, the current account system).
This is modeled as a method in the object model of the Payment Engine. The factory class creates a
reference to a proxy whose interface corresponds to the object model. The proxy reflects the other
class8 to the client. From the client view, this behavior is exactly as described in the point above; the
difference is not visible for the client. The proxy passes the request on to the person responsible.
Mapping can also be carried out here. The proxy can also be realized via XI.
The following diagram shows how the classes named are connected as an object model:
Client class
Factory
gets reference
+ getExternalRef()
programs against
External process class

+ business method 1()
+ s_instance()
<<external PE component>>
PE Class
External application
Proxy
maps to
+ business method X()

+ business method Y()
The variant where the factory class accesses the component-external process class that is in the PE system
works as follows:
This does not have to be a class in the sense of object orientation, it can also be a wrapper of function
modules.
Page
22
: Client class
: Factory
: External process
class
getExternalRef( )
s_instance( )
reference
reference
business method 1...

The case where an application is used outside of the Payment Engine is as follows:
: Client class
: Factory
: Proxy
: External
application
getExternalRef( )
s_instance( )
reference
reference
business method X...

business method Y...
In contrast to the other sequence diagram, you can see that from the client class view, the logic has not
changed. An additional indirection is applied for the execution of the technical methods. The factory class
controls whether a proxy or a process object is created.
Page
23
8.6 BAPI Wrapper

You can wrap methods of the business process control level or the process layer released for access by
external systems with a BAPI shell. The BAPI shell is responsible for:
Filling the standard header. The S_INSTANCE-method of the standard header is accessed and this
creates a corresponding object from a transferred structure using the attributes of the standard
header.
Transaction control: Create the standard header such that the BAPI shell declares itself responsible
for the transaction control (by filling the corresponding field in the standard header; see section 8.1).
Preparation of messages that exist in the standard header in the form of an internal table of
BAPIRET2 structures. This structure can also be passed on to the caller.
Obtaining an instance of the business process control or the process class by accessing the
"s_instance" class method.
Accessing the business method.
Providing customer exits (BadIs) which deal with customer extensions to import and export
parameters (ExtensionIn, ExtensionOut).
SAP plans to create a standard framework and a cookbook for the BAPI wrappers.
8.7 Error Handling

Error handling in the Payment Engine is based on the error (exception) classes of ABAP objects as of
Release 6.10. In addition, an exception hierarchy has been created for the Payment Engine. In the
application logic, you can control how the system reacts to errors. For more details, see below.
8.7.1 Exception Hierarchy

The exceptions in the Payment Engine are based on the static exceptions that the ABAP objects provide.
This means that all exceptions that can be triggered in the Payment Engine are derived from the exception
CX_STATIC_CHECK.
To enable the central handling of all errors that might occur in the Payment Engine, there is a rule that all
error classes in the Payment Engine are collected in one hierarchy under the central class CX_PE_ERROR.
Here, additional properties of all exceptions in the Payment Engine are defined. To achieve a better
structure, additional abstract classes are given under these classes that organize the errors which were
actually triggered in thematic groups. The inheritance hierarchy of the Payment Engine therefore looks as
follows:
Page
24
CX_ROOT
Classes from the

ABAP Objects
Exception hierarchy
CX_STATIC_CHECK
CX_PE_ERROR
+ classname
+ methodname
+ errorlevel
+ exception
CX_PE_<Component>_ERROR
CX_PE_<Component>_SpecificError
Top-Level
Exception of the
Payment Engine
CX_PE_<Component>_ERROR
Additional attributes that are inherited by all subclasses are defined in the class CX_PE_ERROR. These
attributes are:
Classname: The name of the class in which the exception occurred is stored here. In CX_ROOT, a
mechanism is defined that specifies the include in which the exception occurred; however, a
descriptive class name is often useful.
Methodname: The name given under class name.
Errorlevel: This variable is filled with the values that are also used for the classic ABAP messages to
determine the error level (E, A, W, X, I, S).
Exception: This variable can be filled if an exception was triggered after the variable SY-SUBRC was
not equal to 0. This means that the exact cause of the error can be more easily determined and it
allows an exact diagnosis in connection with the class name and method name.
The fields mentioned may be filled by the users if they build an exception into their coding using the
Template button.
8.7.2 Reactions to Exceptions

If a method that is accessed by another method triggers an exception and sends this to the initiator, the
initiator can react to the exception in five different ways. These five alternatives, which may all be correct
depending on the context, are described in detail below.
To be able to understand the alternatives better, you must be aware that exceptions in ABAP objects can be
linked to each other. It is possible to catch an exception, create a new one and then hang the original
(caught) exception behind the second (created) one. For this, each exception has an attribute previous. If
this attribute is filled with a reference to another exception (at RAISE EXCEPTION), you can create a linked
list. For example, if a component in the persistency layer causes a database error and the initiating method
of the entity layer catches this and hangs it after a technical exception, you would have the following
situation:
Page
25
Chain of exceptions
Entity LayerException
DB-Exception
previous
Reference to another exception, forming

a linked list. Can be queried and navigated along.
This mechanism can be used to create an entire chain of cause and effect. How and when this occurs is
described in the following subsections:
8.7.2.1 Catching and Ignoring an Exception
Sometimes it can be useful to catch an exception from a subordinate software layer and ignore it. This would
mean that the exception had no further consequences: It would not be propagated upwards (caught there)
and no further exceptions are forwarded to the initiator. For example: A database exception not found can
be ignored by an entity method if this simply executes an internal check for existence in the database and if
the non-existence does not represent an error from a business process point of view. In this case, not found
would not be sent to the initiator after the reaction had been processed.
Graphically, this can be shown as follows:
Page
26
Suppressing an exception
Called method:
Current method:
Exception
Catching the exception
(nothing)
Coding example:
TRY.
do something that might result in an exception being thrown
CATCH cx_pe_error.
do nothing here
ENDTRY.
8.7.2.2 Sending the Exception Directly to the Initiator by not Catching It

It is possible not to react to an exception at all. In this case, when an exception occurs in a method that is
accessed, the accessing method is interrupted and the exception is sent directly to the previous method. For
this, the exception must be declared in the method signature of the method that it is not processing but that it
forwards9.
This procedure is useful if a method is not capable of reacting to the error in such a way that further
processing is possible, or if it is not possible to treat the error in an orderly manner. Examples of this are
standard header errors that occur when the fields of the standard header are filled incorrectly in the initiator
of a process method or business process control method, or all system errors that cannot be rectified by the
Payment Engine. This procedure cannot be used if a reaction of any kind is needed (for example, via
transaction control). The implicit assumption that, for example, a rollback is triggered at the initiator when
leaving the process method may prove to be false!
Otherwise, you get a warning. Non-declaration makes it significantly more difficult for a user to work with a
method. For this reason you should not ignore the warning.
Page
27
Ignoring an exception
Called method:
Current method:
Exception
Doing nothing
Exception

WITHOUT enclosing try-catch-endtry
8.7.2.3 Processing the Exception and Sending to the Initiator

In this variant, when an error occurs, the method responds by catching the exception, reacting to it and then
forwarding the caught exception. For this, the exception must also be declared in the signature of the
method. When the exception is caught, you should bear in mind that you have to store the reference to the
caught exception in a local variable.
Process methods are a typical application area. If a technical error occurs in the entity classes, this can often
be forwarded to the initiator in the same form. However, before this, transaction control must be accessed so
that the error can be reacted to once the process method has transaction authority (for example, using a
rollback).
Page
28
Passing on an exception after reacting to it

Called method:
Current method:
Exception
Catching the exception; reacting in some way;

re-raising the same exception
Exception
DATA: l_rcl_cx_pe_error TYPE REF TO cx_pe_error. Reference to general PE exception

TRY.
CATCH cx_pe_error INTO l_rcl_cx_pe_error.
react in some way, and raise again:
RAISE EXCEPTION l_rcl_cx_pe_error.
ENDTRY.
8.7.2.4 Replacing a Chain of Exceptions with a Single New Exception

In this case an exception is caught and replaced by a new exception. If the exception that was caught was
linked to other exceptions, the whole chain is lost. This makes sense if the exact background information
before the exception is sent to the initiator is not of any interest to the initiator.
Example: A process method accesses a read method of an entity class. This leads to the technical error
object could not be read that is linked to the database exception not found. However, since the process
method simply checks for existence and the non-availability of the object only provides a warning, the chain
is replaced by a new technical exception in which the error level is set to warning.
Page
29
Replacing exception(s) with a new exception

Called method:
Current method:
Exception Old 2
Exception Old 1

raising a new exception
Exception New
TRY.
CATCH cx_pe_error.
do something, and raise a new exception
RAISE EXCEPTION cx_pe_my_own_exception.
ENDTRY.
8.7.2.5 Replacing the First Exception in a Chain with Another Exception

Here, a new exception is generated. The content of the field previous is copied from the old exception to
the field previous of the new exception. This means that the new exception receives the entire chain that
was linked to the old exception. Only the exception that occurred last is replaced.
This is useful if a technical error in a specific context is to be reinterpreted.
Page
30
Replacing the last exception with a new exception

Exception Old 2
Called method:
Current method:

raising a new exception; copying previous to the new exception
Exception New
Exception Old 1
Exception Old 1

TRY.
do something
RAISE EXCEPTION cx_pe_my_new_front_exception
EXPORTING
previous = l_rcl_cx_pe_error->previous.
ENDTRY.
8.7.2.6 Adding a New Exception to the Head of an Exception Chain

This is the usual case for error handling. An exception is caught, a new exception is generated in the method
that caught it and the previous exception, including all connected exceptions, is linked to this new exception.
The new exception is simply added before the exceptions that already exist and it describes the situation
from the view of the methods that caught the original exception (chain).
Example: An exception from the database layer not found is caught in the entity layer and interpreted
technically. For this, a new exception payment item does not exist is generated. The reference to the
original not found exception is written in the previous field of the technical exception that has just been
generated.
Page
31
Adding a new exception to a list of exceptions

Exception Old 2
Called method:
Current method:

raising a new exception; writing caught exception into previous
Exception New
Exception Old 1
Exception Old 2
Exception Old 1

TRY.
do something
RAISE EXCEPTION cx_pe_new_front_exception
EXPORTING
previous = l_rcl_cx_pe_error.
ENDTRY.
9 Standard Frameworks and Cookbooks

(Comment: This section may be stored in a Payment Engine-specific enhancement of the programming
guidelines)
9.1 Business Process Control Classes

9.1.1 Standard Frameworks
To be created.
9.1.2 Cookbook
To be created.
Page
32
9.2 Process Classes

To be created.
9.2.2 Cookbook
To be created.
9.3 Entity Classes

To be created.
9.3.2 Cookbook
To be created.
9.4 Persistency Classes

To be created.
9.4.2 Cookbook
To be created.
10
Appendix
In this appendix you can find additional sections that are not necessary for a general understanding of the
Payment Engine, but that provide interesting insights into the background information.
10.1Target System of the Payment Engine Architecture

The architecture of an IT system is always molded by business and technical requirements. Even if this is not
explicitly clear, such requirements are always implicitly present. In this section, the requirements for the
Payment Engine are explicitly presented so that later sections can look in detail at how these requirements
can be implemented.
The aims of a software system can be subdivided into those aims that are a result of the application that is to
be created and those aims that result from the software lifecycle, which also determines a series of
restrictions.
10.1.1Aims that Can Be Derived from the Application

These aims are:
Performance: The Payment Engine must be able to process large quantities of data quickly. In
addition to data processing, realtime access (internet scenario, cash machine, ) with acceptable
response times must also be possible.
Page
33
Solution: Buffering at different levels, retrieval of process variants for single and mass processing of
payment orders (this point is, however, part of the technical design).
Enhancement possibilities: Payment transaction systems are solutions that have to be able to be
integrated in different IT landscapes at the customer. For this reason, it is important to plan
mechanisms for customer enhancements.
Solution: BADIs in all process methods, proxies for access to external systems, loose coupling of
individual components.
Scalability and distribution: Due to the close integration of a payment transaction system in the IT
landscape, it is possible to imagine scenarios in which some of the functions of a Payment Engine
are distributed over different platforms, and it may be possible that parallel instances have to coexist.
Solution: Loose, flexible coupling of components in a customized business process control layer that
can be adjusted to the respective customer requirements; coupling of individual components using
proxies and factories which allow the distribution of different technical functions on different
platforms.
Exchangeability of partial systems: Many customers already have payment transaction systems and
may be planning to continue using their functions for specific payment transactions (for example,
payment method definition, clearing, ). This implies that the Payment Engine needs to consist of
several loosely connected modules..
Solution: Loose component coupling.
10.1.2Aims that Can Be Derived from the Software Creation Process

As well as the aims purely related to the application, the software creation process at SAP (SDLC documents
and supports in Horizon) makes additional demands on a system architecture:
Clear structuring of the application. This aim arises from the need to be able to integrate new
developers into the project quickly as it makes it easier for them to concentrate on the actual
technical aspects of their work. Clear structuring also supports the transfer of the project results to
the IBD and the subsequent maintenance of the application by the IBD.
Solution: Architecture without Layer Bridging, standard frameworks for method structure, clean
design (not a topic for this concept).
Standardized, strict procedures for cross-application topics. Amongst others, these topics include
transaction handling, the message concept and lock management. Decisions for these topics must
be made as early as possible during the project and in such a way that the consequences of
subsequent changes are minimized.
Solution: The use of standardized guidelines and standard headers for all levels of the software
architecture.
The possibility of making structural changes later at a justifiable cost. This aim is a result of the
prototype nature of development for the Payment Engine project. The purpose of the prototype is not
only to analyze the technical properties of the system and then be discontinued. Instead, it is to form
the basis of the first productive release. As a result, the architecture should be defined from the very
beginning so that new technical requirements can also be taken into account at a later date. An
example of this would be a requirement later in development that the user ID of the end user should
be sent to all methods of the Payment Engine if this is to be used via BAPIs.
Solution: Standard headers as containers for technical attributes that can be subsequently changed.
Compatibility with IBS and SAP architectures. This is necessary to be able to use the Payment
Engine together with other SAP applications such at the Interface Repository, Workflow, BCA or the
Financial Server.
Solution: Basing the layers on the general software layers of IBS FS, the use of central tools
wherever possible.
Simple handover to IBD. The handover of the project results from NAD to IBD is a crucial part of the
project and a prerequisite for its successful completion. In addition, effective support from the IBD is
a critical success factor for the product in the marketplace.
Solution: Standard structure of all methods (no surprises), precise documentation of all exceptions
(if they exist), standard frameworks, documentation of the design in the form of an object model (not
part of this concept).
Page
34
Integration of new employees. Due to the resource situation (within SAP and in the marketplace), it
is necessary to integrate new and (sometimes) external employees as quickly as possible. For this,
the new employees need to be able to concentrate on the technical logic; That is, the actual
complexity of the architecture with respect to technical topics should not concern them.
Solution: Standard frameworks and cookbooks, encapsulation of central technical topics.
10.2Basic Understanding of the Architecture

Behind every architecture, there is an implicit or explicit understanding of that which is depicted and in what
way it is depicted. In the procedure model Extreme Programming, there is even talk of a metaphor. In this
section, you can see the understanding of business applications in a technical context that forms the basis
for the architecture of the Payment Engine. This makes it easier to categorize and comprehend the details of
the different elements and layers of the architecture.
10.2.1Business Concept
An enterprise can be understood as a system that carries out processes related to a certain aim, and
therefore interacts with flows of money, goods and information in a business environment. A business
application is a representation in the form of an IT system of those aspects of this process (and the money,
goods and information it deals with) that are relevant to the management of the enterprise.
The IT system must reflect the business reality as closely as possible. Therefore, it makes sense to structure
the IT system in a similar way to the reality that is being depicted.
This results in the following requirements of the IT architecture:
Business objects: Abstract or concrete concepts in the real world that can be created, changed and
dismantled during business activity output. They are created, used and dismantled exclusively within
activities.
Activities: Fundamental, nuclear operations for business objects. An activity either alters all of the
business objects associated with it (success) or none (error).
Business processes: Chains of activities that are connected via events and that can branch to
parallel or alternative paths.
These elements can be found in all business process modeling techniques, such as ARIS for example.
The following table maps these elements to the components of the architecture:
Business Concept
Architectural Element
Business object
Object of an entity class
Activity
Method of a process class
Business process
Method of a class of the independent component
This architecture is based on the assumption that business objects are only accessed for the purpose of
carrying out business processes. The activities correspond to the ARIS activities at the highest level of detail
(granularity). The chains of activities that are represented by the methods of the independent component
would all be subprocesses (process paths) of ARIS.
11
Literature
[Gamma+95]
Gamma et al: Design Patterns. Elements of Reusable Object-Oriented Software.

Addison-Wesley, Reading / Massachusetts, 1995.
[Buschmann+96] Buschmann et al: Pattern-Oriented Software Architecture. A System of Patterns. Wiley,

Chichester, 1996.
Page
35
[Hofmeister+99]
Hofmeister et al: Applied Software Architecture. Addison-Wesley, Reading /

Massachusetts, 1999.
[Bass+98]
Bass et al: Software Architecture in Practice. Addison-Wesley, Reading /

Massachusetts, 1998.
[Brown00]
Brown, Alan W.: Large-Scale, Component-Based Development. Prentice Hall, Upper

Saddle River, 2000.
[HerzumSims00]
Herzum, Peter & Sims, Oliver: Business Component Factory. Wiley, New York, 2000.
[Szyperski97]
Szyperski, Clemens: Component Software. Beyond Object-Oriented Programming.

Addison-Wesley, Reading / Massachusetts, 1997.
Page
36

05 Architektur Payment Engine Eng

Uploaded by

Copyright:

Available Formats

05 Architektur Payment Engine Eng

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

05 Architektur Payment Engine Eng

Uploaded by

Copyright:

Available Formats

Jrg Wegener

IBS FS, NAD OS II

Payment Engine Software Architecture

Payment Engine Project

Payment Engine Software Architecture

3 Basics of the Structures of Methods and Classes........................................................8

4 Business Process Control Classes..............................................................................11

Payment Engine Software Architecture

9 Standard Frameworks and Cookbooks........................................................................32

Payment Engine Software Architecture

2.1 Object Orientation

Payment Engine Software Architecture

2.3.1 Structure of Components: Internal Layer Model

Process object methods are accessed by component-internal or component-external methods and

Payment Engine Software Architecture

SAP AG 2001, Title of Presentation, Speaker Name 2

Payment Engine-Component Layer

Public methods of the process classes

Public methods of the entity classes

Private methods of process, entity, and persistency

Public methods of persistency classes

2.3.2 Coupling of Components

Payment Engine Software Architecture

Synchronous versus asynchronous

Safety requirements (guaranteed message delivery)

Mechanisms for recognizing and tracing errors (logging, restart)

Payment Engine Software Architecture

Access to external components I:

SAP AG 2001, Title of Presentation, Speaker Name 10

Access to external components II:

SAP AG 2001, Title of Presentation, Speaker Name 11

3 Basics of the Structures of Methods and Classes

Payment Engine Software Architecture

[no instance available] constructor

[no instance available] storeRef

Payment Engine Software Architecture

[instance not found] constructor

3.2 Basic Properties of Methods

Payment Engine Software Architecture

4 Business Process Control Classes

4.1 Properties of Business Process Control Classes

4.2 Properties of Methods for Business Process Control Classes

They decide the type of transaction control as described above.

Payment Engine Software Architecture

5.1 Properties of Process Classes

Payment Engine Software Architecture

5.2 Methods of Process Classes

5.3 Using Process Classes

[first access to class] constructor

Payment Engine Software Architecture

6.1 Properties of Entity Classes

They are generally not singletons (see above).

6.2 Methods of Entity Classes

Payment Engine Software Architecture

There is exactly one instance of each persistency class (singleton).

The methods of persistency classes have the following properties:

Payment Engine Software Architecture

8.1 The Standard Header

The technical organizational unit.