diff --git a/specs/http-client-2/index.html b/specs/http-client-2/index.html index f2dc25c..53da61e 100644 --- a/specs/http-client-2/index.html +++ b/specs/http-client-2/index.html @@ -131,6 +131,12 @@ font-weight: bolder; font-style: italic; } + .constants-table th:nth-child(3) { + text-align: right; + } + .constants-table td:nth-child(3) { + text-align: right; + } @@ -528,29 +534,170 @@

Request Options

- status-only - xs:boolean - false() - -

Ignore the headers and body in the HTTP response.

-

This may be used to save resources on parsing the response when the user is - only interested in the response code.

- - - - parse-response-entity-body - xs:boolean - true() + parse-response + map(xs:string, *) + 
+map {
+  "mode": $http:parse-mode-full,
+  "entity": $http:parse-entity-auto
+}
 -

Indicates if the response bodies will be parsed (see - ).

-

When set to true(), if status-only is also set to - true(), the error http:invalid-option MUST be raised.

+

Controls the parsing of the HTTP response. Entries for the map are detailed in + .

+
+

Parse Response Options

+

+ The following parse-response options can be specified to control HTTP response parsing: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parse-response map entries
Entry KeyXDM TypeDefaultDescription
modexs:string$http:parse-mode-full +

Determines the extent to which the HTTP response is parsed before being returned from the function + call as the response map. Parsing of the HTTP response requires processing, so some + implementations may be able to optimize for some of the simpler parsing modes. Valid values are:

+
    +
  • + $http:parse-mode-raw +

    No parsing of the HTTP response is performed. The entire response is returned as + xs:base64Binary in the body of the response map, all other + entries of the response map are omitted.

    +
    • +
  • + $http:parse-mode-status +

    Only the status line from the HTTP response is + parsed. Only the http-version, status, and message + entries will be present in the response map.

    +
    • +
  • + $http:parse-mode-headers +

    From the HTTP response, only the status line, + general headers, + response headers, and + entity headers will all be parsed. All fields apart + from the body will be present in the response map.

    +
    • +
  • + $http:parse-mode-multipart-raw +

    When the HTTP response is a multipart response, first the + status line, + general headers, + response headers, and + entity headers of the HTTP response will be parsed, + setting the http-version, status, and message in the + response map.

    +

    Secondly the response's entity body will be minimally parsed; Only extracting each entity from + the body in raw form. That is to say, that each multipart entity within the entity body will not + have its headers parsed. The entity will be delivered in its raw form in the body + entry of the part body and the part body's headers entry will be omitted. Each + part body will be set in the body entry of the response map.

    +

    If the response is not a multipart response, and this mode is set, then the error + http:parse MUST be raised.

    +
    • +
  • + $http:parse-mode-multipart-headers +

    When the HTTP response is a multipart response, first the + status line, + general headers, + response headers, and + entity headers of the HTTP response will be parsed, + setting the http-version, status, and message in the + response map.

    +

    Secondly the response's entity body will only be minimally parsed; Only extracting the headers + of each entity within the body. That is to say, that each multipart entity within the entity + body will have its body ignored. Only the headers of the part body entry will be + set, and each part body will be set in the body entry of the response map.

    +

    If the response is not a multipart response, and this mode is set, then the error + http:parse MUST be raised.

    +
    • +
  • + $http:parse-mode-full +

    The entire HTTP response is parsed automatically according to the rules in + , and all the entries in the response + map are set (apart from the body entry when the HTTP response has no body).

    +
    • +
+
entityxs:string+$http:parse-entity-auto +

Overrides the implicit automatic parsing defined in + .

+

If this option is specified and the mode is not set to $http:parse-mode-full, + then the error http:invalid-option MUST be raised.

+

Where a multipart response is expected, a sequence of values may be specified. + If there are less values than multipart parts, then the last value will apply to the remaining + multipart parts.

+

Valid values are:

+
    +
  • + $http:parse-entity-auto +

    Determines the parser based on the the rules defined in + .

    +
    • +
  • + $http:parse-entity-xml +

    The entity will be parsed as XML. The result is a document-node().

    +
    • +
  • + $http:parse-entity-html-to-xml +

    The entity will be parsed using a HTML parser which can produce XML output. + The result is a document-node().

    +

    Implementations are not required to support this option. If an implementation does not support + this it MUST raise the error http:invalid-option.

    +
    • +
  • + $http:parse-entity-json +

    The entity will be parsed using a JSON parser. The result is either a map(*), + array(*), xs:string, xs:double, xs:boolean, + or empty-sequence().

    +
    • +
  • + $http:parse-entity-text +

    The entity will be parsed as text. The result is an xs:string.

    +
    • +
  • + $http:parse-entity-raw +

    The entity will be extracted as is. The result is an xs:base64Binary.

    +
    • +
  • + $http:parse-entity-none +

    The entity will be not be parsed. The result is an empty-sequence().

    +
    • +
+
+
+ 
           http:get('http://expath.org/xyz', map {
             'status-only': true(),
@@ -722,7 +869,8 @@ 
The Response

       

         When the HTTP request is made to the server indicated by the request $uri, if the
         server processes the request and responds to the client within the timeout then the
-        HTTP response from the server is returned as the result of the function as a map.

+        HTTP response from the server is returned as the result of the function as a map, this is  known as the
+        Response Map.

       

         If the server fails to respond to an HTTP request within the timeout then the error
         http:timeout MUST be raised. If the HTTP request cannot be made to the server then
@@ -732,14 +880,13 @@ 
The Response

       

         
The Response Map

         

-          The HTTP response map contains the following entries. Optional entries are entirely absent
+          The HTTP Response Map contains the following entries. Optional entries are entirely absent
           from the map if the HTTP response does not contain the corresponding data, for example no body is returned, there will be no body entry.
         

 
         -            @@ -748,7 +895,6 @@ 
The Response Map

-              
@@ -756,7 +902,6 @@ 
The Response Map

-              
-              
@@ -773,7 +917,6 @@ 
The Response Map

-              
@@ -781,13 +924,11 @@ 
The Response Map

-              
-              
@@ -833,7 +974,7 @@ 
The Response Entity Body

           For those cases where the server is not responding faithfully to the request, or the developer
           needs a greater level of control over the response, the implicit parsing of the response entity
-          body can be disabled via the parse-response-entity-body request option,
+          body can be disabled via the parse-response request option,
           see .
         

 
@@ -883,6 +1024,7 @@ 
Implicit Parsing

@@ -946,13 +1088,11 @@ 
Implicit Parsing

           
Explicit Parsing

           

-            Implicit parsing of the response body can be disabled via the parse-response-entity-body
-            request option. All bodies of single and multipart responses will be returned as binary items
-            of type xs:base64Binary, and the values can be processed (stored, parsed,
-            forwarded) in a second step.
+            Implicit parsing of the response body can be disabled via the parse-response
+            request option, which allows the parsing to be explicitly specified.
           

 
-          
+          
             (:~
              : Parses a response and returns the parsed body values.
              : @param $response response (top-level, multipart)
@@ -980,7 +1120,12 @@ 
Explicit Parsing

 
             local:parse(
               http:get('http://expath.org/xyz',
-                  map { 'parse-response-entity-body': false() })
+                  map { 'parse-response':
+                      map {
+                          'entity': $http:parse-entity-raw()
+                      }
+                  }
+              )
             )
           

         

@@ -989,6 +1134,97 @@ 
Explicit Parsing

 
+    

+      
Constants

+      
This section defines the constants which are defined by the HTTP module. Each constant is
+      defined as a variable. The purpose of these constants is to reduce developer error where otherwise
+      common strings or values would have to be reproduced.

+
+      

           Response Entries
           

             
             
             

             

               Response Key
               XDM TypeOptional
               Description
             

           
             

               http-version
               xs:stringNo
               
                 
The HTTP Version of the response. This may differ from the
                   http-version requested!

@@ -765,7 +910,6 @@ 
The Response Map

             

               status
               xs:stringNo
               
                 
The HTTP status code.

               		
             

               message
               xs:stringNo
               
                 
HTTP reason phrase.

               		
             

               headers
               map(xs:string, xs:string)Yes
               HTTP response header fields.
             

             

               body
               item()+Yes
               HTTP response body.
             

           
         
                 
document-node()
                 
                   
Parsed as XML.

+                  
NOTE: this will logically also include XHTML with the mimetype application/xhtml+xml.
                 

               

               

         
 
     

+        
+        +          +          +          +          +        
+        
+        
+          
+          
+          
+        
+        
+        
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+          
+            
+            
+            
+          
+        
+      
Constants





VariableXDM TypeValue
$http:parse-entity-autoxs:stringauto
$http:parse-entity-xmlxs:stringxml
$http:parse-entity-html-to-xmlxs:stringhtml2xml
$http:parse-entity-jsonxs:stringjson
$http:parse-entity-textxs:stringtext
$http:parse-entity-rawxs:stringraw
$http:parse-entity-nonexs:stringnone
$http:parse-mode-rawxs:stringraw
$http:parse-mode-statusxs:stringstatus
$http:parse-mode-headersxs:stringheaders
$http:parse-mode-multipart-rawxs:stringmultipart-raw
$http:parse-mode-multipart-headersxs:stringmultipart-headers
$http:parse-mode-fullxs:stringfull

+    

+
     

       
Errors

       
This section defines and describes the error codes that may be raised by the module.