<?xml version="1.0"?>

<!-- ====================================================================== -->
<!-- = chapter-2.xml                                                      = -->
<!-- = web application management service guide - chapter 2               = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 1999-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter service="wam" number="2">
  <title>Low level service object</title>

  <p>
  This chapter covers  low level service object available in the 
  web application management service module. These objects are
  designed to resolved specific operations which cannot be handled by
  high-level objects.
  </p>

  <!-- http reply -->
  <section>
    <title>HTTP reply class</title>

    <p>
    The <code>HttpReply</code> class is a base class designed to handle
    a HTTP reply transaction. Most of the time, this object is not
    needed since it is used by high level object. However, there is
    some situation where it might become handy. For example, a CGI
    script needs to reply with a text file that will be use for
    download. In this case, the <code>HttpReply</code> object provides
    a simple mechanism to perform this operation.
    </p>

    <example>
    const reply (afnix:wam:HttpReply)
    </example>

    <p>
    The <code>HttpReply</code> class operates with a buffer which is
    used to accumulate characters. When the buffer is ready, this one
    is sent along with a header. The HTTP 1.1 protocol requires at
    least to inform the client of the content type of the data being
    transferred. The <code>HttpReply</code> has by default a
    <em>text/plain</em> content-type property set by default. This
    property can be changed at the object construction.
    </p>

    <example>
    # create a reply object
    const reply (afnix:wam:HttpReply)
    # add some data
    reply:add-buffer "Hello world"
    # write the reply to the output
    reply:write
    </example>
  </section>

  <!-- cookies -->
  <section>
    <title>Cookie object</title>

    <p>
    The <code>Cookie</code> object is a special object that can be
    used during a http session, to post data to the http client. The
    idea behind <em>cookies</em> is to be able to maintain some state,
    during the user session for some time. A cookie is a
    <em>name/value</em> pair and eventually an expiration time. By
    default, the <afnix/> cookie object are defined for one http
    client session, but this behavior can be changed.
    </p>

    <!-- managing cookies -->
    <subsect>
      <title>Managing cookies</title>

      <p>
      A cookie is created with a <em>name/value</em> pair and
      eventually an expiration time. Such expiration time is called
      the <em>maximum-age</em> and is automatically formatted by the
      object. With two arguments a session cookie is created. With a
      third argument as an integer, the constructor set the maximum
      age in seconds.
      </p>

      <example>
      # create a cookie with name/value
      const cookie (afnix:wam:Cookie "cartid" "123456789")
      </example>

      <p>
      The cookie implementation follows the recommendation of the
      RFC-2965 for http state management. The most important point to
      remember is the interpretation of the maximum age that differs
      from one cookie version to another. With version 1, which is the
      default, the maximum age is defined relatively in seconds, while
      it is absolute with version 0.The maximum age is set either at
      construction or with the <code>set-max-age</code> method.
      The <code>set-max-age</code> method sets the cookie life time in
      seconds, in reference to the current time. A negative value is
      always reset to -1 and defined a session cookie. A 0 value tells
      the http client to remove the cookie. The <code>set-path</code>
      method defines the path for which this cookie apply.
      </p>
    </subsect>

    <!-- adding a cookie -->
    <subsect>
      <title>Adding a cookie</title>

      <p>
      Once the cookie is defined, the <code>set-cookie</code> method
      of the <code>HttpReply</code> object can be used to install the
      cookie. Combined with the <code>write</code> method, the
      cookie can be send to the http client.
      </p>
    </subsect>
  </section>
</chapter>
