Note:

Table 225-1 UTL_HTTP Constants - HTTP Versions

Table 225-2 UTL_HTTP Constants - Default Ports

Table 225-3 UTL_HTTP Constants - HTTP 1.1 Status Codes

REQ Type

Use this PL/SQL record type to represent an HTTP request.

Syntax

TYPE req IS RECORD (
   url           VARCHAR2(32767),
   method        VARCHAR2(64),
   http_version  VARCHAR2(64));

Parameters

Usage Notes

The information returned in REQ from the interface begin_request is for read-only. Changing the field values in the record has no effect on the request.

There are other fields in REQ record type whose names begin with the prefix private_. The fields are private and are intended for use by implementation of theUTL_HTTP package. You should not modify the fields.

REQUEST_CONTEXT_KEY Type

This type is used to represent the key to a request context. A request context is a context that holds a private wallet and cookie table to make a HTTP request. This private wallet and cookie table, unlike the session-wide ones maintained in the package, will not be shared with other HTTP requests within the database session.

Syntax

SUBTYPE request_context_key IS PLS_INTEGER;

Usage Notes

To provide enhanced security, UTL_HTTP allows PL/SQL programs to create request contexts. A request context is a private context that holds a wallet and a cookie table that will not be shared with other programs in the same database session when making HTTP requests and receiving HTTP responses. PL/SQL programs should use request contexts when they need to use wallets or cookies that contain sensitive information such as authentication credentials.

RESP Type

This PL/SQL record type is used to represent an HTTP response.

Syntax

TYPE resp IS RECORD (
   status_code    PLS_INTEGER,
   reason_phrase  VARCHAR2(256),
   http_version   VARCHAR2(64));

Parameters

Usage Notes

The information returned in RESP from the interface GET_RESPONSE is read-only. There are other fields in the RESP record type whose names begin with the prefixprivate_. The fields are private and are intended for use by implementation of the UTL_HTTP package. You should not modify the fields.

COOKIE and COOKIE_TABLE Types

The COOKIE type is the PL/SQL record type that represents an HTTP cookie. The COOKIE_TABLE type is a PL/SQL index-by-table type that represents a collection of HTTP cookies.

Syntax

TYPE cookie IS RECORD (
   name  VARCHAR2(256),
   value  VARCHAR2(1024),
   domain  VARCHAR2(256),
   expire  TIMESTAMP WITH TIME ZONE,
   path  VARCHAR2(1024),
   secure  BOOLEAN,
   version  PLS_INTEGER,
   comment  VARCHAR2(1024));

TYPE cookie_table IS TABLE OF cookie INDEX BY binary_integer;

Fields of COOKIE Record Type

Table 225-6 shows the fields for the COOKIE and COOKIE_TABLE record types.

Usage Notes

PL/SQL programs do not usually examine or change the cookie information stored in the UTL_HTTP package. The cookies are maintained by the package transparently. They are maintained inside the UTL_HTTP package, and they last for the duration of the database session only. PL/SQL applications that require cookies to be maintained beyond the lifetime of a database session can read the cookies using GET_COOKIES, store them persistently in a database table, and re-store the cookies back in the package using ADD_COOKIES in the next database session. All the fields in the cookie record, except for the comment field, must be stored. Do not alter the cookie information, which can result in an application error in the Web server or compromise the security of the PL/SQL and the Web server applications. See "Retrieving and Restoring Cookies".

CONNECTION Type

Use the PL/SQL record type to represent the remote hosts and TCP/IP ports of a network connection that is kept persistent after an HTTP request is completed, according to the HTTP 1.1 protocol specification. The persistent network connection may be reused by a subsequent HTTP request to the same host and port. The subsequent HTTP request may be completed faster because the network connection latency is avoided. connection_table is a PL/SQL table of connection.

For a direct HTTP persistent connection to a Web server, the host and port fields contain the host name and TCP/IP port number of the Web server. Theproxy_host and proxy_port fields are not set. For an HTTP persistent connection that was previously used to connect to a Web server using a proxy, theproxy_host and proxy_port fields contain the host name and TCP/IP port number of the proxy server. The host and port fields are not set, which indicates that the persistent connection, while connected to a proxy server, is not bound to any particular target Web server. An HTTP persistent connection to a proxy server can be used to access any target Web server that is using a proxy.

The SSL field indicates if Secured Socket Layer (SSL) is being used in an HTTP persistent connection. An HTTPS request is an HTTP request made over SSL. For an HTTPS (SSL) persistent connection connected using a proxy, the host and port fields contain the host name and TCP/IP port number of the target HTTPS Web server and the fields will always be set. An HTTPS persistent connection to an HTTPS Web server using a proxy server can only be reused to make another request to the same target Web server.

Syntax

TYPE connection IS RECORD (
   host  VARCHAR2(256),
   port  PLS_INTEGER,
   proxy_host  VARCHAR2(256),
   proxy_port  PLS_INTEGER,
   ssl  BOOLEAN);

TYPE connection_table IS TABLE OF connection INDEX BY BINARY_INTEGER;

Operational Flow

The UTL_HTTP package provides access to the HTTP protocol. The interfaces must be called in the order shown in Figure 225-1, or an exception will be raised.

Figure 225-1 Flow of the Core UTL_HTTP Package

Description of "Figure 225-1 Flow of the Core UTL_HTTP Package"

The following can be called at any time:

• Non-protocol interfaces that manipulate cookies

  • GET_COOKIE_COUNT

  • GET_COOKIES

  • ADD_COOKIES

  • CLEAR_COOKIES

• Persistent connections

  • GET_PERSISTENT_CONN_COUNT

  • GET_PERSISTENT_CONNS

  • CLOSE_PERSISTENT_CONN

  • CLOSE_PERSISTENT_CONNS

• Interfaces that manipulate attributes and configurations of the UTL_HTTP package in the current session

  • SET_PROXY

  • GET_PROXY

  • SET_COOKIE_SUPPORT

  • GET_COOKIE_SUPPORT

  • SET_FOLLOW_REDIRECT

  • GET_FOLLOW_REDIRECT

  • SET_BODY_CHARSET

  • GET_BODY_CHARSET

  • SET_PERSISTENT_CONN_SUPPORT

  • GET_PERSISTENT_CONN_SUPPORT

  • SET_DETAILED_EXCP_SUPPORT

  • GET_DETAILED_EXCP_SUPPORT

  • SET_WALLET

  • SET_TRANSFER_TIMEOUT

  • GET_TRANSFER_TIMEOUT

• Interfaces that retrieve the last detailed exception code and message UTL_HTTP package in the current session

  • GET_DETAILED_SQLCODE

  • GET_DETAILED_SQLERRM

    NOTE:

    Some of the request and response interfaces bear the same name as the interface that manipulates the attributes and configurations of the package in the current session. They are overloaded versions of the interface that manipulate a request or a response.

Simple HTTP Fetches

REQUEST and REQUEST_PIECES take a string uniform resource locator (URL), contact that site, and return the data (typically HTML) obtained from that site.

You should not expect REQUEST or REQUEST_PIECES to succeed in contacting a URL unless you can contact that URL by using a browser on the same machine (and with the same privileges, environment variables, and so on.)

If REQUEST or REQUEST_PIECES fails (for example, if it raises an exception, or if it returns an HTML-formatted error message, but you believe that the URL argument is correct), then try contacting that same URL with a browser to verify network availability from your machine. You may have a proxy server set in your browser that needs to be set with each REQUEST or REQUEST_PIECES call using the optional proxy parameter.

HTTP Requests

The HTTP Requests group of subprograms begin an HTTP request, manipulate attributes, and send the request information to the Web server. When a request is created, it inherits the default settings of the HTTP cookie support, follow-redirect, body character set, persistent-connection support, and transfer timeout of the current session. The settings can be changed by calling the request interface.

HTTP Responses

The HTTP Responses group of subprograms manipulate an HTTP response obtained from GET_RESPONSE and receive response information from the Web server. When a response is created for a request, it inherits settings of the HTTP cookie support, follow-redirect, body character set, persistent-connection support, and transfer timeout from the request. Only the body character set can be changed by calling the response interface.

HTTP Cookies

The UTL_HTTP package provides subprograms to manipulate HTTP cookies.

HTTP Persistent Connections

The UTL_HTTP package provides subprograms to manipulate persistent connections.

Error Conditions

The UTL_HTTP package provides subprograms to retrieve error information.

Session Settings

Session settings manipulate the configuration and default behavior of UTL_HTTP when HTTP requests are executed within a database user session. When a request is created, it inherits the default settings of the HTTP cookie support, follow-redirect, body character set, persistent-connection support, and transfer timeout of the current session. Those settings can be changed later by calling the request interface. When a response is created for a request, it inherits those settings from the request. Only the body character set can be changed later by calling the response interface.

Request Context

The UTL_HTTP package maintains a common wallet and cookie table within the database session that all HTTP requests and responses share. This makes it easy for users to share the wallet or to maintain application state in the cookies within the session. However, if an application stores private information in the wallet or in the cookies that it does not want to share with other applications in the same database session, it may define a request context to hold its own wallet and cookie table and use this request context to make HTTP requests.

External Password Store

The UTL_HTTP package allows HTTP password credentials to be stored in an Oracle wallet‘s external password store. The external password store provides an easy but secure storage for passwords and frees the application developers from the need to maintain their own storage.

Table 225-7 UTL_HTTP Exceptions

NOTE:

General Usage

SET SERVEROUTPUT ON SIZE 40000
  
DECLARE
  req   UTL_HTTP.REQ;
  resp  UTL_HTTP.RESP;
  value VARCHAR2(1024);
BEGIN
  UTL_HTTP.SET_PROXY(‘proxy.my-company.com‘, ‘corp.my-company.com‘);
  req := UTL_HTTP.BEGIN_REQUEST(‘http://www-hr.corp.my-company.com‘);
  UTL_HTTP.SET_HEADER(req, ‘User-Agent‘, ‘Mozilla/4.0‘);
  resp := UTL_HTTP.GET_RESPONSE(req);
  LOOP
    UTL_HTTP.READ_LINE(resp, value, TRUE);
    DBMS_OUTPUT.PUT_LINE(value);
  END LOOP;
  UTL_HTTP.END_RESPONSE(resp);
EXCEPTION
  WHEN UTL_HTTP.END_OF_BODY THEN
    UTL_HTTP.END_RESPONSE(resp);
END;

Retrieving HTTP Response Headers

SET SERVEROUTPUT ON SIZE 40000
  
DECLARE
  req   UTL_HTTP.REQ;
  resp  UTL_HTTP.RESP;
  name  VARCHAR2(256);
  value VARCHAR2(1024);
BEGIN
  UTL_HTTP.SET_PROXY(‘proxy.my-company.com‘, ‘corp.my-company.com‘);
  req := UTL_HTTP.BEGIN_REQUEST(‘http://www-hr.corp.my-company.com‘);
  UTL_HTTP.SET_HEADER(req, ‘User-Agent‘, ‘Mozilla/4.0‘);
  resp := UTL_HTTP.GET_RESPONSE(req);
  DBMS_OUTPUT.PUT_LINE(‘HTTP response status code: ‘ || resp.status_code);
  DBMS_OUTPUT.PUT_LINE(‘HTTP response reason phrase: ‘ || resp.reason_phrase);
  FOR i IN 1..UTL_HTTP.GET_HEADER_COUNT(resp) LOOP
    UTL_HTTP.GET_HEADER(resp, i, name, value);
    DBMS_OUTPUT.PUT_LINE(name || ‘: ‘ || value);
  END LOOP;
  UTL_HTTP.END_RESPONSE(resp);
END;

Handling HTTP Authentication

SET serveroutput ON SIZE 40000
  
CREATE OR REPLACE PROCEDURE get_page (url      IN VARCHAR2,
                                      username IN VARCHAR2 DEFAULT NULL,
                                      password IN VARCHAR2 DEFAULT NULL,
                                      realm    IN VARCHAR2 DEFAULT NULL) AS
  req       UTL_HTTP.REQ;
  resp      UTL_HTTP.RESP;
  my_scheme VARCHAR2(256);
  my_realm  VARCHAR2(256);
  name      VARCHAR2(256);
  value     VARCHAR2(256);
BEGIN
  -- Turn off checking of status code. We will check it by ourselves.
  UTL_HTTP.SET_RESPONSE_ERROR_CHECK(FALSE);
  req := UTL_HTTP.BEGIN_REQUEST(url);
  IF (username IS NOT NULL) THEN
    UTL_HTTP.SET_AUTHENTICATION(req, username, password); -- Use HTTP Basic Authen. Scheme
  END IF;
  resp := UTL_HTTP.GET_RESPONSE(req);
  IF (resp.status_code = UTL_HTTP.HTTP_UNAUTHORIZED) THEN
    UTL_HTTP.GET_AUTHENTICATION(resp, my_scheme, my_realm, FALSE);
    DBMS_OUTPUT.PUT_LINE(‘Web proxy server is protected.‘);
    DBMS_OUTPUT.PUT(‘Please supplied the required ‘ || my_scheme || ‘ authentication username/password for realm ‘ || my_realm || ‘ for the proxy server.‘);
    UTL_HTTP.END_RESPONSE(resp);
    RETURN;
  ELSIF (resp.status_code = UTL_HTTP.HTTP_PROXY_AUTH_REQUIRED) THEN
    UTL_HTTP.GET_AUTHENTICATION(resp, my_scheme, my_realm, TRUE);
    DBMS_OUTPUT.PUT_LINE(‘Web page ‘ || url || ‘ is protected.‘);
    DBMS_OUTPUT.PUT(‘Please supplied the required ‘ || my_scheme || ‘ authentication username/password for realm ‘ || my_realm || ‘ for the Web page.‘);
    UTL_HTTP.END_RESPONSE(resp);
    RETURN;
  END IF;
  FOR i IN 1..UTL_HTTP.GET_HEADER_COUNT(resp) LOOP
    UTL_HTTP.GET_HEADER(resp, i, name, value);
    DBMS_OUTPUT.PUT_LINE(name || ‘: ‘ || value);
  END LOOP;
  UTL_HTTP.END_RESPONSE(resp);
END;

Retrieving and Restoring Cookies

CREATE TABLE my_cookies (
    session_id  INTEGER,
    name        VARCHAR2(256),
    value       VARCHAR2(1024),
    domain      VARCHAR2(256),
    expire      DATE,
    path        VARCHAR2(1024),
    secure      VARCHAR2(1),
    version     INTEGER);

CREATE SEQUENCE session_id;
SET SERVEROUTPUT ON SIZE 40000

REM Retrieve cookies from UTL_HTTP
CREATE OR REPLACE FUNCTION save_cookies RETURN PLS_INTEGER AS
  cookies        UTL_HTTP.COOKIE_TABLE;
  my_session_id  PLS_INTEGER;
  secure         VARCHAR2(1);
BEGIN
  /* assume that some cookies have been set in previous HTTP requests. */
  UTL_HTTP.GET_COOKIES(cookies);
  SELECT session_id.nextval INTO my_session_id FROM DUAL;
  FOR i in 1..cookies.count LOOP
    IF (cookies(i).secure) THEN
      secure := ‘Y‘;
    ELSE
      secure := ‘N‘;
    END IF;
    INSERT INTO my_cookies
    VALUES (my_session_id, cookies(i).name, cookies(i).value,
            cookies(i).domain,
            cookies(i).expire, cookies(i).path, secure, cookies(i).version);
  END LOOP;
  RETURN my_session_id;
END;
/

REM Retrieve cookies from UTL_HTTP
CREATE OR REPLACE PROCEDURE restore_cookies (this_session_id IN PLS_INTEGER)
AS
  cookies        UTL_HTTP.COOKIE_TABLE;
  cookie         UTL_HTTP.COOKIE;
  i              PLS_INTEGER := 0;
  CURSOR c (c_session_id PLS_INTEGER) IS
    SELECT * FROM my_cookies WHERE session_id = c_session_id;
BEGIN
  FOR r IN c(this_session_id) LOOP
    i := i + 1;
    cookie.name     := r.name;
    cookie.value    := r.value;
    cookie.domain   := r.domain;
    cookie.expire   := r.expire;
    cookie.path     := r.path;
    IF (r.secure = ‘Y‘) THEN
      cookie.secure := TRUE;
    ELSE
      cookie.secure := FALSE;
    END IF;
    cookie.version := r.version;
    cookies(i) := cookie;
  END LOOP;
  UTL_HTTP.CLEAR_COOKIES;
  UTL_HTTP.ADD_COOKIES(cookies);
END;
/

Making HTTP Request with Private Wallet and Cookie Table

SET SERVEROUTPUT ON SIZE 40000
 
CREATE OR REPLACE PROCEDURE DISPLAY_PAGE(url IN VARCHAR2) AS
  request_context UTL_HTPT.REQUEST_CONTEXT_KEY;
  req             UTL_HTTP.REQ;
  resp            UTL_HTTP.RESP;
  data            VARCHAR2(1024);
 
BEGIN

  -- Create a request context with its wallet and cookie table
  request_context := UTL_HTTP.CREATE_REQUEST_CONTEXT(
                       wallet_path          => ‘file:/oracle/wallets/test/wallet‘,
                       wallet_password      => ‘******‘,
                       enable_cookies       => TRUE,
                       max_cookies          => 300,
                       max_cookies_per_site => 20);
 
  -- Make a HTTP request using the private wallet and cookie
  -- table in the request context
  req := UTL_HTTP.BEGIN_REQUEST(
           url             => url,
           request_context => request_context);
  resp := UTL_HTTP.GET_RESPONSE(req);
 
  BEGIN
    LOOP
       UTL_HTTP.READ_TEXT(resp, data);
       DBMS_OUTPUT.PUT(data);
    END LOOP;
  EXCEPTION
      WHEN UTL_HTTP.END_OF_BODY THEN
         UTL_HTTP.END_RESPONSE(resp); 
  END;
 
  -- Destroy the request context
  UTL_HTTP.DESTROY_REQUEST_CONTEXT(request_context);
 
END;
 
BEGIN
  DISPLAY_PAGE(‘https://www.example.com/‘);
END;
/

Table 225-8 UTL_HTTP Subprograms—Simple HTTP Fetches in a Single Call

Table 225-9 UTL_HTTP Subprograms—Session Settings

Table 225-10 UTL_HTTP Subprograms—HTTP Requests

Table 225-11 UTL_HTTP Subprograms—HTTP Request Contexts

Table 225-12 UTL_HTTP Subprograms—HTTP Responses

Table 225-13 UTL_HTTP Subprograms—HTTP Cookies

Table 225-14 UTL_HTTP Subprograms—HTTP Persistent Connections

Table 225-15 UTL_HTTP Subprograms—Error Conditions

See Also:

Syntax

UTL_HTTP.ADD_COOKIES (
   cookies          IN  cookie_table,
   request_context  IN  request_context_key DEFAULT NULL);

Parameters

Usage Notes

The cookies that the package currently maintains are not cleared before new cookies are added.

See Also:

Syntax

UTL_HTTP.BEGIN_REQUEST (
   url               IN  VARCHAR2,
   method            IN  VARCHAR2 DEFAULT ‘GET‘,
   http_version      IN  VARCHAR2 DEFAULT NULL,
   request_context   IN  request_context_key DEFAULT NULL)
RETURN req;

Parameters

Usage Notes

• The URL passed as an argument to this function is not examined for illegal characters, such as spaces, according to URL specification RFC 2396. You should escape those characters with the UTL_URL package to return illegal and reserved characters. URLs should consist of US-ASCII characters only. See Chapter 239, "UTL_URL" for a list of legal characters in URLs. Note that URLs should consist of US-ASCII characters only. The use of non-US-ASCII characters in a URL is generally unsafe.

• BEGIN_REQUEST can send a URL whose length is up to 32767 bytes. However, different Web servers impose different limits on the length of the URL they can accept. This limit is often about 4000 bytes. If this limit is exceeded, the outcome will depend on the Web server. For example, a Web server might simply drop the HTTP connection without returning a response of any kind. If this happens, a subsequent invocation of the GET_RESPONSE Function will raise the PROTOCOL_ERROR exception.

  A URL will be long when its QUERY_STRING (that is, the information that follows the question mark (?)) is long. In general, it is better to send this parameterization in the body of the request using the POST method.

  req := UTL_HTTP.BEGIN_REQUEST (url=>the_url, method=>‘POST‘);
  UTL_HTTP.SET_HEADER (r      =>  req, 
                       name   =>  ‘Content-Type‘,   
                       value  =http://www.mamicode.com/>  ‘application/x-www-form-urlencoded‘);"background-color:rgb(255,255,102)">UTL_HTTP.SET_HEADER (r      =>   req, 
                       name   =>   ‘Content-Length‘, 
                       value  =http://www.mamicode.com/>‘  ‘);"background-color:rgb(255,255,102)">UTL_HTTP.WRITE_TEXT (r      =>   req, 
                       data   =http://www.mamicode.com/>   ‘p1 = value1&p2=value2...‘);"background-color:rgb(255,255,102)">UTL_HTTP.GET_RESPONSE 
                       (r     =>   req);
  ...
  

  The programmer must determine whether a particular Web server may, or may not, accept data provided in this way.

• An Oracle wallet must be set before accessing Web servers over HTTPS. See the SET_WALLET Procedure procedure on how to set up an Oracle wallet. To use SSL client authentication, the client certificate should be stored in the wallet and the caller must have the use-client-certificatesprivilege on the wallet. See "Managing Fine-grained Access to External Network Services" in the Oracle Database Security Guide to grant the privilege.

• To connect to the remote Web server directly, or indirectly through a HTTP proxy, the UTL_HTTP must have the connect ACL privilege to the remote Web server host or the proxy host respectively.

See Also:

Syntax

UTL_HTTP.CLEAR_COOKIES (
   request_context  IN  request_context_key DEFAULT NULL);

Parameters

See Also:

Syntax

UTL_HTTP.CLOSE_PERSISTENT_CONN (
   conn  IN connection);

Parameters

See Also:

Syntax

UTL_HTTP.CLOSE_PERSISTENT_CONNS (
   host        IN VARCHAR2 DEFAULT NULL,
   port        IN PLS_INTEGER DEFAULT NULL,
   proxy_host  IN VARCHAR2 DEFAULT NULL,
   proxy_port  IN PLS_INTEGER DEFAULT NULL,
   ssl         IN BOOLEAN DEFAULT NULL);

Parameters

Usage Notes

Connections to the same Web server at different TCP/IP ports are counted individually. The host names of the Web servers are identified as specified in the URL of the original HTTP requests. Therefore, fully qualified host names with domain names will be counted differently from the host names without domain names.

Note that the use of a NULL value in a parameter when this procedure is called means that the caller does not care about its value when the package decides which persistent connection to close. If you want a NULL value in a parameter to match only a NULL value of the parameter of a persistent connection (which is when you want to close a specific persistent connection), you should use the CLOSE_PERSISTENT_CONN procedure that closes a specific persistent connection.

See Also:

Syntax

UTL_HTTP.CREATE_REQUEST_CONTEXT (
 wallet_path          IN VARCHAR2 DEFAULT NULL,
 wallet_password      IN VARCHAR2 DEFAULT NULL,
 enable_cookies       IN BOOLEAN  DEFAULT TRUE,
 max_cookies          IN PLS_INTEGER DEFAULT 300,
 max_cookies_per_site IN PLS_INTEGER DEFAULT 20)
RETURN request_context_key;

Parameters

Return Values

The request context created.

Examples

DECLARE
  request_context  UTL_HTTP.REQUEST_CONTEXT_KEY;
  req              utl_http.req;
BEGIN
  request_context := UTL_HTTP.CREATE_REQUEST_CONTEXT(
       wallet_path          => ‘file:/oracle/wallets/test_wallets‘,
       wallet_password      => NULL,
       enable_cookies       => TRUE,
       max_cookies          => 300,
       max_cookies_per_site => 20);
  req := UTL_HTTP.BEGIN_REQUEST(
       url                  => ‘http://www.example.com/‘,
       request_context      => request_context);
END;

See Also:

Syntax

UTL_HTTP.DESTROY_REQUEST_CONTEXT (
   request_context    request_context_key);

Parameters

Examples

DECLARE
  request_context  UTL_HTTP.REQUEST_CONTEXT_KEY;
BEGIN
  request_context := UTL_HTTP.CREATE_REQUEST_CONTEXT(…);
  …
  UTL_HTTP.DESTROY_REQUEST_CONTEXT(request_context);
END;

See Also:

Syntax

UTL_HTTP.END_REQUEST (
   r  IN OUT NOCOPY req);

Parameters

See Also:

Syntax

UTL_HTTP.END_RESPONSE (
   r  IN OUT NOCOPY resp);

Parameters

See Also:

Syntax

UTL_HTTP.GET_AUTHENTICATION(
   r          IN OUT NOCOPY resp,
   scheme     OUT VARCHAR2,
   realm      OUT VARCHAR2,
   for_proxy  IN BOOLEAN  DEFAULT FALSE);

Parameters

Usage Notes

When a Web client is unaware that a document is protected, at least two HTTP requests are required for the document to be retrieved. In the first HTTP request, the Web client makes the request without supplying required authentication information; so the request is denied. The Web client can determine the authentication information required for the request to be authorized by calling GET_AUTHENTICATION. The Web client makes the second request and supplies the required authentication information with SET_AUTHORIZATION. If the authentication information can be verified by the Web server, the request will succeed and the requested document is returned. Before making the request, if the Web client knows that authentication information is required, it can supply the required authentication information in the first request, thus saving an extra request.

See Also:

Syntax

UTL_HTTP.GET_BODY_CHARSET (
   charset  OUT NOCOPY VARCHAR2);

Parameters

See Also:

Syntax

UTL_HTTP.GET_COOKIE_COUNT (
   request_context  IN  request_context_key DEFAULT NULL) 
 RETURN PLS_INTEGER;

Parameters

See Also:

Syntax

UTL_HTTP.GET_COOKIE_SUPPORT (
   enable                OUT BOOLEAN,
   max_cookies           OUT PLS_INTEGER,
   max_cookies_per_site  OUT PLS_INTEGER);

Parameters

See Also:

Syntax

UTL_HTTP.GET_COOKIES (
   cookies          IN  OUT NOCOPY cookie_table,
   request_context  IN             request_context_key DEFAULT NULL);

Parameters

See Also:

Syntax

UTL_HTTP.GET_DETAILED_EXCP_SUPPORT (
   enable  OUT BOOLEAN);

Parameters

See Also:

Syntax

UTL_HTTP.GET_DETAILED_SQLCODE 
RETURN PLS_INTEGER;

See Also:

Syntax

UTL_HTTP.GET_DETAILED_SQLERRM 
RETURN VARCHAR2;

See Also:

Syntax

UTL_HTTP.GET_FOLLOW_REDIRECT (
   max_redirects  OUT PLS_INTEGER);

Parameters

See Also:

Syntax

UTL_HTTP.GET_HEADER (
   r      IN OUT NOCOPY resp,
   n      IN PLS_INTEGER,
   name   OUT NOCOPY VARCHAR2,
   value  OUT NOCOPY VARCHAR2);

Parameters

Usage Notes

If the response body returned by the remote Web server is encoded in chunked transfer encoding format, the trailer headers that are returned at the end of the response body will be added to the response, and the response header count will be updated. You can retrieve the additional headers after the end of the response body is reached and before you end the response.

See Also:

Syntax

UTL_HTTP.GET_HEADER_BY_NAME(
   r      IN OUT NOCOPY resp,
   name   IN VARCHAR2,
   value  OUT NOCOPY VARCHAR2,
   n      IN PLS_INTEGER DEFAULT 1);

Parameters

Usage Notes

If the response body returned by the remote Web server is encoded in chunked transfer encoding format, the trailer headers that are returned at the end of the response body will be added to the response, and the response header count will be updated. You can retrieve the additional headers after the end of the response body is reached and before you end the response.

See Also:

Syntax

UTL_HTTP.GET_HEADER_COUNT (
   r  IN OUT NOCOPY resp) 
RETURN PLS_INTEGER;

Parameters

Usage Notes

If the response body returned by the remote Web server is encoded in chunked transfer encoding format, the trailer headers that are returned at the end of the response body will be added to the response, and the response header count will be updated. You can retrieve the additional headers after the end of the response body is reached and before you end the response.

See Also:

Syntax

UTL_HTTP.GET_PERSISTENT_CONN_COUNT 
RETURN PLS_INTEGER;

Usage Notes

Connections to the same Web server at different TCP/IP ports are counted individually. The host names of the Web servers are identified as specified in the URL of the original HTTP requests. Therefore, fully qualified host names with domain names will be counted differently from the host names without domain names.

Syntax

UTL_HTTP.GET_PERSISTENT_CONN_SUPPORT (
   enable     OUT BOOLEAN,
   max_conns  OUT PLS_INTEGER);

Parameters

See Also:

Syntax

UTL_HTTP.get_persistent_conns (
   connections  IN OUT NOCOPY connection_table);

Parameters

Usage Notes

Connections to the same Web server at different TCP/IP ports are counted individually. The host names of the Web servers are identified as specified in the URL of the original HTTP requests. Therefore, fully qualified host names with domain names will be counted differently from the host names without domain names.

See Also:

Syntax

UTL_HTTP.GET_PROXY (
   proxy             OUT NOCOPY VARCHAR2, 
   no_proxy_domains  OUT NOCOPY VARCHAR2);

Parameters

See Also:

Syntax

UTL_HTTP.GET_RESPONSE (
   r                       IN OUT NOCOPY req,
   return_info_response    IN BOOLEAN DEFAULT FALSE) 
RETURN resp;

Parameters

Exceptions

• When detailed-exception is disabled:

  ORA-29273 REQUEST_FAILED - the request fails to execute. Use the GET_DETAILED_EXCP_SUPPORT Procedure and the GET_DETAILED_SQLERRM Functionto get the detailed error message.

• When detailed-exception is enabled:

  ORA-29261 BAD_ARGUMENT - some arguments passed are not valid

• When response error check is enabled:

  ORA-29268 HTTP_CLIENT_ERROR - the response code is in 400 range

  ORA-29269 HTTP_SERVER_ERROR - the response code is in 500 range

Usage Notes

• The request will be ended when this functions returns regardless of whether an exception is raised or not. There is no need to invoke theEND_REQUEST Procedure.

• If URL redirection occurs, the URL and method fields in the req record will be updated to the last redirected URL and the method used to access the URL.

Examples

In certain situations (initiated by the HTTP client or not), the HTTP server may return a 1xx informational response. The user who does not expect such a response may indicate to GET_RESPONSE to ignore the response and proceed to receive the regular response. In the case when the user expects such a response, the user can indicate to GET_RESPONSE to return the response.

For example, when a user is issuing a HTTP POST request with a large request body, the user may want to check with the HTTP server to ensure that the server will accept the request before sending the data. To do so, the user will send the additional EXPECT: 100-CONTINUE request header, and check for 100 CONTINUEresponse from the server before proceeding to send the request body. Then, the user will get the regular HTTP response.

The following code example illustrates this:

DECLARE
 data  VARCHAR2(1024) := ‘...‘;
 req   utl_http.req;
 resp  utl_http.resp;
BEGIN
   
 req := utl_http.begin_request(‘http://www.acme.com/receiver‘, ‘POST‘);
 utl_http.set_header(req, ‘Content-Length‘, length(data));
 -- Ask HTTP server to return "100 Continue" response
 utl_http.set_header(req, ‘Expect‘, ‘100-continue‘);
 resp := utl_http.get_response(req, TRUE);
   
 -- Check for and dispose "100 Continue" response
 IF (resp.status_code <> 100) THEN
   utl_http.end_response(resp);
   raise_application_error(20000, ‘Request rejected‘);
 END IF;
 utl_http.end_response(resp);
   
 -- Now, send the request body
 utl_http.write_text(req, data);
 
 -- Get the regular response
 resp := utl_http.get_response(req);
 utl_http.read_text(resp, data);
   
 utl_http.end_response(resp);
   
END;

See Also:

Syntax

UTL_HTTP.GET_RESPONSE_ERROR_CHECK (
   enable  OUT BOOLEAN);

Parameters

See Also:

Syntax

UTL_HTTP.GET_TRANSFER_TIMEOUT (
   timeout  OUT PLS_INTEGER);

Parameters

See Also:

Syntax

UTL_HTTP.READ_LINE(
   r            IN OUT NOCOPY resp,
   data         OUT NOCOPY  VARCHAR2 CHARACTER SET ANY_CS,
   remove_crlf  IN  BOOLEAN DEFAULT FALSE);

Parameters

Usage Notes

The UTL_HTTP package supports HTTP 1.1 chunked transfer-encoding. When the response body is returned in chunked transfer-encoding format as indicated in the response header, the package automatically decodes the chunks and returns the response body in de-chunked format.

If transfer timeout is set in the request of this response, read_line waits for each data packet to be ready to read until timeout occurs. If it occurs, this procedure stops reading and returns all the data read successfully. If no data is read successfully, the transfer_timeout exception is raised. The exception can be handled and the read operation can be retried later.

If a partial multibyte character is found at the end of the response body, read_line stops reading and returns all the complete multibyte characters read successfully. If no complete character is read successfully, the partial_multibyte_char exception is raised. The exception can be handled and the bytes of that partial multibyte character can be read as binary by the read_raw procedure. If a partial multibyte character is seen in the middle of the response body because the remaining bytes of the character have not arrived and read timeout occurs, the transfer_timeout exception is raised instead. The exception can be handled and the read operation can be retried later.

When the Content-Type response header specifies the character set of the response body and the character set is unknown or unsupported by Oracle, the "ORA-01482: unsupported character set" exception is raised if you try to read the response body as text. You can either read the response body as binary using the READ_RAW procedure, or set the character set of the response body explicitly using the SET_BODY_CHARSET procedure and read the response body as text again.

See Also:

Syntax

UTL_HTTP.READ_RAW(
   r     IN OUT NOCOPY resp,
   data  OUT NOCOPY RAW,
   len   IN PLS_INTEGER DEFAULT NULL);

Parameters

Usage Notes

The UTL_HTTP package supports HTTP 1.1 chunked transfer-encoding. When the response body is returned in chunked transfer-encoding format as indicated in the response header, the package automatically decodes the chunks and returns the response body in de-chunked format.

If transfer timeout is set in the request of this response, read_raw waits for each data packet to be ready to read until timeout occurs. If it occurs, read_rawstops reading and returns all the data read successfully. If no data is read successfully, the transfer_timeout exception is raised. The exception can be handled and the read operation can be retried later.

See Also:

Syntax

UTL_HTTP.READ_TEXT(
   r     IN OUT NOCOPY resp,
   data  OUT NOCOPY VARCHAR2 CHARACTER SET ANY_CS,
   len   IN PLS_INTEGER DEFAULT NULL);

Parameters

Usage Notes

The UTL_HTTP package supports HTTP 1.1 chunked transfer-encoding. When the response body is returned in chunked transfer-encoding format as indicated in the response header, the package automatically decodes the chunks and returns the response body in de-chunked format.

If transfer timeout is set in the request of this response, read_text waits for each data packet to be ready to read until timeout occurs. If it occurs, this procedure stops reading and returns all the data read successfully. If no data is read successfully, the transfer_timeout exception is raised. The exception can be handled and the read operation can be retried later.

If a partial multibyte character is found at the end of the response body, read_text stops reading and returns all the complete multibyte characters read successfully. If no complete character is read successfully, the partial_multibyte_char exception is raised. The exception can be handled and the bytes of that partial multibyte character can be read as binary by the read_raw procedure. If a partial multibyte character is seen in the middle of the response body because the remaining bytes of the character have not arrived and read timeout occurs, the transfer_timeout exception is raised instead. The exception can be handled and the read operation can be retried later.

When the Content-Type response header specifies the character set of the response body and the character set is unknown or unsupported by Oracle, the "ORA-01482: unsupported character set" exception is raised if you try to read the response body as text. You can either read the response body as binary using the READ_RAW procedure, or set the character set of the response body explicitly using the SET_BODY_CHARSET procedure and read the response body as text again.

See Also:

Syntax

UTL_HTTP.REQUEST (
   url              IN VARCHAR2,
   proxy            IN VARCHAR2 DEFAULT NULL, 
   wallet_path      IN VARCHAR2 DEFAULT NULL,
   wallet_password  IN VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Pragmas

pragma restrict_references (request, wnds, rnds, wnps, rnps);

Parameters

Return Values

The return type is a string of length 2000 or less, which contains up to the first 2000 bytes of the HTML result returned from the HTTP request to the argument URL.

Exceptions

INIT_FAILED
REQUEST_FAILED

Usage Notes

The URL passed as an argument to this function is not examined for illegal characters, for example, spaces, according to URL specification RFC 2396. The caller should escape those characters with the UTL_URL package. See the comments of the package for the list of legal characters in URLs. Note that URLs should consist of US-ASCII characters only. The use of non-US-ASCII characters in a URL is generally unsafe.

Please see the documentation of the function SET_WALLET on the use of an Oracle wallet, which is required for accessing HTTPS Web servers.

Unless response error check is turned on, this function does not raise an exception when a 4xx or 5xx response is received from the Web server. Instead, it returns the formatted error message from the Web server:

<HTML> 
<HEAD> 
<TITLE>Error Message</TITLE> 
</HEAD> 
<BODY> 
<H1>Fatal Error 500</H1> 
Can‘t Access Document:  http://home.nothing.comm. 
<P> 
<B>Reason:</B> Can‘t locate remote host:  home.nothing.comm. 
<P> 
<P><HR> 
<ADDRESS><A HREF=http://www.mamicode.com/"http://www.w3.org"> >

Examples

SQL> SELECT UTL_HTTP.REQUEST(‘http://www.my-company.com/‘) FROM DUAL;
UTL_HTTP.REQUEST(‘HTTP://WWW.MY-COMPANY.COM/‘)                         
<html>
<head><title>My Company Home Page</title>
<!--changed Jan. 16, 19
1 row selected.

If you are behind a firewall, include the proxy parameter. For example, from within the Oracle firewall, where there might be a proxy server named www-proxy.my-company.com:

SQLPLUS> SELECT 
UTL_HTTP.REQUEST(‘http://www.my-company.com‘, ‘www-proxy.us.my-company.com‘) FROM DUAL;

See Also:

Syntax

TYPE html_pieces IS TABLE OF VARCHAR2(2000) INDEX BY BINARY_INTEGER;

UTL_HTTP.REQUEST_PIECES (
   url             IN VARCHAR2,
   max_pieces      IN NATURAL DEFAULT 32767,
   proxy           IN VARCHAR2 DEFAULT NULL,
   wallet_path     IN VARCHAR2 DEFAULT NULL,
   wallet_password IN VARCHAR2 DEFAULT NULL)
RETURN html_pieces;

Pragmas

PRAGMA RESTRICT_REFERENCES (request_pieces, WNDS, RNDS, WNPS, RNPS);

Parameters

Return Values

REQUEST_PIECES returns a PL/SQL table of type UTL_HTTP.HTML_PIECES. Each element of that PL/SQL table is a string of maximum length 2000. The elements of the PL/SQL table returned by REQUEST_PIECES are successive pieces of the data obtained from the HTTP request to that URL.

Exceptions

INIT_FAILED
REQUEST_FAILED

Usage Notes

The URL passed as an argument to this function will not be examined for illegal characters, for example, spaces, according to URL specification RFC 2396. The caller should escape those characters with the UTL_URL package. See the comments of the package for the list of legal characters in URLs. Note that URLs should consist of US-ASCII characters only. The use of non-US-ASCII characters in a URL is generally unsafe.

Each entry of the PL/SQL table (the "pieces") returned by this function may not be filled to their fullest capacity. The function may start filling the data in the next piece before the previous "piece" is totally full.

Please see the documentation of the function SET_WALLET on the use of an Oracle wallet, which is required for accessing HTTPS Web servers.

Unless response error check is turned on, this function does not raise an exception when a 4xx or 5xx response is received from the Web server. Instead, it returns the formatted error message from the Web server:

<HTML> 
<HEAD> 
<TITLE>Error Message</TITLE> 
</HEAD> 
<BODY> 
<H1>Fatal Error 500</H1> 
Can‘t Access Document:  http://home.nothing.comm. 
<P> 
<B>Reason:</B> Can‘t locate remote host:  home.nothing.comm. 
<P> 
<P><HR> 
<ADDRESS><A HREF=http://www.mamicode.com/"http://www.w3.org"> >

Examples

SET SERVEROUTPUT ON 

DECLARE 
   x   UTL_HTTP.HTML_PIECES; 
   len PLS_INTEGER; 
BEGIN 
   x := UTL_HTTP.REQUEST_PIECES(‘http://www.oracle.com/‘, 100); 
   DBMS_OUTPUT.PUT_LINE(x.count || ‘ pieces were retrieved.‘); 
   DBMS_OUTPUT.PUT_LINE(‘with total length ‘); 
   IF x.count < 1 THEN 
      DBMS_OUTPUT.PUT_LINE(‘0‘); 
  ELSE 
   len := 0; 
   FOR i in 1..x.count LOOP 
      len := len + length(x(i)); 
   END LOOP; 
   DBMS_OUTPUT.PUT_LINE(len); 
  END IF; 
END; 
/ 
-- Output 
Statement processed. 
4 pieces were retrieved. 
with total length 
7687 

See Also:

Syntax

UTL_HTTP.SET_AUTHENTICATION(
   r         IN OUT NOCOPY req,
   username  IN VARCHAR2,
   password  IN VARCHAR2,
   scheme    IN VARCHAR2 DEFAULT ‘Basic‘,
   for_proxy IN BOOLEAN  DEFAULT FALSE);

Parameters

Usage Notes

The supported authentication schemes are HTTP basic and Amazon S3 authentication.

See Also:

Syntax

UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET(
   r         IN OUT NOCOPY req,
   alias     IN VARCHAR2,
   scheme    IN VARCHAR2 DEFAULT ‘Basic‘,
   for_proxy IN BOOLEAN  DEFAULT FALSE);

Parameters

Usage Notes

• To use the password credentials in a wallet, the UTL_HTTP user must have the use-passwords privilege on the wallet.

• The supported authentication schemes are HTTP basic and Amazon S3 authentication schemes.

Examples

Creating a wallet and entering username and password in the wallet

> mkstore -wrl /oracle/wallets/test_wallet -create
Enter password: ******
Enter password again: ******
> mkstore –wrl /oracle/wallets/test_wallet –createCredential hr-access jsmith 
Your secret/Password is missing in the command line
Enter your secret/Password: ****
Re-enter your secret/Password: ****
Enter wallet password: ******

Granting the use-passwords privilege on the wallet to a user by the database administrator

BEGIN
  DBMS_NETWORK_ACL_ADMIN.CREATE_ACL(
    acl         => ‘wallet-acl.xml‘, 
    description => ‘Wallet ACL‘,
    principal   => ‘SCOTT‘,
    is_grant    => TRUE,
    privilege   => ‘use-passwords‘);
  DBMS_NETWORK_ACL_ADMIN.ASSIGN_WALLET_acl(
      acl          => ‘wallet-acl.xml‘, 
      wallet_path  => ‘file: /oracle/wallets/test_wallet‘);
END;

Using username and password from the wallet

DECLARE
  req  UTL_HTTP.req;
BEGIN
  UTL_HTTP.SET_WALLET(path => ‘file:/oracle/wallets/test_wallet‘);
  req := UTL_HTTP.BEGIN_REQUEST(…);
  UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET(req, ‘hr-access‘);
  …
END;

See Also:

• HTTP Responses and HTTP Responses Subprograms

• Session Settings and Session Settings Subprograms

Syntax

Sets the default character set of the body of all future HTTP requests when the media type is text and the character set is not specified in the Content-Typeheader. Following the HTTP protocol standard specification, if the media type of a request or a response is text, but the character set information is missing in the Content-Type header, the character set of the request or response body should default to ISO-8859-1. A response created for a request inherits the default body character set of the request instead of the body character set of the current session. The default body character set is ISO-8859-1 in a database user session. The default body character set setting affects only future requests and has no effect on existing requests. After a request is created, the body character set can be changed by using the other SET_BODY_CHARSET procedure that operates on a request:

UTL_HTTP.SET_BODY_CHARSET (
   charset  IN VARCHAR2 DEFAULT NULL);

Sets the character set of the request body when the media type is text but the character set is not specified in the Content-Type header. According to the HTTP protocol standard specification, if the media type of a request or a response is "text" but the character set information is missing in the Content-Type header, the character set of the request or response body should default to "ISO-8859-1". Use this procedure to change the default body character set a request inherits from the session default setting:

UTL_HTTP.SET_BODY_CHARSET(
   r        IN OUT NOCOPY req,
   charset  IN VARCHAR2 DEFAULT NULL);

Sets the character set of the response body when the media type is "text" but the character set is not specified in the Content-Type header. For each the HTTP protocol standard specification, if the media type of a request or a response is "text" but the character set information is missing in the Content-Type header, the character set of the request or response body should default to "ISO-8859-1". Use this procedure to change the default body character set a response inherits from the request:

UTL_HTTP.SET_BODY_CHARSET(
   r        IN OUT NOCOPY resp,
   charset  IN VARCHAR2 DEFAULT NULL);

Parameters

See Also:

• HTTP Requests andHTTP Requests Subprograms

• Session Settings and Session Settings Subprograms

Syntax

Enables or disables support for the HTTP cookies in the request. Use this procedure to change the cookie support setting a request inherits from the session default setting:

UTL_HTTP.SET_COOKIE_SUPPORT(
   r       IN OUT NOCOPY REQ,
   enable  IN BOOLEAN DEFAULT TRUE);

Sets whether or not future HTTP requests will support HTTP cookies, and the maximum number of cookies maintained in the current database user session:

UTL_HTTP.SET_COOKIE_SUPPORT (
   enable       IN BOOLEAN,
   max_cookies  IN PLS_INTEGER DEFAULT 300,
   max_cookies_per_site  IN PLS_INTEGER DEFAULT 20);

Parameters

Usage Notes

If cookie support is enabled for an HTTP request, all cookies saved in the current session and applicable to the request are returned to the Web server in the request in accordance with HTTP cookie specification standards. Cookies set in the response to the request are saved in the current session for return to the Web server in the subsequent requests if cookie support is enabled for those requests. If the cookie support is disabled for an HTTP request, no cookies are returned to the Web server in the request and the cookies set in the response to the request are not saved in the current session, although the Set-CookieHTTP headers can still be retrieved from the response.

Cookie support is enabled by default for all HTTP requests in a database user session. The default setting of the cookie support (enabled versus disabled) affects only the future requests and has no effect on the existing ones. After your request is created, the cookie support setting may be changed by using the other SET_COOKIE_SUPPORT procedure that operates on a request.

The default maximum number of cookies saved in the current session is 20 for each site and 300 total.

If you lower the maximum total number of cookies or the maximum number of cookies for each Web site, the oldest cookies will be purged first to reduce the number of cookies to the lowered maximum. HTTP cookies saved in the current session last for the duration of the database session only; there is no persistent storage for the cookies. Cookies saved in the current session are not cleared if you disable cookie support.

See "Examples" for how to use GET_COOKIES and ADD_COOKIES to retrieve, save, and restore cookies.

See Also:

Syntax

UTL_HTTP.SET_DETAILED_EXCP_SUPPORT (
   enable  IN BOOLEAN DEFAULT FALSE);

Parameters

See Also:

• HTTP Requests and HTTP Requests Subprograms

• Session Settings and Session Settings Subprograms

Syntax

Use this procedure to set the maximum number of redirections:

UTL_HTTP.SET_FOLLOW_REDIRECT (
   max_redirects  IN PLS_INTEGER DEFAULT 3);

Use this procedure to change the maximum number of redirections a request inherits from the session default setting:

UTL_HTTP.SET_FOLLOW_REDIRECT(
   r              IN OUT NOCOPY req,
   max_redirects  IN PLS_INTEGER DEFAULT 3);

Parameters

Usage Notes

If max_redirects is set to a positive number, the GET_RESPONSE Function will automatically follow the redirected URL for the HTTP response status code 301, 302, and 307 for the HTTP HEAD and GET methods, and 303 for all HTTP methods, and retry the HTTP request (the request method will be changed to HTTP GET for the status code 303) at the new location. It follows the redirection until the final, non-redirect location is reached, or an error occurs, or the maximum number of redirections has been reached (to prevent an infinite loop). The URL and method fields in the REQ record will be updated to the last redirected URL and the method used to access the URL. Set the maximum number of redirects to zero to disable automatic redirection.

While it is set not to follow redirect automatically in the current session, it is possible to specify individual HTTP requests to follow redirect instructions the function FOLLOW_REDIRECT and vice versa.

The default maximum number of redirections in a database user session is 3. The default value affects only future requests and has no effect on existing requests.

The SET_FOLLOW_REDIRECT procedure must be called before GET_RESPONSE for any redirection to take effect.

See Also:

Syntax

UTL_HTTP.SET_HEADER (
   r      IN OUT NOCOPY req,
   name   IN VARCHAR2,
   value  IN VARCHAR2);

Parameters

Usage Notes

Multiple HTTP headers with the same name are allowed in the HTTP protocol standard. Therefore, setting a header does not replace a prior header with the same name.

If the request is made using HTTP 1.1, UTL_HTTP sets the Host header automatically for you.

When you set the Content-Type header with this procedure, UTL_HTTP looks for the character set information in the header value. If the character set information is present, it is set as the character set of the request body. It can be overridden later by using the SET_BODY_CHARSET procedure.

When you set the Transfer-Encoding header with the value chunked, UTL_HTTP automatically encodes the request body written by the WRITE_TEXT, WRITE_LINEand WRITE_RAW procedures. Note that some HTTP-1.1-based Web servers or CGI programs do not support or accept the request body encoding in the HTTP 1.1 chunked transfer-encoding format.

See Also:

Syntax

Sets whether future HTTP requests should support the HTTP 1.1 persistent connection or not, and the maximum numbers of persistent connections to be maintained in the current database user session.

UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(
   enable      IN BOOLEAN DEFAULT FALSE,
   max_conns   IN PLS_INTEGER DEFAULT 0);

Enables or disables support for the HTTP 1.1 persistent-connection in the request.

UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(
   r           IN OUT NOCOPY req,
   enable      IN BOOLEAN DEFAULT FALSE);

Parameters

Usage Notes

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 for each 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 below.

Examples

Using SET_PERSISTENT_CONN_SUPPORT in http requests at the session level, showing the active persistent connection after each request

DECLARE
  pieces utl_http.html_pieces;
  conns  utl_http.connection_table;
BEGIN
 
  -- Turns on persistent connection support for the request_pieces call.
  utl_http.set_persistent_conn_support(true, 1);
 
  FOR i IN 1..10 LOOP
 
    pieces := utl_http.request_pieces(‘http://www.example.com/‘);
 
    -- Shows the active persistent connection
    utl_http.get_persistent_conns(conns);
    FOR j IN 1..conns.count LOOP
       dbms_output.put_line(‘Persistent connection ‘||j||‘: ‘||conns(j).host||‘:‘||conns(j).port);
    END LOOP;
 
  END LOOP;
 
 
  -- Turns off persistent connection support. Set active max persistent connection to 0 to close all active connections.
  utl_http.set_persistent_conn_support(false, 0);
 
END;
/

Using SET_PERSISTENT_CONN_SUPPORT in HTTP requets showing how to use persistent connection individually in each request to fetch multiple URLs at the same host

DECLARE
-- Table to store the URLs
TYPE vc2_table IS TABLE OF VARCHAR2(256) INDEX BY BINARY_INTEGER;
paths VC2_TABLE;

PROCEDURE fetch_pages(paths IN vc2_table) AS
  req  UTL_HTTP.REQ;
  resp UTL_HTTP.RESP;
  data VARCHAR2(1024);

BEGIN

  -- Set the proxy server
  UTL_HTTP.SET_PROXY(‘www-proxy.us.oracle.com:80‘, ‘‘);

  FOR i IN 1..paths.count LOOP

    req := UTL_HTTP.BEGIN_REQUEST(paths(i));

    -- Use persistent connections except for the last request
    IF (i < paths.count) THEN
      -- Use a persistent connection for the current request
      UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(req, TRUE);
    END IF;

    resp := UTL_HTTP.GET_RESPONSE(req);

    -- Display the results of the response
    DBMS_OUTPUT.PUT_LINE(‘-‘);
    DBMS_OUTPUT.PUT_LINE(‘URL: ‘ || paths(i));
    DBMS_OUTPUT.PUT_LINE(‘HTTP Response Status Code:   ‘ || resp.status_code);
    DBMS_OUTPUT.PUT_LINE(‘HTTP Response Reason Phrase: ‘ || resp.reason_phrase);
    DBMS_OUTPUT.PUT_LINE(‘HTTP Response Version:       ‘ || resp.http_version);

    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
-- Set a maximum of 1 persistent connection, but start with persistent connections 
-- off
   UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(FALSE, 1);

   -- Create a list of URLs
   paths(1) := ‘http://www.oracle.com/technetwork/index.html‘;
   paths(2) := ‘http://www.oracle.com/us/products/index.html‘;

   fetch_pages(paths);
 END;
/

See Also:

Syntax

UTL_HTTP.SET_PROXY (
   proxy             IN VARCHAR2,
   no_proxy_domains  IN VARCHAR2);

Parameters

Usage Notes

The proxy may include an optional TCP/IP port number at which the proxy server listens. The syntax is [http://]host[:port][/], for example, www-proxy.my-company.com:80. If the port is not specified for the proxy, port 80 is assumed.

Optionally, a port number can be specified for each domain or host. If the port number is specified, the no-proxy restriction is only applied to the request at the port of the particular domain or host, for example, corp.my-company.com, eng.my-company.com:80. When no_proxy_domains is NULL and the proxy is set, all requests go through the proxy. When the proxy is not set, UTL_HTTP sends requests to the target Web servers directly.

You can define a username/password for the proxy to be specified in the proxy string. The format is

[http://][user[:password]@]host[:port][/]

If proxy settings are set when the database server instance is started, the proxy settings in the environment variables http_proxy and no_proxy are assumed. Proxy settings set by this procedure override the initial settings.

See Also:

Syntax

UTL_HTTP.SET_RESPONSE_ERROR_CHECK (
   enable  IN BOOLEAN DEFAULT FALSE);

Parameters

Usage Notes

If the status code indicates an error—a 4xx or 5xx code—and this procedure is enabled, GET_RESPONSE will raise the HTTP_CLIENT_ERROR or HTTP_SERVER_ERRORexception. If SET_RESPONSE_ERROR_CHECK is set to FALSE, GET_RESPONSE will not raise an exception when the status code indicates an error.

Response error check is turned off by default.

The GET_RESPONSE function can raise other exceptions when SET_RESPONSE_ERROR_CHECK is set to FALSE.

See Also:

Syntax

UTL_HTTP.SET_TRANSFER_TIMEOUT (
   timeout  IN PLS_INTEGER DEFAULT 60);

Parameters

Usage Notes

The default value of the time out is 60 seconds.

See Also:

• Session Settings and Session Settings Subprograms

• "Managing Fine-Grained Access in PL/SQL Network Utility Packages" in the Oracle Database Security Guide

Syntax

UTL_HTTP.SET_WALLET (
   path      IN VARCHAR2,
   password  IN VARCHAR2 DEFAULT NULL);

Parameters

Usage Notes

To set up an Oracle wallet, use the Oracle Wallet Manager to create a wallet. In order for the HTTPS request to succeed, the certificate authority that signs the certificate of the remote HTTPS Web server must be a trust point set in the wallet.

When a wallet is created, it is populated with a set of well-known certificate authorities as trust points. If the certificate authority that signs the certificate of the remote HTTPS Web server is not among the trust points, or the certificate authority has new root certificates, you should obtain the root certificate of that certificate authority and install it as a trust point in the wallet using Oracle Wallet Manager

See Also:

Syntax

UTL_HTTP.WRITE_LINE(
   r     IN OUT NOCOPY req,
   data  IN VARCHAR2 CHARACTER SET ANY_CS);

Parameters

Usage Notes

An HTTP client must always let the remote Web server know the length of the request body it is sending. If the amount of data is known beforehand, you can set the Content-Length header in the request, where the length of the content is measured in bytes instead of characters. If the length of the request body is not known beforehand, you can send the request body using the HTTP 1.1 chunked transfer-encoding format. The request body is sent in chunks, where the length of each chunk is sent before the chunk is sent. The UTL_HTTP package performs chunked transfer-encoding on the request body transparently when the Transfer-Encoding: chunked header is set. Note that some HTTP-1.1-based Web servers or CGI programs do not support or accept the request body encoding in the HTTP 1.1 chunked transfer-encoding format. See the SET_HEADER procedure for details.

If you send the Content-Length header, you should note that the length specified in the header should be the byte-length of the textual request body after it is converted from the database character set to the request body character set. When either one of the two character sets is a multibyte character set, the precise byte-length of the request body in the request body character set cannot be known beforehand. In this case, you can perform the character set conversion explicitly, determine the byte-length of the results, send the Content-Length header, and the results using the WRITE_RAW procedure to avoid the automatic character set conversion. Or, if the remove Web server or CGI programs allow, you can send the request body using the HTTP 1.1 chunked transfer-encoding format, where UTL_HTTP handles the length of the chunks transparently.

See Also:

Syntax

UTL_HTTP.WRITE_RAW(
   r     IN OUT NOCOPY REQ,
   data  IN            RAW);

Parameters

Usage Notes

An HTTP client must always let the remote Web server know the length of the request body it is sending. If the amount of data is known beforehand, you can set the Content-Length header in the request, where the length of the content is measured in bytes instead of characters. If the length of the request body is not known beforehand, you can send the request body using the HTTP 1.1 chunked transfer-encoding format. The request body is sent in chunks, where the length of each chunk is sent before the chunk is sent. UTL_HTTP performs chunked transfer-encoding on the request body transparently when the Transfer-Encoding:chunked header is set. Note that some HTTP-1.1-based Web servers or CGI programs do not support or accept the request body encoding in the HTTP 1.1 chunked transfer-encoding format. See the SET_HEADER procedure for details.

See Also:

Syntax

UTL_HTTP.WRITE_TEXT(
   r     IN OUT NOCOPY REQ,
   data  IN            VARCHAR2 CHARACTER SET ANY_CS);

Parameters

Usage Notes

An HTTP client must always let the remote Web server know the length of the request body it is sending. If the amount of data is known beforehand, you can set the Content-Length header in the request, where the length of the content is measured in bytes instead of characters. If the length of the request body is not known beforehand, you can send the request body using the HTTP 1.1 chunked transfer-encoding format. The request body is sent in chunks, where the length of each chunk is sent before the chunk is sent. UTL_HTTP performs chunked transfer-encoding on the request body transparently when the Transfer-Encoding: chunked header is set. Note that some HTTP-1.1-based Web servers or CGI programs do not support or accept the request body encoding in the HTTP 1.1 chunked transfer-encoding format. See the SET_HEADER procedure for details.

If you send the Content-Length header, you should note that the length specified in the header should be the byte-length of the textual request body after it is converted from the database character set to the request body character set. When either one of the two character sets is a multibyte character set, the precise byte-length of the request body in the request body character set cannot be known beforehand. In this case, you can perform the character set conversion explicitly, determine the byte-length of the results, send the Content-Length header, and the results using the WRITE_RAW procedure to avoid the automatic character set conversion. Or, if the remove Web server or CGI programs allow, you can send the request body using the HTTP 1.1 chunked transfer-encoding format, where UTL_HTTP handles the length of the chunks transparently.

------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

From Others

Oracle UTL_HTTP Version 10.2