Introduction
For introduction to ABAP Channels please refer to Introduction to ABAP Channels. For tangible examples in the system see also the blog ABAP Channels Examples. See also FAQ - ABAP Channels.
This blog focuses on the eventing framework for messages exchange between different ABAP sessions based on publish/subscribe channels,, also known as ABAP Messaging Channel (AMC).
For live demonstration and step-by-step implementation look at ABAP Messaging Channel Video.
Integration of Messaging Channels into the ABAP Engine
In order to pass an event from an ABAP session to another session we decided to implement a publish/subscribe infrastructure in the ABAP engine. Any ABAP session can subscribe to channels and any ABAP session can publish messages to channels. The channels can be used to exchange messages between sessions in an ABAP system containing several application servers, no matter on which application server these sessions reside. The ABAP Messaging Channel (AMC) brokers take care of the exchange of messages between application servers (see figure 2.0).
Figure 2.0: Simple interaction model of ABAP Messaging Channel
The following diagram (figure 2.1) shows the interaction model between AMC consumers and AMC producers in different ABAP sessions which are residing on different application servers. On top of the unidirectional communication also other communication patterns can be established, e.g. bidirectional communication. Furthermore a session can act simultaneously in both roles as AMC consumer and producer. The present ABAP Messaging Channels support only the best-effort quality of service of messaging but no reliable messaging such as exactly-once or exactly-once in order.
Figure 2.1: Exchange of messages based on ABAP Messaging Channel
The ABAP Messaging Channels support also the exchange of messages between ABAP sessions and WebSocket clients. This kind of communication is called “Collaborative” scenario. In order to reach this goal the ABAP Push Channel applications (see my blog on the ABAP Push Channel) are able to bind their WebSocket connection to ABAP Channels in a way, that the WebSocket client acts as consumer of AMC messages. This scenario is described in the dedicated blog “Collaborative Scenario”. Figure 2.2 illustrates a simple scenario for publishing a message, which is consumed by a WebSocket client.
Figure 2.2: Publishing AMC messages to a WebSocket client using ABAP Push Channel
Multicasting Granularity of ABAP Messaging Channels
The channels provide following possibilities to define/restrict the number of recipient of a message:
- The channel attribute “activity scope” describes the area to which the message is provided. The attribute can have the following values (see also next section):
- System: The producers and consumers reside in the same ABAP system. An example for such a channel is the system messages channel which is used to send messages from transaction SM02 to the active users in the system.
- Client: The producers and consumers reside in same client of the ABAP system. I other words the messages published in a client 100 can only be consumed by the session in the client 100.
- User: The producers and consumers running under the same user identity, i.e. same client and user id.
- A channel consists of three sections “<application name><channel id>[<channel extension id>]”:
- Application name: This section identifies the name space of the channel which contains the list of all channels that are maintained for this application.
- Channel ID: This section is used to maintain the scope and security attributes. This is used to identify the consumers of a message.
- Channel Extension ID (optional): This as extension to Channel ID is used to identify the consumers of a message. With this the application is able to restrict the number of recipients of a message at runtime.
Creating an ABAP Messaging Channel (AMC) Application
This section contains a step by step description of the creation of an ABAP Messaging Channel application.
An ABAP Messaging Channel (AMC) application can be created in two ways.
In transaction SE80 using the context menu entry ("Right-Click on top-level package object) "Create" -> "Connectivity" -> "ABAP Messaging Channel" (see figure 3.1):
Figure 3.1.
As of release 740 SP5: In the transaction SAMC using the context menu entry ("Right-Click") on the "ABAP Messaging Channel" entry and selecting "Create" (see figure 3.2):
Figure 3.2.
In the next step, enter the name of the AMC application and confirm the popup screens (press "Enter"). In this example "YAMC_TEST" is used as application name (see figure 3.3):
Figure 3.3.
Also choose an appropriate package entry, in this case as "Local Object" (see figure 3.4):
Figure 3.4.
Additionally, maintain the field "Description" (see figure 3.5):
Figure 3.5.
On the tab „Channels“ enter a channel name of your choice e.g. „/ping“ and click on this field. The „Channel“ name must begin with slash (/) (see figure 3.6):
Figure 3.6.
Then, fill the next fields:
- Message-Type ID : A dedicated message type is assigned to each channel. Only messages of the assigned message type can be transferred over the channel. Using message types, the access APIs are type safe and the ABAP compiler and ABAP runtime ensure the consistency. Currently, the following message types are provided with the corresponding ABAP types and the producer and receiver interfaces.
- Message type "TEXT":
- Corresponding ABAP type "STRING"
- Producer interface: IF_AMC_MESSAGE_PRODUCER_TEXT
- Receiver interface: IF_AMC_MESSAGE_RECEIVER_TEXT
- Message type "BINARY":
- Corresponding ABAP type "XSTRING"
- Producer interface: IF_AMC_MESSAGE_PRODUCER_BINARY
- Receiver interface: IF_AMC_MESSAGE_RECEIVER_BINARY
- Message type "PCP" for Push Channel Protocol:
- Corresponding ABAP interface "IF_AC_MESSAGE_TYPE_PCP"
- Producer interface: IF_AMC_MESSAGE_PRODUCER_PCP
- Receiver interface: IF_AMC_MESSAGE_RECEIVER_PCP
The construction of the Push Channel Protocol (PCP) is very similar to an HTTP message with (header) fields, i.e. field name/ field value pairs and a body with the exception that PCP does not contain any request/response line. Furthermore the field names are case-sensitive and in Unicode. The Body part is optional and can be either binary or text. A PCP object in ABAP is created via the class factory method CL_AC_MESSAGE_TYPE_PCP=>CREATE( ).
The PCP message type is the preferred message type used in the ABAP basis technology. This is because with the PCP messages not only application is able to add additional meta-data as field to the message but also the AMC runtime inserts per default the name of the channel to the PCP message before it is sent. This information is often necessary for the consumers which subscribe to different AMC channels. Using the channel field, i.e. “pcp-channel”, consumers can identify the channel to which the message belongs.
For this basic example we choose the message type TEXT by clicking on input help Message Type ID (see figure 3.7):
Figure 3.7.
Choose entry TEXT (see figure 3.8):
Figure 3.8.
- Activity Scope (System, Client or User): The channel access scope defines whether a channel is system-specific, i.e. cross-client, client-specific or user-specific. With client- and user-specific channel access scopes, the exchange of messages between producer and consumer sessions can be limited to sessions residing in the same client or sessions of the same user.
For this example select the entry Client (see figure 3.9):
Figure 3.9.
- Authorized Program: The access rights for the channels are realized via code based authorization. For each channel, and depending on the access role as consumer or producer, a white list of ABAP reports, function groups, classes has to be maintained otherwise the access will be rejected.
For the maintenance of the access rights of the AMC channels dedicated reports in the role of producer, i.e. sender, and consumer, i.e. receiver, of AMC messages is needed. In the next steps following example reports will be created:
- Report YRS_AMC_RECEIVE_MESSAGE_TEXT will act as consumer for the AMC application “YAMC_TEST” and the channel “/ping”.
- Report YRS_AMC_SEND_MESSAGE_TEXT will act as producer for the AMC application “YAMC_TEST” and channel “/ping”.
The programming model of ABAP Messaging Channels is simple. The class factory CL_AMC_CHANNEL_MANAGER provides AMC producer and consumer object. After creation of the AMC producer object for the respective channel, i.e. “<application name><channel id>[<channel extension id>]”, messages can be published with the provided interface method SEND. For the consumer receiving messages can be started with the interface method START_MESSAGE_DELIVERY. For this action an (call back) object has to be provided which implements the interface receiver method RECEIVE. Furthermore in order to receive the message the session has to be in an “interrupted” state. This can be achieved explicitly with the new ABAP statement WAIT FOR MESSAGING CHANNELS <expression> [UP TO <time> SECONDS].
Create the test report YRS_AMC_RECEIVE_MESSAGE_TEXT in the transaction SE38 and copy-paste following ABAP code as context for the report (see figure 3.10):
Figure 3.10.
Insert the title “Consumer test for ABAP Messaging Channel YAMC_TEST” for the report and choose following Attributes (see figure 3.11):
- Type: “Executable program”
- Status: “Test Program”
Figure 3.11.
Additionally click Save and select Local Object (see figure 3.12):
Figure 3.12.
Now insert the following ABAP code into the report and save the report (see figure 3.13):
AMC consumer example code |
---|
REPORT yrs_amc_receive_message_text.
PARAMETERS: msg_nr TYPE i DEFAULT 1, "number of expected messages
wait_sec TYPE i DEFAULT 20. "waiting time to
DATA: lo_consumer TYPE REF TO if_amc_message_consumer.
DATA: gt_message_list TYPE TABLE OF string.
DATA: lv_message TYPE string.
DATA: lx_amc_error TYPE REF TO cx_amc_error.
* implemenation class for AMC receiver interface
CLASS lcl_amc_test_text DEFINITION
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
* interface for AMC messages of type TEXT
INTERFACES if_amc_message_receiver_text .
ENDCLASS.
* Consumer test for ABAP Messaging Channel YAMC_TEST”
CLASS lcl_amc_test_text IMPLEMENTATION.
METHOD if_amc_message_receiver_text~receive.
*
* remark: in this method should the message be received and the main actions
* should be processed in the main program and usually after WAIT statement.
* Any kind of communication, e.g. RFCs, HTTP and message hanlding,
* e.g. error message is not supported and will lead to ABAP dump.
*
* insert received messages into the global table
APPEND i_message TO gt_message_list.
ENDMETHOD.
ENDCLASS.
START-OF-SELECTION.
DATA: lo_receiver_text TYPE REF TO lcl_amc_test_text.
TRY.
lo_consumer = cl_amc_channel_manager=>create_message_consumer( i_application_id = 'YAMC_TEST' i_channel_id = '/ping' ).
CREATE OBJECT lo_receiver_text.
" start of message delivery
lo_consumer->start_message_delivery( i_receiver = lo_receiver_text ).
CATCH cx_amc_error INTO lx_amc_error.
MESSAGE lx_amc_error->get_text( ) TYPE 'E'.
ENDTRY.
*
* wait until a message is received but not longer than waiting time in seconds
*
WAIT FOR MESSAGING CHANNELS UNTIL lines( gt_message_list ) >= msg_nr UP TO wait_sec SECONDS.
IF sy-subrc = 8 AND lines( gt_message_list ) = 0.
WRITE: ')-: Time out occured and no message received :-('.
ELSE.
LOOP AT gt_message_list INTO lv_message.
* print out the list of received AMC messages
WRITE: / sy-tabix, lv_message.
ENDLOOP.
ENDIF. |
Figure 3.13.
Finally activate the report (see figure 3.14):
Figure 3.14.
Create the test report YRS_AMC_SEND_MESSAGE_TEXT in transaction SE38 and copy-paste the following ABAP code as context for the report (similar to figure 3.10-2.13)Insert the title “Producer test for ABAP Messaging Channel YAMC_TEST” for the report.
Now insert the following ABAP code into the report and save the report (see figure 3.15):
AMC produce example code |
---|
REPORT yrs_amc_send_message_text.
PARAMETERS: message TYPE string LOWER CASE DEFAULT 'Hi there !'.
DATA: lo_producer_text TYPE REF TO if_amc_message_producer_text.
DATA: lx_amc_error TYPE REF TO cx_amc_error.
TRY.
lo_producer_text ?= cl_amc_channel_manager=>create_message_producer( i_application_id = 'YAMC_TEST' i_channel_id = '/ping' ).
" send message to the AMC channel
lo_producer_text->send( i_message = message ).
CATCH cx_amc_error INTO lx_amc_error.
MESSAGE lx_amc_error->get_text( ) TYPE 'E'.
ENDTRY. |
Figure 3.15.
Finally activate the report (see figure 3.14):
Choose Authorized Program and insert the report YRS_AMC_RECEIVE_MESSAGE_TEXT in the popup (see figure 3.16).
Figure 3.16.
Insert the report name YRS_AMC_RECEIVE_MESSAGE_TEXT and click Accept (see figure 3.17).
Figure 3.17.
Choose the activity Receive (see figure 3.18).
Figure 3.19.
Similar to the previous steps insert the report name YRS_AMC_SEND_MESSAGE_TEXT with the activity Send (see figure 3.20).
Figure 3.20.
Finally Save (see figure 3.21) and Activate (see figure 3.22) the AMC application. To accomplish these steps just choose Continue (process Enter) in the next popup screens (see figure 3.23).
Figure 3.21.
Figure 3.22
Click Continue (see figure 3.23).
Figure 3.23.
Now execute first the ABAP report YRS_AMC_RECEIVE_MESSAGE_TEXT (see figure 3.24) and then the report YRS_AMC_SEND_MESSAGE_TEXT (see figure 3.25) in two parallel sessions. While the report YRS_AMC_RECEIVE_MESSAGE_TEXT report subscribes to the application YAMC_TEST and channel /ping and waits for incoming messages, the report YRS_AMC_SEND_MESSAGE_TEXT sends messages to the same application and channel.
Figure 3.25.
Figure 3.26.
Remark: If during of execution of an AMC program the AMC exception with the message
“No authority for program <program name> to access to ABAP Messaging Channel with application ID <application_id> and Channel <channel_id>”
is raised, this is because in the “Authorized Program” area (see figure 3.12) the reported program is not maintained appropriately.
Limitation: In the present version of AMC framework is the size of AMC messages limited to ~31 kbytes.
Recommendation: The basic goal of AMC messages is the notification of subscribers about an event. If the subscribers should be informed about any changes to an entity in this case is the transfer of the resource URL of the affected entity to the subscribers recommended.The URL should refer to the persisted entity record, e.g. in the database.
AMC Security
The access rights for AMC channels are controlled via code based authorization and by maintenance of reports, i.e. classes, function groups or includes, which are permitted to apply an action, i.e. publish, subscribe, to the channel.
For the case, that a channel is bound to a WebSocket connection and is used to push messages from a session to a WebSocket client (see figure 2.2) , can a dedicated virus/content scan ID for outgoing messages be maintained.
AMC Supportability
Since the AMC producers and consumers, besides the collaboration scenario, resides in an ABAP session, the existing ABAP supportability tools, e.g. debugger, ABAP runtime analysis or kernel trace can be used. Within the debugger the session breakpoints can be used to debug the session during send or receive phase of the messaging. Using transaction SAT the runtime analysis for the respective session and report can be activated. Via transaction SM04 you can activate and deactivate the user specific kernel trace for the respective session.
Furthermore with the following transactions you can manage the AMC logging (activate, deactivate and monitor recorded entries):
- Transaction AMC_LOG_ADMIN: Activate and deactivate logging for dedicated AMC channels.
- Transaction AMC_LOG_PROCESSING: Monitoring transaction for the AMC log entries.
Note: For the reorganization of AMC log entries a dedicated batch job has to be planed. The pre-defined standard batch-job SAP_ABAP_CHANNELS_MANAGEMENT has to be scheduled in the transaction SM36. The batch-job requires the authorization for the authorization object S_AMC_LOG with the activity “Delete”. From release 740 SP09 is the estandard job SAP_ABAP_CHANNELS_MANAGEMENT not available anymore and the planning should be done via transaction AMC_LOG_ADMIN. For detail information refer to note 2043894.
The transaction „SMAMC“ (see figure 4.0) shows the list of the AMC channels (in our example the channel yamc_test/ping) which are registered in sessions (Type “Session”) or in case of “Collaboration scenario” the WebSocket connections (Type is “WebSocket”) in the system as AMC consumers.
Figure 4.0.
Conclusion and outlook
The present implementation of AMC supports only the best-effort strategy without guarantee of delivery. We could think about providing also reliable messaging in future release.
The next related blog to ABAP Channels is Collaboration scenario. The collaboration scenario blog describes, how by using APC and AMC can messages be pushed from ABAP sessions to WebSocket clients and vice versa.