Get Example source ABAP code based on a different SAP table
ABAP Push Channels ( ABAP_APC ) ITOC
Latest notes: Each communication step using ABAP Push Channels, such as sending a message or responding to an event, can trigger the change of the work process and usually triggers a database commit. ABAP_HINT_END
APC - Overview ABAP Push Channels (APC) enable bidirectional communication with the Internet for ABAP programs using:
WebSockets
TCP sockets Both communication protocols are based on the transmission control protocol (TCP), which enables push communication, unlike HTTP. With the traditional pull principle, each response of a server requires a preceding client request, however with the push principle, it is enough to have an open connection between client and server, used by the server to pass information as soon as it becomes available.
An AS ABAP can use the WebSocket protocol to communicate with clients and servers that support this protocol. All standard Web browsers, for example, support the WebSocket protocol. One example of clients are appropriately programmed Web pages in browsers that support WebSockets.
An AS ABAP can use TCP sockets directly using TCP/IP packets to communicate with clients and servers that do not support the WebSocket protocol. These can be, for example, embedded systems or programmable logic controllers (PLC). Direct communication is hence possible between ABAP programs and intelligent things in the Internet of Things (IoT) or devices used to control and monitor machines. ABAP Push Channels can be used to make AS ABAP into a WebSocket server and a WebSocket client. The APC framework in AS ABAP makes the following scenarios possible:
AS ABAP as an APC server
stateless
stateful
AS ABAP as APC client
AS ABAP as a detached APC client
stateless
stateful A detached client is an AS ABAP ABAP_ASINSTANCE that opens a connection to an APC server, is detached, and can then itself be addressed as an APC server. All scenarios can be implemented for both protocols, WebSocket and TCP socket. The associated class-based APIs in AS ABAP for both protocols are very similar. For an AS ABAP as APC server, ABAP push channels need to be created as repository objects. A service in the ICF service tree and a special APC handler class are then assigned to these objects. A WebSocket server can be addressed directly using a HTTP/HTTPS query, whereas corresponding TCP ports need to be configured for TCP sockets. For both protocols, simple character and byte strings can be used as a format for messages. In the case of the WebSocket protocol, SAP's Push Channel Protocol (PCP) should also be used. For the WebSocket protocol, it is still possible to associate ABAP Push Channels with ABAP Messaging Channels (AMC) to make AS ABAP communication with the Internet independent of the current ABAP_ASINSTANCE .
AS ABAP as an APC Server To implement a stateless or stateful APC server on an AS ABAP, an ABAP push channel must be created as a repository object and an associated APC handler class must be implemented.
ABAP Push Channels as Repository Objects An ABAP push channel defined as a repository object must exist for each APC server application. ABAP Push Channels can be created in the Repository Browser in the ABAP Workbench by opening the context menu of a package and choosing Connectivity. The Connectivity Browser of the Object Navigator provides another access option. To open the Object Navigator for APCs, transaction SAPC can be used . When a push channel is created, either WebSocket or TCP socket must be defined as the connection type. The server must also be defined as stateless or stateful. On stateful servers, the context and, more specifically, the attributes of the APC handler are preserved each time the server is accessed by a client. Each push channel has two further repository objects that are generated when a push channels is created:
A node in the service tree of ICF, visible in transaction SICF (the service editor). Like all other ICF services, this node represents the Web address of the push channel. This node can be activated and deactivated in the service editor, but not tested directly.
In the case of the WebSocket protocol, other systems, such as a Web browser that supports the WebSocket protocol, can use this address to communicate with the push channel directly.
In the case of the TCP socket protocol, the alias mechanism in ICF must be used to configure a TCP port.
An APC handler class that is stored as a global class in the ABAP Class Library and which can be edited in the Class Builder or ADT. When a query is sent to a push channel, the APC framework creates an instance of the class as an APC handler in a dedicated APC session. An optional subprotocol of the WebSocket protocol can be assigned to a push channel that uses the WebSocket protocol. Currently, SAP's own Push Channel Protocol (PCP) can be assigned. The generated APC handler class inherits from a different superclass, depending on the protocol used, and implements other interfaces that enable specific access to the protocol.
Example ABAP Coding
See the ABAP push channels DEMO_APC, DEMO_APC_PCP, and DEMO_APC_PCP_STATEFUL in the package SABAPDEMOS. All three use the WebSocket protocol. DEMO_APC is stateless and does not use a subprotocol. DEMO_APC_PCP is stateless and uses the Push Channel Protocol (PCP) as a subprotocol. DEMO_APC_PCP_STATEFUL is like DEMO_APC_PCP but is stateful. ABAP_EXAMPLE_END
APC Handler Class The APC handler class of each ABAP push channel inherits from one of the following superclasses, depending on its attributes:
WebSocket protocol
CL_APC_WSP_EXT_STATELESS_BASE
(stateless if a subprotocol is not used)
CL_APC_WSP_EXT_STATELESS_PCP_B
(stateless if the Push Channel Protocol (PCP) is used)
CL_APC_WSP_EXT_STATEFUL_BASE
(stateful if a subprotocol is not used)
CL_APC_WSP_EXT_STATEFUL_PCP_B
(stateful if the Push Channel Protocol (PCP) is used)
TCP socket protocol.
CL_APC_TCP_EXT_STATELESS_BASE
(stateless)
CL_APC_TCP_EXT_STATEFUL_BASE
(stateful) All superclasses contain abstract interface methods ON_START and ON_MESSAGE that must be redefined as application-specific methods:
ON_START The APC framework runs this method in the APC handler when the push channel is opened. Here, initial actions can be implemented that are to be performed at this time. For example, the binding can be made to an ABAP Messaging Channel here. The method can also remain empty.
ON_MESSAGE The APC framework executes this method in the APC handler when the push channel receives an APC message. All reactions to the message must be implemented or called here. Input parameters are available here that reference objects for the message, its context, and the message manager. For example, a message can be sent as a response.
In an APC without a subprotocol, text messages and binary message content can be read from received message objects and written to message objects to be sent.
In an APC with Push Channel Protocol (PCP), the content of received messages can be deserialized to ABAP data and ABAP data can be serialized to message objects to be sent. Further optional interface methods, such as ON_ACCEPT, ON_CLOSE, and ON_ERROR can be implemented to react to the corresponding events. More particularly, ON_ACCEPT can be used to decide whether an APC connection is opened. The APC handler classes for the TCP socket protocol have an additional method ON_CONNECTION_SETUP from the interface IF_APC_TCP_SERVER_CONFIG in which the TCP framework structure must be defined. Here, a TCP framework type and a value for this type can be specified using constants of the interface IF_APC_TCP_FRAME_TYPES. The TCP framework structure can be determined using a terminator character or a length. An APC message in an APC handler class is handled as APC processing in a separate APC session. Here, certain statements, like MESSAGE or BREAK-POINT, are handled differently than, for example, in dialog processing. External breakpoints can be set to debug programs during APC processing. In stateful APC processing, the program is executed in non-blocking mode, where all statements are forbidden that could prevent inbound messages from being received.
Latest notes:
Each time a message is sent and each time APC processing is exited, a database commit is executed, except during updates.
If no subprotocol is used, there are no special requirements made for an APC client, such as a WebSocket-enabled browser. As a WebSocket server, an AS ABAP can be addressed using text messages and binary messages and with standard techniques. If SAP's own Push Channel Protocol (PCP) is used, a WebSocket client must use the associated API. For external clients such as WebSocket-enabled browsers, this API is available as a JavaScript file in the MIME repository under the node /sap/public/bc/ur/sap-pcp-websocket.js. ABAP_HINT_END
Example ABAP Coding
See the APC handler class CL_APC_WS_EXT_DEMO_APC for the ABAP push channel DEMO_APC or CL_APC_WSP_EXT_DEMO_APC_PCP for the ABAP push channel DEMO_APC_PCP. The APC handler class CL_APC_WSP_EXT_DEMO_APC_PCP_ST for the ABAP push channel DEMO_APC_PCP_STATEFUL calls the identically named methods of CL_APC_WSP_EXT_DEMO_APC_PCP. Here, an object of the class is created in the method ON_ACCEPT . The executable example under AS ABAP as WebSocket Server creates a Web site that accesses these APC services as a client. ABAP_EXAMPLE_END
AS ABAP as APC Client The functions of APC clients in an AS ABAP are implemented in handler classes that include the following interfaces:
IF_APC_WSP_EVENT_HANDLER for the WebSocket protocol and the TCP socket protocol without subprotocol.
IF_APC_WSP_EVENT_HANDLER_PCP for the WebSocket protocol with the Push Channel Protocol (PCP) The interface methods ON_OPEN, ON_MESSAGE, ON_CLOSE , and ON_ERROR can be implemented in suitable ways in the handler classes. ON_OPEN and ON_CLOSE are executed when opening and closing a connection, whereas ON_MESSAGE is raised the next time messages from the server cause the work process to be switched. The attribute MESSAGE can be accessed in ON_MESSAGE. When a method like this is being processed, no database commit can be executed, implicitly or explicitly, since this causes the runtime error APC_ILLEGAL_STATEMENT. The following classes are used to instantiate the actual client objects:
CL_APC_WSP_CLIENT_MANAGER using the methods CREATE_BY_URL or CREATE_BY_DESTINATION for the WebSocket protocol
CL_APC_TCP_CLIENT_MANAGER using the method CREATE for the TCP socket protocol The address of the required server, a reference to the hander object, and the subprotocol, if necessary, are passed to these methods. In the case of the TCP socket protocol, the TCP framework structure must be defined by a terminator character or a length. Reference variables of the type IF_APC_WSP_CLIENT that point to a client object with the following interface methods are returned:
The method GET_CONTEXT returns a context object whose method GET_INITIAL_REQUEST can be used in the WebSocket protocol to create an access object for the HTTP address. This object then adds paths and forms fields for the address.
The method CONNECT opens an APC connection to a server using the information from the client object. The method CLOSE can be used to close the connection again explicitly. If the current ABAP_ISESS is closed while a connection is open, the connection is also closed implicitly. If a connection is closed by an error, the handler method ON_ERROR and then ON_CLOSE are called.
The method GET_MESSAGE_MANAGER returns a reference of type IF_APC_WSP_MESSAGE_MANAGER_BAS to a message manager object that can be cast to IF_APC_WSP_MESSAGE_MANAGER or IF_APC_WSP_MESSAGE_MANAGER_PCP, depending on the subprotocol. The message manager can be used to create messages and send them from the client to the server. When an APC message is sent, messages can be received by the server in the client session. This requires that the current session be in a wait state, that is, rolled out by a change of work process. Messages directed to the client that are received by the AS ABAP during the wait state call the method ON_MESSAGE of the handler object when the session is rolled in. The work process can be switched explicitly or implicitly:
The statement WAIT FOR PUSH CHANNELS is used for explicit programming. Depending on a condition, this statement switches the work process, and hence rolls out the session, while waiting for messages.
Implicit switches of the work process, such as those that occur for example at the end of a dialog step, are useful in GUI scenarios where WAIT needs to be avoided.
ABAP_EXAMPLES_ABEXA
AS ABAP as WebSocket client
AS ABAP as TCP socket client ABAP_EXAMPLE_END
AS ABAP as a Detached APC Client Like in AS ABAP as an APC client, detached APC clients open a connection from an ABAP_ASINSTANCE to an APC server and detach it again immediately. Either the same AS ABAP or another can then attach itself to this connection as an attached APC client. The AS ABAP that opened the connection plays the role of an APC server as a detached client. This server can be stateless or stateful. As in an APC client, a detached client requires handler classes with the interfaces IF_APC_WSP_EVENT_HANDLER or IF_APC_WSP_EVENT_HANDLER_PCP. In this case, however, only the method ON_OPEN is called and must be implemented accordingly. In the method ON_OPEN, the method GET_CONNECTION_ATTACH_HANDLE of the interface IF_APC_WSP_SERVER_CONTEXT can be used to get a connection handle for the detached client from the context object. This can then be used to connect with an attached client. Here, a security rule must be defined that specifies whether only sessions with the same client and user or only the current program can operate as an attached client in the same client. The following classes are used to instantiate the actual detached client objects:
CL_APC_WSP_CLIENT_CONN_MANAGER using the methods CREATE_BY_URL or CREATE_BY_DESTINATION for the WebSocket protocol
CL_APC_TCP_CLIENT_CONN_MANAGER using the method CREATE for the TCP socket protocol The methods CREATE_... have the same semantics as in a regular APC client and connect to an APC server. The interface IF_APC_WSP_CLIENT_CONN_DETACH is used to access a detached client object. Once a connection is defined with a stateless or stateful APC, it is opened and then immediately detached using the method CONNECT_AND_DETACH. This executes the method ON_OPEN, which gets a connection handle for the connection using the context object. To connect an AS ABAP with the detached client as an attached client, the method ATTACH of the classes CL_APC_WSP_CLIENT_CONN_MANAGER or CL_APC_TCP_CLIENT_CONN_MANAGER above is used to create attached client objects. Here, the connection handle for the connection must be passed. This can take place in the current session or in a different session. The interface IF_APC_WSP_CLIENT_CONN_ATTACH can be used to access an attached client object. As in regular client objects, messages can be sent using the message manager. It is not possible, however, to create a connection with a handler class to use WAIT FOR PUSH CHANNELS to wait for messages. Any connections to detached clients that are no longer needed should be closed using the method CLOSE of the attached client object.
Latest notes:
A detached client supports scenarios where an AS ABAP that wants to operate as an APC server itself opens an APC connection.
If the same AS ABAP with the same ABAP push channel plays the role of the detached and attached client, the sent messages must be identified as suitable messages in the APC handler class to prevent it from responding to its own messages. The header fields of the PCP protocol are an appropriate way of doing this.
While an AS ABAP is working as a stateful detached client, an ABAP program is processed in the non-blocking mode. Here, all statements are forbidden that could prevent inbound messages from being received.
APC messages sent from an attached client object using the interface IF_APC_WSP_CLIENT_CONN_ATTACH
