com.WebServiceEngine.HandleRequest

Wait for an HTTP input request to process an operation of one of the registered SOAP or REST Web Services, or return an HttpServiceRequest object to handle a low-level request not registered at all.

Syntax

com.WebServiceEngine.HandleRequest(
   timeout INTEGER,
   status INTEGER )
  RETURNS com.HttpServiceRequest
  1. timeout defines the timeout in seconds.
  2. status defines the variable receiving the method execution status. The variable must be INTEGER, SMALLINT, or BIGINT; otherwise, a runtime error is thrown.

The method returns a com.HttpServiceRequest object when the request targets a service that is not registered, and NULL otherwise. For the meaning of each status value, go to Table 1.

Usage

com.WebServiceEngine.HandleRequest() waits for an incoming HTTP request. Before using this method, you register the service and start the engine the same as when using ProcessServices(). For example, call RegisterRestService() or RegisterService() before starting the engine.

You typically call com.WebServiceEngine.HandleRequest() inside a loop that runs until the server stops or a fatal error occurs, and handle the status in a CASE / END CASE block. As long as the int_flag variable is FALSE or the execution status is valid, the condition within the loop remains TRUE and requests are executed.

The program must declare DEFER INTERRUPT. Without that declaration, an interrupt stops the program inside the waiting method, so neither the -4 status nor the int_flag test is reached.

The method sets the status variable as follows:

Table 1. HandleRequest status values
Situation status Resolution/Additional notes
Request for a registered SOAP or REST service 0 The engine processed the request, as ProcessServices() does.
Request for a service that is not registered 1

The method returns a com.HttpServiceRequest object. Send a response with it. If you do not respond, the next call to HandleRequest() fails, because the previous request object remains active.

A query-only request to the service root path, such as /service?abc, also falls back to this case when no REST operation matches.

No request within the timeout -1 Not an error: no request arrived in time. Call the method again to go on waiting. With a timeout of -1, the method waits without a time limit and never returns this status.
The GAS disconnected the program -2 The method raises error -15575. Trap it with TRY/CATCH and exit the program.
Client closed the connection (standalone mode) -3 The method raises error -15575. Trap it with TRY/CATCH. The server stays usable, so you can go on processing requests.
Request that is not valid HTTP -5 (-8 before FGLGWS 6.00.03)

Starting from FGLGWS 6.00.03, the server responds to the client with an HTTP error status (501 for an unknown method, 505 for an unsupported HTTP version, and 400 for other invalid requests) and keeps running, so the application can process later requests.

In earlier versions, such a request puts the GWS HTTP server into an invalid state. Even if the application traps the exception, every later call fails with the same error. The application must then shut down cleanly and exit.

An XML service is reached with a method other than GET or POST -9 The server sends an HTTP error response to the client and keeps running.
The web operation called com.WebServiceEngine.Flush() -31 Not an error: the web operation sent its response early. Check the status that Flush() returns inside the web operation function. For details and an example, go to com.WebServiceEngine.Flush.
No REST operation matches the request path, method, and media type (the Accept or Content-Type header) -35 Check the URL of the resource, the HTTP method and headers, and the REST web service function parameters. The server sends an HTTP error response to the client and keeps running.
Other errors Other negative values For the full list, go to Error codes of com.WebServiceEngine.

The method reports most results in the status variable, with the Web Services engine codes listed in HandleRequest status values. It raises only the BDL runtime errors listed in HandleRequest exceptions as exceptions, which you trap with TRY/CATCH. For both, the sqlca.sqlerrm register can hold a description of the problem.

Note:

In earlier versions, with GAS 6.00.04 or later, this is not an issue in production environments: the Genero Application Server (GAS) and GWSProxy detect the ended DVM, return an HTTP error code to the client app, and any new request starts a new DVM in a clean state through GWSProxy and the pool configuration.

Table 2. HandleRequest exceptions
Error code Meaning Notes / Recommendation
-15552 URL charset conversion failure Thrown when the server cannot convert UTF‑8 URLs to the fglrun locale charset. Recommendation: run the Web Services server program in UTF‑8.
-15575 Connection closed Thrown when the GAS disconnects the WS program, with a status of -2, or, in standalone mode, when the client closes the connection, with a status of -3. For what to do in each case, go to The GAS disconnected the program and Client closed the connection.

Example: Handle HTTP requests

This example shows how to use com.WebServiceEngine.HandleRequest() to process incoming requests and handle status = 1 by responding to requests for unregistered services. The TRY/CATCH block traps error -15575. The loop goes on when the client closes the connection (status -3), and the program exits when the GAS disconnects it (status -2).
Tip:

Use com.WebServiceEngine.ProcessServices() for servers that handle only registered web services. Use com.WebServiceEngine.HandleRequest() when you need to intercept and respond to unregistered services or implement custom endpoints.

IMPORT com
IMPORT FGL myservice

MAIN
  DEFINE status INTEGER
  DEFINE req com.HttpServiceRequest
  DEFER INTERRUPT

  CALL com.WebServiceEngine.RegisterRestService("myservice", "MyService")
  DISPLAY "Server started"
  CALL com.WebServiceEngine.Start()

  WHILE TRUE
    TRY
      LET req = com.WebServiceEngine.HandleRequest(-1, status)
    CATCH
      # Error -15575 is raised when the connection is closed:
      # status is -3 when the client closed it, -2 when the GAS did
      DISPLAY "Connection closed: ", sqlca.sqlerrm
    END TRY

    CASE status
      WHEN 0
        DISPLAY "Request processed."
      WHEN 1
        DISPLAY "Unregistered service request."
        CALL req.sendResponse(400, SFMT("Unknown service (%1)", req.getUrl()))
      WHEN -1
        DISPLAY "Timeout reached."
      WHEN -2
        DISPLAY "Disconnected from application server."
        EXIT PROGRAM
      WHEN -3
        DISPLAY "Client connection lost."
      WHEN -4
        DISPLAY "Server interrupted with Ctrl-C."
      WHEN -5
        DISPLAY "Invalid HTTP request."
      WHEN -8
        DISPLAY "HTTP error, the server stops."
        EXIT WHILE
      WHEN -9
        DISPLAY "Unsupported operation."
      WHEN -10
        DISPLAY "Internal server error."
      WHEN -23
        DISPLAY "Deserialization error."
      WHEN -31
        DISPLAY "Flush detected."
      WHEN -35
        DISPLAY "No such REST operation found."
      WHEN -36
        DISPLAY "Missing REST parameter."
      WHEN -15552
        DISPLAY "UTF-8 URL conversion error."
      OTHERWISE
        DISPLAY "Unexpected server error ", status, " - ", sqlca.sqlerrm
        EXIT WHILE
    END CASE

    IF int_flag <> 0 THEN
      LET int_flag = 0
      EXIT WHILE
    END IF
  END WHILE

  DISPLAY "Server stopped"

END MAIN