SET_PERSISTENT_CONN_SUPPORT Procedure

This procedure enables or disables support for the HTTP 1.1 persistent-connection in the request.

If the persistent-connection support is enabled for an HTTP request, the package will keep the network connections to a Web server or the proxy server open in the package after the request is completed properly for a subsequent request to the same server to reuse per HTTP 1.1 protocol specification. With the persistent connection support, subsequent HTTP requests may be completed faster because the network connection latency is avoided. If the persistent-connection support is disabled for a request, the package will always send the HTTP header "Connection: close" automatically in the HTTP request and close the network connection when the request is completed. This setting has no effect on HTTP requests that follows HTTP 1.0 protocol, for which the network connections will always be closed after the requests are completed.

When a request is being made, the package attempts to reuse an existing persistent connection to the target Web server (or proxy server) if one is available. If none is available, a new network connection will be initiated. The persistent-connection support setting for a request affects only whether the network connection should be closed after a request completes.

Use this procedure to change the persistent-connection support setting a request inherits from the session default setting.

Users should note that while the use of persistent connections in UTL_HTTP may reduce the time it takes to fetch multiple Web pages from the same server, it consumes precious system resources (network connections) in the database server. Also, excessive use of persistent connections may reduce the scalability of the database server when too many network connections are kept open in the database server. Network connections should be kept open only if they will be used immediately by subsequent requests and should be closed immediately when they are no longer needed. Set the default persistent connection support as disabled in the session, and enable persistent connection in individual HTTP requests as shown in "Example: Using SET_PERSISTENT_CONN_SUPPORT in HTTP Requests".

Syntax

UTL_HTTP.set_persistent_conn_support(

r  IN OUT NOCOPY req,
enable  IN BOOLEAN DEFAULT FALSE);

Parameters

Table 78-32 shows the parameters for the SET_PERSISTENT_CONN_SUPPORT procedure.

Table 78-32 SET_PERSISTENT_CONN_SUPPORT Procedure Parameters

Parameter	Description
r (IN/OUT)	The HTTP request
enable (IN)	TRUE to keep the network connection persistent. FALSE otherwise.

Usage Notes

The default value of the maximum number of persistent connections in a database session is zero. To truly enable persistent connections, you must also set the maximum number of persistent connections to a positive value or no connections will be kept persistent.

Example: Using SET_PERSISTENT_CONN_SUPPORT in HTTP Requests

DECLARE
  TYPE vc2_table IS TABLE OF VARCHAR2(256) INDEX BY binary_integer;
  paths vc2_table;

UTL_HTTP.fetch_pages(paths IN vc2_table) AS
    url_prefix VARCHAR2(256) := 'http://www.my-company.com/';
    req   utl_http.req;
    resp  utl_http.resp;
    data  VARCHAR2(1024);
  BEGIN
    FOR i IN 1..paths.count LOOP
      req := utl_http.begin_request(url_prefix || paths(i));

      -- Use persistent connection except for the last request
      IF (i < paths.count) THEN
        utl_http.set_persistent_conn_support(req, TRUE);
      END IF;
  
      resp := utl_http.get_response(req);
  
      BEGIN
        LOOP
          utl_http.read_text(resp, data);
          -- do something with the data
        END LOOP;
      EXCEPTION
        WHEN utl_http.end_of_body THEN
          NULL;
      END;
      utl_http.end_response(resp);
    END LOOP;
  END;

BEGIN
  utl_http.set_persistent_conn_support(FALSE, 1);
  paths(1) := '...';
  paths(2) := '...';
  ...   
  fetch_pages(paths);
END;