AWS: what is the difference between Response.Acknowledge and Response.Build ?

AWS: what is the difference between Response.Acknowledge and Response.Build ?

[Natasha Kerensikova]

Hello,

I have little question about these functions in AWS.Response:

   function Build
     (Content_Type  : String;
      Message_Body  : String;
      Status_Code   : Messages.Status_Code      := Messages.S200;
      Cache_Control : Messages.Cache_Option     := Messages.Unspecified;
      Encoding      : Messages.Content_Encoding := Messages.Identity)
      return Data
   with Post => not Is_Empty (Build'Result);
   --  Return a message whose body is passed into Message_Body. The
   --  Content_Type parameter is the MIME type for the message
   --  body. Status_Code is the response status (see Messages.Status_Code
   --  definition).


   function Acknowledge
     (Status_Code  : Messages.Status_Code;
      Message_Body : String := "";
      Content_Type : String := MIME.Text_HTML) return Data
   --  Returns a message to the Web browser. This routine must be used to
   --  send back an error message to the Web browser. For example if a
   --  requested resource cannot be served a message with status code S404
   --  must be sent.

What is exactly the difference between `Build (Type_Str, Body_Str, S404);`
and `Acknowledge (S404, Body_Str, Type_Str);` ?

Peeking into the implementation, it seems there is currently no
difference between them, however the quoted comments imply a semantic
difference. I guess that means that it means that an implementation
difference might emerge in the future.

The problem with comments is that they can be a bit more ambiguous than
Ada code.

Is "must" as strong as when it is used in RFCs? Or is more like a piece
of advice?

What is an "error message"? Does it include 3xx HTTP codes?

Or am I wrong interpreting the comments, with Acknowldge and Build
equivalent when a response body is present, while Acknowldge is able to
build header-only responses?


Thanks in advance for your insights,
Natasha

Re: AWS: what is the difference between Response.Acknowledge and Response.Build ?

[Pascal Obry]

Hello Natasha, 

> I have little question about these functions in AWS.Response:
> 
>    function Build
>      (Content_Type  : String;
>       Message_Body  : String;
>       Status_Code   : Messages.Status_Code      := Messages.S200;
>       Cache_Control : Messages.Cache_Option     := Messages.Unspecified;
>       Encoding      : Messages.Content_Encoding := Messages.Identity)
>       return Data
>    with Post => not Is_Empty (Build'Result);
>    --  Return a message whose body is passed into Message_Body. The
>    --  Content_Type parameter is the MIME type for the message
>    --  body. Status_Code is the response status (see Messages.Status_Code
>    --  definition).
> 
> 
>    function Acknowledge
>      (Status_Code  : Messages.Status_Code;
>       Message_Body : String := "";
>       Content_Type : String := MIME.Text_HTML) return Data
>    --  Returns a message to the Web browser. This routine must be used to
>    --  send back an error message to the Web browser. For example if a
>    --  requested resource cannot be served a message with status code S404
>    --  must be sent.
> 
> What is exactly the difference between `Build (Type_Str, Body_Str, S404);`
> and `Acknowledge (S404, Body_Str, Type_Str);` ?

If I rememeber correctly these two calls are 100% equivalent. But the
Acknowledge as different default parameter making it easier to use when
replying:

   return Acknowledge (S404);

> What is an "error message"? Does it include 3xx HTTP codes?

The message displayed by the Web browser.

-- 
  Pascal Obry /  Magny Les Hameaux (78)

  The best way to travel is by means of imagination

  http://v2p.fr.eu.org
  http://www.obry.net

  gpg --keyserver keys.gnupg.net --recv-key F949BD3B