<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = appendix-i.xml                                                     = -->
<!-- = web application management service guide - appendix i              = -->
<!-- ====================================================================== -->
<!-- = 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                            = -->
<!-- ====================================================================== -->

<appendix service="wam" number="i">
  <title>Web application management service reference</title>

  <p>
  This appendix is a reference of the <afnix/> low level web application
  management (wam) service objects.
  </p>

  <table>
    <title>Web application management</title>
    <thead>
      <tr><td>Symbol</td> <td>Description</td></tr>
    </thead>
    <tbody>
      <tr><td>afnix-wam</td><td>module</td></tr>
      <tr><td>afnix:wam</td><td>nameset</td></tr>
    </tbody>
  </table>

  <!-- =================================================================== -->
  <!-- = http reply object                                               = -->
  <!-- =================================================================== -->

  <object nameset="afnix:wam">
    <name>HttpReply</name>

    <!-- synopsis -->
    <p>
    The <code>HttpReply</code> class is a simple designed to format a
    http reply. The class holds a property list which is used to
    format the header and a buffer which is the reply content. When
    the write method is called, the header and the buffer is formatted
    to the output stream argument. The class creates initially the
    <em>content-type</em> property which is initialized to the
    <em>text/plain</em> mime value. 
    </p>

    <!-- predicate -->
    <pred>http-reply-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>HttpReply</name>
      <args>none</args>
      <p>
      The <code>HttpReply</code> constructor creates an empty http
      reply object.
      </p>
    </ctor>

    <ctor>
      <name>HttpReply</name>
      <args>String</args>
      <p>
      The <code>HttpReply</code> constructor creates a http reply
      object with a specific content type. The string argument is the
      mime content type to set.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add-header</name>
      <retn>none</retn>
      <args>String Literal</args>
      <p>
      The <code>add-header</code> method adds a new property to the
      HTTP header. The first argument is the property name. The second
      argument is a literal object which is internally converted to a
      string.
      </p>
    </method>

    <method>
      <name>add-buffer</name>
      <retn>none</retn>
      <args>Literal|Buffer</args>
      <p>
      The <code>add-buffer</code> method adds some content to the HTTP
      reply buffer. The argument can be either a literal r a buffer
      object.
      </p>
    </method>

    <method>
      <name>write</name>
      <retn>none</retn>
      <args>none|Output|Buffer</args>
      <p>
      The <code>write</code> method formats and writes the reply to an
      output stream or a buffer. Without argument, the default output
      stream is used.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = cookie object                                                   = -->
  <!-- =================================================================== -->

  <object nameset="afnix:wam">
    <name>Cookie</name>

    <!-- synopsis -->
    <p>
    The <code>Cookie</code> class is a special class designed to
    handle cookie setting within a htpp transaction. A cookie is
    <em>name/value</em> pair that is set by the server and stored by
    the http client. Further connection with the client will result
    with the cookie value transmitted by the client to the server. A
    cookie has various parameters that controls its existence and
    behavior. The most important one is the <em>cookie maximum age</em>
    that is defined in seconds. A null value tells the client to
    discard the cookie. A cookie without maximum age is valid only
    during the http client session. A cookie can be added to the 
    <code>HttpReply</code> object with the <code>set-cookie</code>
    method. A cookie can be constructed with a <em>name/value</em>
    pair. An optional third argument is the maximum age.
    </p>

    <!-- predicate -->
    <pred>cookie-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Cookie</name>
      <args>String String</args>
      <p>
      The <code>Cookie</code> constructor creates a cookie with a name
      value pair. The first argument is the cookie name. The second
      argument is the cookie value.
      </p>
    </ctor>

    <ctor>
      <name>Cookie</name>
      <args>String String Integer</args>
      <p>
      The <code>Cookie</code> constructor creates a cookie with a name
      value pair and a maximum age. The first argument is the cookie
      name. The second argument is the cookie value. The third
      argument is the cookie maximum age.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>get-version</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-version</code> method returns the cookie version.
      </p>
    </method>

    <method>
      <name>set-version</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-version</code> method sets the cookie version. The
      version number can only be 0 or 1.
      </p>
    </method>

    <method>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the cookie name. This
      is the name store on the http client.
      </p>
    </method>

    <method>
      <name>set-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-name</code> method sets the cookie name. This is
      the name store on the http client.
      </p>
    </method>

    <method>
      <name>get-value</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-value</code> method returns the cookie value. This
      is the value stored on the http client bounded by the cookie name.
      </p>
    </method>

    <method>
      <name>set-value</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-value</code> method sets the cookie value. This is
      the value store on the http client bounded by the cookie name.
      </p>
    </method>

    <method>
      <name>get-maximum-age</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-maximum-age</code> method returns the cookie
      maximum age. The default value is -1, that is, no maximum age is
      set and the cookie is valid only for the http client session.
      </p>
    </method>

    <method>
      <name>set-maximum-age</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-maximum-age</code> method sets the cookie maximum
      age. A negative value is reset to -1. A 0 value tells the http
      client to discard the cookie. A positive value tells the http
      client to store the cookie for the remaining seconds.
      </p>
    </method>

    <method>
      <name>get-path</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-path</code> method returns the cookie path
      value. The path determines for which http request the cookie is
      valid. 
      </p>
    </method>

    <method>
      <name>set-path</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-path</code> method sets the cookie path value. The
      path determines for which http request the cookie is valid.
      </p>
    </method>

    <method>
      <name>get-domain</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-domain</code> method returns the cookie domain
      value.
      </p>
    </method>

    <method>
      <name>set-domain</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-domain</code> method sets the cookie domain
      value. It is string recommended to use the originator domain
      name since many http client can reject cookie those domain name
      does not match the originator name.
      </p>
    </method>

    <method>
      <name>get-port</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-port</code> method returns the cookie port number.
      </p>
    </method>

    <method>
      <name>set-port</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-port</code> method sets the cookie port
      number. This value is not used with a cookie version 0.
      </p>
    </method>

    <method>
      <name>get-comment</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-comment</code> method returns the cookie comment
      value.
      </p>
    </method>

    <method>
      <name>set-comment</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-comment</code> method sets the cookie comment value.
      </p>
    </method>

    <method>
      <name>get-comment-url</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-comment-url</code> method returns the cookie comment
      url value.
      </p>
    </method>

    <method>
      <name>set-comment-url</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-comment-url</code> method sets the cookie comment
      url value. This value is not used with cookie version 0.
      </p>
    </method>

    <method>
      <name>get-discard</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>get-discard</code> method returns the cookie discard flag.
      </p>
    </method>

    <method>
      <name>set-discard</name>
      <retn>none</retn>
      <args>Boolean</args>
      <p>
      The <code>set-discard</code> method sets the cookie discard
      flag. The discard flag the tells the user agent to destroy the
      cookie when it terminates. This value is not used with cookie
      version 0.
      </p>
    </method>

    <method>
      <name>get-secure</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>get-secure</code> method returns the cookie secure flag.
      </p>
    </method>

    <method>
      <name>set-secure</name>
      <retn>none</retn>
      <args>Boolean</args>
      <p>
      The <code>set-secure</code> method sets the cookie secure
      flag. When a cookie is secured, it is only returned by the http
      client if a connection has been secured (i.e use https).
      </p>
    </method>

    <method>
      <name>to-string</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>to-string</code> method returns a string formatted for
      the http reply header. Normally this method should not be
      called since the <code>set-cookie</code> method of the
      <code>httpReply</code> takes care of such thing. 
      </p>
    </method>
  </object>
</appendix>
