The HTTPRequest class

Summary:

Syntax
Methods
Examples

Syntax

The HTTPRequest class provides an interface to perform asynchronous XML and TEXT requests over HTTP for a specified URL, with additional XML streaming possibilities.

The status is set to zero after a successful method call.

Syntax

com.HTTPRequest

Creation

Class Methods
Name	Description
`com.HTTPRequest.Create( url STRING ) RETURNING com.HTTPRequest`	Creates an HTTPRequest object by providing a mandatory url with HTTP or HTTPS as the protocol. Note: url can be an identifier of an URL mapping with an optional alias:// prefix. See FGLPROFILE Configuration for more details about URL mapping with aliases, and for proxy and security configuration. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Configuration

Object Methods
Name	Description
`setVersion( version STRING )`	Sets the HTTP version of the request. Accepted versions are 1.0 and 1.1 (only these two versions are supported). The default is 1.1. Throws an exception in case of errors, and updates status with an error code.
`setMethod( method STRING )`	Sets the HTTP method of the request. Supported methods are GET, PUT, POST, HEAD and DELETE. The default is GET. Throws an exception in case of errors, and updates status with an error code.
`setHeader( name STRING , value STRING )`	Sets an HTTP header name and value for the request, and replaces the previous one if there was any. Setting a header after the body has been sent, or if a streaming operation has been started, will only be taken into account when a new request is reissued. Throws an exception in case of errors, and updates status with an error code.
`removeHeader( name STRING )`	Removes an HTTP header name for the request if it exists. Throws an exception in case of errors, and updates status with an error code.
`clearHeaders()`	Removes all user-defined headers.
`setCharset( charset STRING )`	Defines the charset used when sending text or XML; by default no charset is set. When sending text, HTTP specification defines ISO-8859-1 as an implicit charset. When sending XML, the user-defined charset is used instead of the one set in the XML document itself, which can lead to a charset conversion error at the server side. It is recommended that you unset it by setting charset to NULL, or that you use the same charset that was set in the XML Document.
`setAuthentication( login STRING, pass STRING, scheme STRING, realm STRING )`	Defines the mandatory user login and password to authenticate to the server. An optional scheme defines the method to be used during authentication. Only Anonymous, Basic and Digest are supported. The default is Anonymous. An optional realm can be set. With Anonymous or Digest authentication, you must resend the request if you get a 401 or 407 HTTP return code (authorization required) If a user-defined authentication is set and there is an authenticate entry for this URL in the FGLPROFILE file, the user-defined authentication has priority. Throws an exception in case of errors, and updates status with an error code.
`clearAuthentication()`	Removes user-defined authentication. If an authenticate entry exists in the FGLPROFILE file, it will be used for authentication, even if the user-defined authentication was removed.
`setKeepConnection( keep INTEGER )`	Defines whether the connection should stay open if a new request occurs again. The default is FALSE.
`setTimeOut( timeout INTEGER )`	Sets the time value in seconds to wait for a reading or writing operation, before a break. The value of -1 means infinite wait.
`setConnectionTimeOut( timeout INTEGER )`	Sets the time value in seconds to wait for the establishment of the connection, before a break. The value of -1 means infinite wait.
`setMaximumResponseLength( length INTEGER )`	Sets the maximum authorized size in Kbyte of the whole response (composed of the headers, the body and all control characters), before a break. The value of -1 means no limit.
`setAutoReply( reply BOOLEAN )`	Defines whether method getReponse() or getAsyncResponse() will automatically perform another HTTP GET request if response contains HTTP Authentication, Proxy Authentication or HTTP redirect data. The efault is TRUE. Note: Only available for GET method.

Back to the top

Sending

Object Methods
Name	Description
`doRequest()`	Performs the request. Supported methods are GET, HEAD and DELETE. Throws an exception in case of errors, and updates status with an error code.
`doTextRequest( txt STRING )`	Performs the request by sending an entire string at once. Supported methods are PUT and POST. The default Content-Type header is text/plain, but it can be changed if of the form *text/,** for instance text/richtext. Automatic conversion from locale to user-defined charset is performed when possible, otherwise throws an exception. In HTTP 1.1, if the body size is greater than 32k, the request will be sent in several chunks of the same size. Throws an exception in case of errors, and updates status with an error code.
`doXmlRequest( doc xml.DomDocument )`	Performs the request by sending the entire xml.DomDocument at once. Supported methods are PUT and POST. The default Content-Type header is text/xml, but it can be changed if of the form /xml or /*+xml, for instance application/xhtml+xml. In HTTP 1.1, if the body size is greater than 32k, the request will be sent in several chunks of the same size. Throws an exception in case of errors, and updates status with an error code.
`doFormEncodedRequest( query STRING, utf8 INTEGER )`	Performs an application/x-www-form-urlencoded Forms encoded query. Supported methods are GET and POST. The query string is a list of name/value pairs separated with &. For example, name1=value1&name2=value2&name3=value3. If utf8 is TRUE, the query string is encoded in UTF-8 as specified in XForms 1.0, otherwise in ASCII as specified in HTML 4. Note : if you need to url encode the separator characters & and =, simply double them as following : na&&me=va==lue . Throws an exception in case of errors, and updates status with an error code.
`beginXmlRequest() RETURNING xml.StaxWriter`	Begins the streaming HTTP request and returns an xml.StaxWriter object ready to send XML to the server. Supported methods are PUT and POST. The default Content-Type header is text/xml, but it can be changed if of the form /xml or /*+xml, for instance application/xhtml+xml. In HTTP 1.1, if the body size is greater than 32k, the request will be sent in several chunks of the same size. Throws an exception in case of errors, and updates status with an error code.
`endXmlRequest( writer xml.StaxWriter )`	Ends the streaming HTTP request by closing the Stax writer. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Response

Object Methods
Name	Description
`getResponse() RETURNING com.HTTPResponse`	Returns the response of one of the doRequest, doTextRequest, doXmlRequest, doFormEncodedRequest or beginXmlRequest and endXmlRequest calls in an com.HTTPResponse object. Throws an exception in case of errors, and updates status with an error code.
`getAsyncResponse() RETURNING com.HTTPResponse`	Returns the response of one of the doRequest, doTextRequest, doXmlRequest, doFormEncodedRequest or beginXmlRequest and endXmlRequest calls in an com.HTTPResponse object, or NULL if the response was not yet received. If a previous call returned NULL, a new call will return the expected response if it has already arrived, or NULL again if the response was still not received. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Examples

Example 1 : HTTP GET request

01 IMPORT com
02
03 MAIN
04   DEFINE req com.HTTPRequest
05   DEFINE resp com.HTTPResponse
06   TRY 
07     LET req = com.HTTPRequest.Create("http://localhost:8090/MyPage")
08     CALL req.setHeader("MyHeader","High Priority") # Set additional HTTP header with name 'MyHeader', and value 'High Priority'
09     CALL req.doRequest()
10     LET resp = req.getResponse()
11     IF resp.getStatusCode() != 200 THEN
12       DISPLAY   "HTTP Error ("||resp.getStatusCode()||") ",resp.getStatusDescription()
13     ELSE
14       DISPLAY   "HTTP Response is : ",resp.getTextResponse()
15     END IF
16   CATCH
17     DISPLAY "ERROR :",STATUS||" ("||SQLCA.SQLERRM||")" 
18   END TRY
19 END MAIN

Example 2 : XForms HTTP POST request

01 IMPORT com
02 IMPORT xml
03 
04 MAIN 
05   DEFINE req com.HTTPRequest
06   DEFINE resp com.HTTPResponse
07   DEFINE doc xml.DomDocument
08   TRY 
09     LET req = com.HTTPRequest.Create("http://localhost:8090/MyProcess")
10     CALL req.setMethod("POST") # Perform an HTTP POST method
11     CALL req.doFormEncodedRequest("Param1=hello&Param2=how are you ?",FALSE) # Param1 value is 'hello', Param2 value is 'how are you ?'
12     LET resp = req.getResponse()
13     IF resp.getStatusCode() != 200 THEN
14       DISPLAY  "HTTP Error ("||resp.getStatusCode()||") ",resp.getStatusDescription()
15     ELSE 
16       LET   doc = resp.getXmlResponse() # Expect a returned content type of the form */xml
17       DISPLAY   "HTTP XML Response is : ",doc.saveToString()
18     END IF 
19   CATCH
20     DISPLAY "ERROR :",STATUS||" ("||SQLCA.SQLERRM||")" 
21   END TRY
22 END MAIN

Example 3 : Streaming HTTP PUT request

01 IMPORT com
02 IMPORT xml
03 
04 MAIN 
05   DEFINE req com.HTTPRequest
06   DEFINE resp com.HTTPResponse
07   DEFINE writer xml.StaxWriter
08   TRY 
09    LET req = com.HTTPRequest.Create("http://localhost:8090/MyXmlProcess")
10  CALL req.setMethod("PUT") # Perform an HTTP PUT method
11  CALL req.setHeader("MyHeader","Value of my header") 
12  LET writer = req.beginXmlRequest() # Retrieve an xml.StaxWriter to start xml streaming
13  CALL writer.startDocument("utf-8","1.0",true)
14  CALL writer.comment("My first XML document sent in streaming with genero!!!") 
15  CALL writer.startElement("root")
16  CALL writer.attribute("attr1","value1") 
17  CALL writer.endElement()
18  CALL writer.endDocument()
19  CALL req.endXmlRequest(writer) # End streaming request
20  LET resp = req.getResponse()
21   IF resp.getStatusCode() != 201 OR resp.getStatusCode() != 204 THEN
22    DISPLAY   "HTTP Error ("||resp.getStatusCode()||") ",resp.getStatusDescription()
23   ELSE 
24     DISPLAY   "XML document was correctly put on the server"
25   END IF 
26 CATCH
27   DISPLAY "ERROR :",STATUS||" ("||SQLCA.SQLERRM||")" 
28 END TRY
29 END MAIN

Example 4 : Asynchronous HTTP DELETE request

01 IMPORT com
02
03 MAIN 
04   DEFINE req com.HTTPRequest
05   DEFINE resp com.HTTPResponse
06   DEFINE url STRING
07   DEFINE quit CHAR(1)
08   DEFINE questionStr STRING
09   DEFINE timeout INTEGER
10   TRY 
11     WHILE TRUE
12       PROMPT "Enter http url you want to delete ? " FOR url ATTRIBUTE (CANCEL=FALSE)
13       LET req = com.HTTPRequest.Create(url)
14       CALL req.setMethod("DELETE")
15       CALL req.doRequest()
16       LET resp = req.getAsyncResponse() # Retrieve asynchronous response for the first time
17       CALL Update(resp) RETURNING questionStr,timeout
18       WHILE quit IS NULL OR ( quit!="Y" AND quit!="N" )
19         PROMPT questionStr FOR CHAR quit ATTRIBUTE (CANCEL=FALSE,ACCEPT=FALSE,SHIFT="up")
20           ON IDLE timeout
21            IF resp IS NULL THEN # If no response at first try, retrieve it again
22            LET resp = req.getAsyncResponse() # because we have time now !!! 
23            CALL Update(resp) RETURNING questionStr,timeout 
24          END IF
25      END PROMPT 
26    END WHILE
27    IF quit == "Y" THEN
28     EXIT PROGRAM 
29    ELSE
30      LET quit = NULL
31    END IF
32  END WHILE
33 CATCH
34   DISPLAY "ERROR :",STATUS,SQLCA.SQLERRM
35 END TRY
36 END MAIN
37 
38 FUNCTION Update(resp)
39   DEFINE resp com.HTTPResponse
40   DEFINE ret STRING
41   IF resp IS NOT NULL THEN
42     IF resp.getStatusCode() != 204 THEN
43       LET   ret = "HTTP Error ("||resp.getStatusCode()||") :"||resp.getStatusDescription()||". Do you want to quit ? "
44     ELSE 
45       LET   ret = "HTTP Page deleted. Do you want to quit ? "
46     END IF 
47   RETURN ret, 0
48 ELSE 
49   LET ret = "Do you want to quit ? "
50   RETURN ret, 1
51 END IF 
52 END FUNCTION

Back to the top