SAP NetWeaver AS ABAP Release 750, ©Copyright 2016 SAP AG. All rights reserved.
ABAP - Keyword Documentation → ABAP - Reference → Data Interfaces and Communication Interfaces → ABAP Channels →APC - ABAP Push Channels
Note
Each communication step in ABAP Push Channels, such as sending a message or responding to an event, can be associated with a change of work process and usually triggers a database commit.
APC - Overview
ABAP Push Channels (APC) enable bidirectional communication with the Internet for ABAP programs using the following:
Both communication protocols are based on the transmission control protocol (TCP), which enables push communication (unlike HTTP). Under the traditional pull principle, each response of a server requires a preceding client request; under the push principle, however, 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.
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:
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 application server.
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 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 Repository Browser in ABAP Workbench by opening the context menu of a package and choosing Connectivity. The Connectivity Browser of the Object Navigator provides another means of access. To open the Object Navigator for APCs, use transaction SAPC.
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 generated when a push channels is created:
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 includes other interfaces that enable specific access to the protocol.
Example
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.
APC Handler Class
The APC handler class of each ABAP push channel inherits from one of the following superclasses (depending on its attributes):
All superclasses contain abstract interface methods ON_START and ON_MESSAGE that can be redefined as application-specific methods:
Further optional interface methods, such as ON_ACCEPT, ON_CLOSE, and ON_ERROR can be implemented to respond 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 accordance with the non-blocking model, where all statements are forbidden that could prevent inbound messages from being received.
Notes
Example
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 example program under AS ABAP as WebSocket Server creates a Web site that accesses these APC services as a client.
AS ABAP as an APC client
The functions of APC clients in an AS ABAP are implemented in handler classes that integrate the following interfaces:
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 triggered the next time messages from the server cause the work process to change. 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 cause the runtime error APC_ILLEGAL_STATEMENT.
The following classes are used to instantiate the actual client objects:
The address of the server in question, a reference to the hander object, and the subprotocol (if needed) 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:
When an APC is sent, messages can be received by the server in the client session. This requires that the current session be in a wait state (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 changed explicitly or implicitly:
Examples
AS ABAP as a detached APC client
Like in AS ABAP as an APC client, detached APC clients open a connection from an application server to an APC server and detach it again immediately. The same AS ABAP or another one can then attach itself to this connection as an attached APC client. The AS ABAP that opened the connection is given the part 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:
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.
Notes
Example
See Creating a Detached Client and AS ABAP as an Attached Client.
Associating APC with AMC
On its own, the APC framework enables a WebSocket to communicate with precisely one application server. To make communication non-dependent on the current application server, the servers can be associated using ABAP messaging channels. Here, a push channel (in the implementation of its APC handler class with method BIND_AMC_MESSAGE_CONSUMER of interface IF_APC_WS_BINDING_MANAGER of one the specially created binding managers) can be associated with an AMC consumer for a specific ABAP messaging channel with a suitable message type. Messages sent using this ABAP messaging channel are then handled automatically as APC messages. The APC framework wraps the required methods of the AMC framework. The only prerequisite is that the APC handler class is authorized to bind consumers and to send messages in the messaging channel in question. The association with the AMC consumer can be removed explicitly using the method UNBIND_AMC_MESSAGE_CONSUMER of the binding manager. Any attempts to remove a nonexistent association raise an exception.
Notes
Examples
APC - System-Wide Access
An AS ABAP can send a message to an APC with which it is not associated as long as it knows the connection handle for this connection. The APC connection can exist on the same application server or on a different server. The APC handler class can use the method GET_CONNECTION_ATTACH_HANDLE of the interface IF_APC_WSP_SERVER_CONTEXT to get its connection handle from the context object. Here, a security rule must be defined that specifies whether only sessions with the same client and user or only the current program can access the connection in the same client.
A program that knows the connection handle and meets the prerequisites can use the method ATTACH of the classes CL_APC_WSP_CLIENT_CONN_MANAGER or CL_APC_TCP_CLIENT_CONN_MANAGER to create an access object. These are the same methods as used to create an attached client for a detached client and the access object has the corresponding attributes. Its message manager can be used to create messages and send them to the APC connection.
Note
System-wide sending of messages using an access object is technically the same as using an attached client object, but the scenario itself is different. Detached clients can only be accessed using attached clients and system-wide access is possible in all scenarios (if required).
Example
See System-Wide Access.
APC Security
For the ABAP push channel, a virus scan profile can be specified for outbound and inbound messages. This profile is used when the virus scan interface (VSI) runs checks.
As was previously the case, WebSocket messages can only be handled if the WebSocket object is created using a file or website from the same address or domain. In other cases, permitted addresses or domains must be created using transaction SAPC_CROSS_ORIGIN in the table APC_CROSS_ORIGIN. Authorization for the fields of authorization object S_APC_ORIG is required.
APC - Exceptions
Error situations in sender and receiver programs (such as violations of rules set by the properties of a push channel) raise exceptions of the class CX_APC_ERROR.
APC - Test and Analysis
The existing test and analysis tools, such as ABAP Debugger, runtime analysis, or performance trace, can be used as usual for programs running on AS ABAP and sending and receiving APC messages.
An overview of all APC connections on an AS ABAP can be found in transaction SMWS. Any surplus connections can also be closed here.
More Information
Detailed information about APC can be found in the ABAP Channels documentation in SAP Help Portal.