Application Development Blog Posts
Learn and share on deeper, cross technology development topics such as integration and connectivity, automation, cloud extensibility, developing at scale, and security.
cancel
Showing results for 
Search instead for 
Did you mean: 
masoud_aghadavoodijolfaei
Active Participant

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 ExamplesSee also FAQ - ABAP Channels.

This blog focuses on the WebSocket integration in ABAP, also known as ABAP Push Channel (APC).

For live demonstration and step-by-step implementation take a look at ABAP Push Channel Video.

 

Integration of WebSocket into ABAP engine

In order to pass an event from the ABAP engine to an HTML5 based user agent we decided to integrate the WebSocket protocol into the ABAP engine.WebSocket provides a bi-directional communication channel over a TCP/IP socket. It is designed to be implemented in web browsers and web servers, but in general it can be used by any client or server application. The WebSocket JavaScript API is standardized by the W3C, whereas the WebSocket protocol (RFC 6455) is standardized by the IETF. The WebSocket protocol is supported by many new browsers, e.g.  Chrome 14, Firefox 7.0, IE 10 and Safari on iOS6 (and higher).

 

The implementation of the WebSocket protocol (RFC 6455) in ABAP is called ABAP Push Channel (APC).The APC communication is stateless per default, i.e. each WebSocket message leads to he creation of an individual ABAP session for execution of the respective method. After termination of the method the session will be released. In contrast to the existing request-response-based communication protocols, e.g. Remote Function Call (RFC) and HTTP(S), APC is a message-based protocol, i.e. per default the execution of a message does not lead to a response. However on top of the messaging protocols various communication patterns can be built, also a request-response-based communication. This is possible because the APC session has been implemented as a new session type..

 

It is important to have an understanding for the WebSocket events and methods before starting to explain how the WebSocket protocol has been integrated into the ABAP engine. The following simple sample code snippet shows how to use the JavaScript WebSockets interface (the essential events and methods are in bold format):

 












WebSocket JavaScript example code

   // open a WebSocket connection


     var ws = new WebSocket("ws[s]://host.domain:port/path?query_string");


 

     ws.onopen = function()


     {


        // WebSocket is connected, send data using send()


        ws.send("Sending Message ....");


        alert("Message is sent...");


     };


 

     ws.onmessage = function (msg)


     {


        // process received Message


        alert(msg.data);


 

        // optionally close connection
         ws.close();


     };


 

     ws.onclose = function()


     {


         // WebSocket is closed.


         alert("Connection is closed...");


     };


 


 

In APC framework the involved events and methods are very similar. A simple APC class handler would have the following events and methods.

In order to support WebSocket specification for subprotocols according to RFC 6455 has the APC server interface IF_APC_WS_EXTENSION been refactored and the new interface IF_APC_WSP_EXTENSION with 740 SP08 has been established.

 












APC example code (before 740 SP08)


CLASS YCL_APC_WS_EXT_YEXAMPLE IMPLEMENTATION.

 

     METHOD if_apc_ws_extension~on_start( i_context type ref to  if_apc_ws_context ).

      " WebSocket connection has been established

     ENDMETHOD.

 

     METHOD if_apc_ws_extension~on_message( i_message type ref to  if_apc_ws_message ).

       " Message has been received

        TRY.

         " Echo the message on WebSocket connection

              data(lo_message_manager) = i_message->get_context( )->get_message_manager( ).

              lo_message = lo_message_manager->create_message( ).

              lo_message->set_text( i_message->get_text( ) )

 

              " Send message


              lo_message_manager->send( lo_message ).

           CATCH cx_apc_error INTO lx_apc_error.

              ...

          ENDTRY.

     ENDMETHOD.

 

     METHOD if_apc_ws_extension~on_close.

       " WebSocket is closed

     ENDMETHOD.

 

ENDCLASS.


 

The new version of APC class handler would have the following events and methods, which also supports the Push Channel Protocol (PCP) as subprotcol.












APC example code (from 740 SP08)


CLASS YCL_APC_WSP_EXT_YEXAMPLE IMPLEMENTATION.

 

     METHOD if_apc_wsp_extension~on_start(
i_context type ref to if_apc_wsp_server_context
i_message_manager type ref to if_apc_wsp_message_manager ).


      " WebSocket connection has been established

     ENDMETHOD.

 

     METHOD if_apc_wsp_extension~on_message(
i_message type ref to if_apc_wsp_message
i_message_manager type ref to if_apc_wsp_message_manager
i_context type ref to if_apc_wsp_server_context ).


       " Message has been received

        TRY.

         " Echo the message on WebSocket connection

              lo_message = i_message_manager->create_message( ).

              lo_message->set_text( i_message->get_text( ) )

 

              " Send message


              i_message_manager->send( lo_message ).

           CATCH cx_apc_error INTO lx_apc_error.

              ...

          ENDTRY.

     ENDMETHOD.

 

     METHOD if_apc_wsp_extension~on_close(
i_reason type string
i_code type type i
i_context_base type ref to if_apc_wsp_server_context_base ).


       " WebSocket is closed

     ENDMETHOD.

 

ENDCLASS.


 

The following diagram (figure 2.0) shows the interaction model of WebSocket client, e.g. HTML5-enabled browser, and APC framework in the ABAP engine of the NetWeaver application server.

 


Figure 2.0: WebSocket/APC interaction model in ABAP


 


The main advantage of the integration model is based on the fact that WebSocket connections are administrated by an ICM process, i.e. the end-point of a connection is the ICM process and not the ABAP session. This design helps to reduce resource consumption during inactivity phases of WebSocket communication. Furthermore APC applications are stateless per default.This means that each received message is handled in a dedicated session. The  application can preserve its state information either in shared object areas or database tables.

 

Creating an ABAP Push Channel (APC) application

This section contains a step by step description of the creation of an ABAP Push Channel application.

 

Before starting with development of an APC application we should check the prerequisites for the WebSocket environment in ABAP. From support package 5 upwards the WebSocket configuration is active per default. The WebSocket connection uses the same ports as the maintained HTTP and HTTPS ports and there is no explicit entry for "WEBSOCKET" and "WEBSOCKETS" services in service entries of transaction SMICM. This is different in lower releases. In NetWeaver 740 support package 2 up to support package 4, the WebSocket port parameters were maintained actively. This can be done in two different ways:



    • Manually and  temporarily in the transaction SMICM (via menu entry "Goto" -> "Service" and again in menu "Service" -> "Create") you can choose a proper port number for the field "New Service Port" , e.g. 50090 or 44390 for secure or non-secure WebSocket (WS), and then in the field "Protocol" enter "WEBSOCKET" (non-secure WebSocket) or "WEBSOCKETS" (secure WebSocket).







    • Alternatively, enabling ABAP to use WebSockets can be performed by setting ICM profile parameters. In the profile of the instances supporting WebSockets, some parameters must be added. Example:




icm/server_port_101 = PROT=WEBSOCKET,PORT=0,TIMEOUT=-1
icm/server_port_102 = PROT=WEBSOCKETS,PORT=0,TIMEOUT=-1


assuming that 101 and 102 are not yet used by other server_ports.


Port number is always 0. Timeout is always -1.


 

An ABAP Push Channel (APC) 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 Push Channel" (see figure 2.1):





Figure 2.1.


 


 



    • As of release 740 SP5: In the transaction SAPC using the context menu entry ("Right-Click") on the "ABAP Push Channel" entry and selecting "Create" (see figure 2.2):

      Figure 2.2.


      In the next step, the name of the APC application has to be enteredand the popup screens have to be confimed (press "Enter"). In this example "YAPC_WS_TEST" is used as application name (see figure 2.3):

      Figure 2.3.


       


       

      Also choose an appropriate package entry, in this case as "Local Object" (see figure 2.4):


      Figure 2.4.


       


       

      Additionally, the field "Description" has to be maintained (see figure 2.5):


      Figure 2.5.


       


       

      Next step: save the application (see figure 2.6):


      Figure 2.6.


       


       

      Now the associated design time entities, i.e. in the transaction SICF service path /sap/bc/apc/<name space>/<application name> and the corresponding APC application class, have to be generated (see figure 2.7):


      Figure 2.7.


       

      Confirm the generation step.

       

       

      In the next steps the basic implementation of the APC extension class will be initiated. To do so, double-click on the class name, here YCL_APC_WS_EXT_YAPC_WS_TEST (see figure 2.8):


      Figure 2.8.


       


       

      The before-mentioned action leads to the display of the class YCL_APC_WS_EXT_YAPC_WS_TEST in the class builder environment (see figure 2.9):


      Figure 2.9.


       


       

      Change the display mode to change, i.e.click "Display" <-> "Change" (see figure 2.10).


      Figure 2.10.


       


       

      The required actions are the implementation of the methods ON_START and ON_MESSAGE. The ON_START method is executed as soon as the WebSocket connection setup phase is accomplished successfully. The ON_MESSAGE method is executed when receiving a message. As the extension class is inherited from an abstract class to implement the ON_START and ON_MESSAGE methods these methods have to be redefined. Optionally also the method ON_CLOSE and ON_ERROR can be redefined, i.e. implemented, as well. To do so, choose the respective method, i.e. ON_START, and press "Redefine" (see figure 2.11):


      Figure 2.11.


       


       

      In this example the only action which is processed during ON_START execution is to send a text message to the WebSocket client, after inserting the following code in the method ON_START:

       

      The example coding for 740 with support package less than SP08 is:

      METHOD if_apc_ws_extension~on_start.

        TRY.

      * send the message on WebSocket connection

            DATA(lo_message_manager) = i_context->get_message_manager( ).

            DATA(lo_message) = lo_message_manager->create_message( ).

            lo_message->set_text( |{ sy-mandt }/{ sy-uname }: ON_START has been successfully executed !| ).

            lo_message_manager->send( lo_message ).

          CATCH cx_apc_error INTO DATA(lx_apc_error).

            MESSAGE lx_apc_error->get_text( ) TYPE 'E'.

        ENDTRY.

      ENDMETHOD.
      And the coding for 740 SP08 and later is:

      METHOD if_apc_ws_extension~on_start.

        TRY.

      * send the message on WebSocket connection

            DATA(lo_message) = i_message_manager->create_message( ).

            lo_message->set_text( |{ sy-mandt }/{ sy-uname }: ON_START has been successfully executed !| ).

            i_message_manager->send( lo_message ).

          CATCH cx_apc_error INTO DATA(lx_apc_error).

            MESSAGE lx_apc_error->get_text( ) TYPE 'E'.

        ENDTRY.

      ENDMETHOD.

      the method contains the code below (see figure 2.12):


      Figure 2.12.


       


       

      Save the method (click "Save") in the "Class Builder" (see figure 2.13):


      Figure 2.13.


       


       

      and leave the method (click "Back"), see figure 2.14:

       


      Figure 2.14.


       

      In the ON_MESSAGE method both a message text and the received message are sent to the WebSocket client, after inserting the following code in the ON_MESSAGE method:

      The example coding for 740 with support package less than SP08 is:

       

      METHOD if_apc_ws_extension~on_message.

        TRY.

      * retrieve the text message

            DATA(lv_text) = i_message->get_text( ).

       

      * create the message manager and message object

            DATA(lo_context) = i_message->get_context( ).

            DATA(lo_message_manager) = lo_context->get_message_manager( ).

            DATA(lo_message) = lo_message_manager->create_message( ).

       

      * send 1st message

            lo_message->set_text( |{ sy-mandt }/{ sy-uname }: ON_MESSAGE has been successfully executed !| ).

            lo_message_manager->send( lo_message ).

       

      * send 2nd message, i.e. echo the incoming message

            lo_message->set_text( lv_text ).

            lo_message_manager->send( lo_message ).

          CATCH cx_apc_error INTO DATA(lx_apc_error).

            MESSAGE lx_apc_error->get_text( ) TYPE 'E'.

        ENDTRY.

      ENDMETHOD.

       

      And for 740 SP08 and later release is:

       

      METHOD if_apc_ws_extension~on_message.

        TRY.

      * retrieve the text message

            DATA(lv_text) = i_message->get_text( ).

       

      * create the message object

            DATA(lo_message) = lo_message_manager->create_message( ).

       

      * send 1st message

            lo_message->set_text( |{ sy-mandt }/{ sy-uname }: ON_MESSAGE has been successfully executed !| ).

            i_message_manager->send( lo_message ).

       

      * send 2nd message, i.e. echo the incoming message

            lo_message->set_text( lv_text ).

            i_message_manager->send( lo_message ).

          CATCH cx_apc_error INTO DATA(lx_apc_error).

            MESSAGE lx_apc_error->get_text( ) TYPE 'E'.

        ENDTRY.

      ENDMETHOD.

       

      The method contains the code below (see figure 2.15):


      Figure 2.15.


       

       

      Additionally save the method (click "Save") in the "Class Builder" (transaction SE24), see figure 2.16:


      Figure 2.16.


       

      and leave the method (click "Back"), see figure 2.17:

      :


      Figure 2.17.


       


       

      Finally, activate the class (click "Activate") in the "Class Builder", see figure 2.18:


      Figure 2.18.


       


       

      and leave the "Class Builder" via Back (see figure 2.19):


      Figure 2.19.


       


       

      Optionally, you can maintain the virus/content scan IDs for incoming and outgoing messages at any time (see figure 2.20):


      Figure 2.20.


       


      Now the APC application has to be activated as well, to do so press Activate (see figure 2.21):


      Figure 2.21.


       

      To test the application just press the Test icon (see figure 2.22):


      Figure 2.22.


       

       

      This action launches the Web Dynpro application WDR_TEST_APC in a browser (see figure 2.23) which supports the WebSocket protocol (RFC 6455) (e.g. Chrome version >= 16, Firefox version >= 11, Internet Explorer version >= 10 and Safari on iOS version >= 6). In case of any issue it should be double checked that the Web Dynpro service path "/sap/bc/webdynpro/sap/wdr_test_apc" in the transaction SICF is active.


      Figure 2.23.






 

 

Limitation: In the present version of APC framework is the size of WebSocket/APC messages exchanged between client and server limited to ~64 kbytes.  Furthermore the WebSocket support in Web Dispatcher is released with the version 7.41 and for installation of a new version of Web Dispatcher please refer to SAP note 908097.

 

APC Security

Each APC application has a path entry in the transaction SICF. With a new installation this entry is inactive per default. For an active usage of an APC application the associated APC path in SICF transaction has to be activated before. The path to an APC application is /sap/bc/apc/<name space>/<application name>. For each APC application you can maintain a dedicated virus/content scan ID for outgoing and incoming messages. Furthermore we recommend to use the existing escape methods in ABAP, e.g. the ESCAPE statement, to escape the WebSocket content that is exchanged between client and server. Finally we highly recommend to use the secure varaint of WebSocket, i.e. wss instead of ws, for the communication.

 

For cross-origin-access to an APC application the APC framework also supports some aspects of the "The Web Origin Concept", i.e. RFC 6454. In order to allow the access to APC application from an external server the white list maintenance via transaction SAPC_CROSS_ORIGIN has to be done accordingly.

 

 

APC Supportability


WIth external breakpoints you can debug the execution of the ON_START, ON_MESSAGE, ON_CLOSE and ON_ERROR methods similarily to HTTP handler i.e. by setting breakpoints in the respective methods.

 

In transaction SAPC you can activate/deactivate the following supportability tools for a specific APC application:

be initiated:

 

  • Debugging: choose menu bar the entry "Utilities" -> "Debugging" -> "Activate Debugging"/Deactivate Debugging"

  • Runtime Analysis: choose menu bar the entry "Utilities" -> "Runtime Analysis" -> "Activate"/Deactivate"

  • Kernel Trace: choose menu bar the entry "Utilities" -> "Trace" -> "Reset Trace"/"Display Trace"/"Activate Trace"/"Deactivate Trace"


 

The  runtime analysis records which start with the prefix "APC:<application path>", e.g. "APC:/sap/bc/apc/sap/ping" for a PING application, can be monitored in transaction SAT.

 

Furthermore, transaction SMWS shows the list of active WebSocket connections and their associated APC application on each application server.

 

 

Conclusion and outlook

As you can see from the lines above, the ABAP Push Channel provides the infrastructure for WebSocket communication in ABAP. The present implementation of APC supports only the server side of communication based on stateless sessions, i.e. stateless APC communication similar to stateless HTTP communication. A stateful APC communication and also an APC client library are under development.

 

The next related blog to ABAP Channels is ABAP Messaging Channel (AMC). AMC blog describes the eventing framework for messages exchange between different ABAP sessions based on publish/subscribe channels.

 
63 Comments