Term: UTL_HTTP

Definition:
In Oracle PL/SQL, UTL_HTTP is an Oracle package which supports HTTP requests from SQL and PL/SQL. UTL_HTTP is widely used to read a web page or access data over the internet. The package defines a set of Constants, Types, Exceptions and subprograms. The following list is compiled from Oracle documentation,

Constants:

HTTP_VERSION_1_0 CONSTANT VARCHAR2(10) := 'HTTP/1.0' - Denotes HTTP version 1.0 that can be used in the function begin_request.
HTTP_VERSION_1 CONSTANT VARCHAR2(10) := 'HTTP/1.1' - Denotes HTTP version 1.1 that can be used in the function begin_request.
DEFAULT_HTTP_PORT CONSTANT PLS_INTEGER := 80 - The default TCP/IP port (80) at which a Web server or proxy server listens.
DEFAULT_HTTPS_PORT CONSTANT PLS_INTEGER := 443 - The default TCP/IP port (443) at which an HTTPS Web server listens.
HTTP_CONTINUE CONSTANT PLS_INTEGER := 100;
HTTP_SWITCHING_PROTOCOLS CONSTANT PLS_INTEGER := 101;
HTTP_OK CONSTANT PLS_INTEGER := 200;
HTTP_CREATED CONSTANT PLS_INTEGER := 201;
HTTP_ACCEPTED CONSTANT PLS_INTEGER := 202;
HTTP_NON_AUTHORITATIVE_INFO CONSTANT PLS_INTEGER := 203;
HTTP_NO_CONTENT CONSTANT PLS_INTEGER := 204;
HTTP_RESET_CONTENT CONSTANT PLS_INTEGER := 205;
HTTP_PARTIAL_CONTENT CONSTANT PLS_INTEGER := 206;
HTTP_MULTIPLE_CHOICES CONSTANT PLS_INTEGER := 300;
HTTP_MOVED_PERMANENTLY CONSTANT PLS_INTEGER := 301;
HTTP_FOUND CONSTANT PLS_INTEGER := 302;
HTTP_SEE_OTHER CONSTANT PLS_INTEGER := 303;
HTTP_NOT_MODIFIED CONSTANT PLS_INTEGER := 304;
HTTP_USE_PROXY CONSTANT PLS_INTEGER := 305;
HTTP_TEMPORARY_REDIRECT CONSTANT PLS_INTEGER := 307;
HTTP_BAD_REQUEST CONSTANT PLS_INTEGER := 400;
HTTP_UNAUTHORIZED CONSTANT PLS_INTEGER := 401;
HTTP_PAYMENT_REQUIRED CONSTANT PLS_INTEGER := 402;
HTTP_FORBIDDEN CONSTANT PLS_INTEGER := 403;
HTTP_NOT_FOUND CONSTANT PLS_INTEGER := 404;
HTTP_NOT_ACCEPTABLE CONSTANT PLS_INTEGER := 406;
HTTP_PROXY_AUTH_REQUIRED CONSTANT PLS_INTEGER := 407;
HTTP_REQUEST_TIME_OUT CONSTANT PLS_INTEGER := 408;
HTTP_CONFLICT CONSTANT PLS_INTEGER := 409;
HTTP_GONE CONSTANT PLS_INTEGER := 410;
HTTP_LENGTH_REQUIRED CONSTANT PLS_INTEGER := 411;
HTTP_PRECONDITION_FAILED CONSTANT PLS_INTEGER := 412;
HTTP_REQUEST_ENTITY_TOO_LARGE CONSTANT PLS_INTEGER := 413;
HTTP_REQUEST_URI_TOO_LARGE CONSTANT PLS_INTEGER := 414;
HTTP_UNSUPPORTED_MEDIA_TYPE CONSTANT PLS_INTEGER := 415;
HTTP_REQ_RANGE_NOT_SATISFIABLE CONSTANT PLS_INTEGER := 416;
HTTP_EXPECTATION_FAILED CONSTANT PLS_INTEGER := 417;
HTTP_NOT_IMPLEMENTED CONSTANT PLS_INTEGER := 501;
HTTP_BAD_GATEWAY CONSTANT PLS_INTEGER := 502;
HTTP_SERVICE_UNAVAILABLE CONSTANT PLS_INTEGER := 503;
HTTP_GATEWAY_TIME_OUT CONSTANT PLS_INTEGER := 504;
HTTP_VERSION_NOT_SUPPORTED CONSTANT PLS_INTEGER := 505;

Types:

REQ - Represents HTTP request
RESP - Represents HTTP response
COOKIE - Represents HTTP cookie
COOKIE_TABLE - Represents collection of cookies
CONNECTION - Represents remote hosts and TCP/IP ports of connection

Exceptions:

request_failed (ORA-29273) - The request failed to execute.
bad_argument (ORA-29261) - The argument passed to the interface is malformed, unrecognized, or missing.
bad_url (ORA-29262) - The requested URL was badly formed.
protocol_error (ORA-29263) - An HTTP protocol error occurred when communicating with the web server.
unknown_scheme (ORA-29264) - The scheme of the requested URL is unknown.
header_not_found (ORA-29265) - The header was not found.
end_of_body (ORA-29266) - The end of the HTTP response body was reached.
illegal_call (ORA-29267) - The call to UTL_HTTP is illegal at the current state of the HTTP request.
http_client_error (ORA-29268) - From get_response, the response status code indicates that a client error has occurred (status code in 4xx range). Or from begin_request, the HTTP proxy returns a status code in the 4xx range when making an HTTPS request through the proxy.
http_server_error (ORA-29269) - From get_response, the response status code indicates that a client error has occurred (status code in 5xx range). Or from begin_request, the HTTP proxy returns a status code in the 5xx range when making an HTTPS request through the proxy.
too_many_requests (ORA-29270) - Too many requests or responses are open
partial_multibyte_exception (ORA-29275) - No complete character was read and a partial multibyte character was found at the end of the response body.
transfer_timeout (ORA-29276) - No data was read and a read timeout occurred.

Subprograms: HTTP fetches:

REQUEST - Returns up to the first 2000 bytes of the data retrieved from the given URL. This function can be used directly in SQL queries.
REQUEST_PIECES - Returns a PL/SQL table of 2000-byte pieces of the data retrieved from the given URL.

Session setting subprograms:

GET_BODY_CHARSET - Retrieves the default character set of the body of all future HTTP requests
GET_COOKIE_SUPPORT - Retrieves the current cookie support settings
GET_DETAILED_EXCP_SUPPORT - Checks if the UTL_HTTP package will raise a detailed exception or not
GET_FOLLOW_REDIRECT - Retrieves the follow-redirect setting in the current session
GET_PERSISTENT_CONN_SUPPORT - Checks if the persistent connection support is enabled and gets the maximum number of persistent connections in the current session
GET_PROXY - Retrieves the current proxy settings
GET_RESPONSE_ERROR_CHECK - Checks if the response error check is set or not
GET_TRANSFER_TIMEOUT - Retrieves the current network transfer timeout value
SET_BODY_CHARSET - 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-Type header
SET_COOKIE_SUPPORT - Sets whether or not future HTTP requests will support HTTP cookies; sets the maximum number of cookies maintained in the current database user session
SET_DETAILED_EXCP_SUPPORT - Sets the UTL_HTTP package to raise a detailed exception
SET_FOLLOW_REDIRECT - Sets the maximum number of times UTL_HTTP follows the HTTP redirect instruction in the HTTP responses to future requests in the get_response function
SET_PERSISTENT_CONN_SUPPORT - Sets whether or not future HTTP requests will support the HTTP 1.1 persistent connection; sets the maximum number of persistent connections maintained in the current database user session
SET_PROXY - Sets the proxy to be used for requests of HTTP or other protocols
SET_RESPONSE_ERROR_CHECK - Sets whether or not get_response raises an exception when the Web server returns a status code that indicates an error (a status code in the 4xx or 5xx ranges)
SET_TRANSFER_TIMEOUT - Sets the timeout value for UTL_HTTP to read the HTTP response from the Web server or proxy server
SET_WALLET - Sets the Oracle Wallet used for all HTTP requests over Secured Socket Layer (SSL), that is, HTTPS

Request subprograms:

BEGIN_REQUEST - Begins a new HTTP request. UTL_HTTP establishes the network connection to the target Web server or the proxy server and sends the HTTP request line.
END_REQUEST - Ends or terminates the HTTP request.
SET_HEADER - Sets an HTTP request header. The request header is sent to the Web server as soon as it is set.
SET_AUTHENTICATION - Sets HTTP authentication information in the HTTP request header. The Web server needs this information to authorize the request.
SET_BODY_CHARSET - 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.
SET_COOKIE_SUPPORT - Enables or disables support for the HTTP cookies in the request.
SET_FOLLOW_REDIRECT - Sets the maximum number of times UTL_HTTP follows the HTTP redirect instruction in the HTTP response to this request in the GET_RESPONSE.
SET_PERSISTENT_CONN_SUPPORT - Enables or disables support for the HTTP 1.1 persistent-connection in the request.
WRITE_LINE - Writes a text line in the HTTP request body and ends the line with new-line characters (CRLF as defined in UTL_TCP).
WRITE_RAW - Writes some binary data in the HTTP request body.
WRITE_TEXT - Writes some text data in the HTTP request body.

Response Subprograms:

END_RESPONSE - Ends the HTTP response. It completes the HTTP request and response.
GET_AUTHENTICATION - Retrieves the HTTP authentication information needed for the request to be accepted by the Web server as indicated in the HTTP response header.
GET_HEADER - Returns the nth HTTP response header name and value returned in the response.
GET_HEADER_BY_NAME - Returns the HTTP response header value returned in the response given the name of the header.
GET_HEADER_COUNT - Returns the number of HTTP response headers returned in the response.
GET_RESPONSE - Reads the HTTP response. When the returns, the status line and the HTTP response headers have been read and processed.
READ_LINE - Reads the HTTP response body in text form until the end of line is reached and returns the output in the caller-supplied buffer.
READ_RAW - Reads the HTTP response body in binary form and returns the output in the caller-supplied buffer.
READ_TEXT - Reads the HTTP response body in text form and returns the output in the caller-supplied buffer.
SET_BODY_CHARSET - 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.

Cookie subprograms:

ADD_COOKIES - Adds the cookies maintained by UTL_HTTP.
CLEAR_COOKIES - Clears all cookies maintained by the UTL_HTTP package.
GET_COOKIE_COUNT - Returns the number of cookies currently maintained by the UTL_HTTP package set by all Web servers.
GET_COOKIES - Returns all the cookies currently maintained by the UTL_HTTP package set by all Web servers.

Persistent Connections Subprograms:

CLOSE_PERSISTENT_CONN - Closes an HTTP persistent connection maintained by the UTL_HTTP package in the current database session.
CLOSE_PERSISTENT_CONNS - Closes a group of HTTP persistent connections maintained by the UTL_HTTP package in the current database session.
GET_PERSISTENT_CONN_COUNT - Returns the number of network connections currently kept persistent by the UTL_HTTP package to the Web servers.
GET_PERSISTENT_CONNS - Returns all the network connections currently kept persistent by the UTL_HTTP package to the Web servers.

Error Condition Subprograms:

GET_DETAILED_SQLCODE Function - Retrieves the detailed SQLCODE of the last exception raised.
GET_DETAILED_SQLERRM Function - Retrieves the detailed SQLERRM of the last exception raised.