<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 288721 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: pecl, external -->
 
<book xml:id="book.hw" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Hyperwave</title>
 
 <!-- {{{ preface -->
 <preface xml:id="intro.hw">
  &reftitle.intro;
  <para>
   <productname>Hyperwave</productname> has been developed at
   <link xlink:href="&url.iicm;">IICM</link> in Graz. It started with
   the name <acronym>Hyper-G</acronym> and changed to Hyperwave when
   it was commercialised (in 1996).
  </para>
  <para>
   Hyperwave is not free software. The current version, 5.5 is
   available at <link xlink:href="&url.hyperwave;">&url.hyperwave;</link>.  
   A time limited version can be ordered for free (30 days).
  </para>
  <para>
   See also the <link linkend="ref.hwapi">Hyperwave API</link> module.
  </para>
  <para>
   Hyperwave is an information system similar to a database
   (<acronym>HIS</acronym>, Hyperwave Information Server). Its focus
   is the storage and management of documents. A document can be any
   possible piece of data that may as well be stored in file. Each
   document is accompanied by its object record. The object record
   contains meta data for the document. The meta data is a list of
   attributes which can be extended by the user. Certain attributes
   are always set by the Hyperwave server, other may be modified by
   the user. An attribute is a name/value pair of the form name=value.
   The complete object record contains as many of those pairs as the
   user likes. The name of an attribute does not have to be unique,
   e.g. a title may appear several times within an object record.
   This makes sense if you want to specify a title in several languages.
   In such a case there is a convention, that each title value is
   preceded by the two letter language abbreviation followed by a colon,
   e.g. <literal>'en:Title in English'</literal> or <literal>'de:Titel
   in deutsch'</literal>. Other attributes like a description or keywords
   are potential candidates. You may also replace the language
   abbreviation by any other string as long as it separated by colon
   from the rest of the attribute value.
  </para>
  <para>
   Each object record has native a string representation with each
   name/value pair separated by a newline. The Hyperwave extension
   also knows a second representation which is an associated array with
   the attribute name being the key. Multilingual attribute values itself
   form another associated array with the key being the language
   abbreviation. Actually any multiple attribute forms an associated
   array with the string left to the colon in the attribute value
   being the key. (This is not fully implemented. Only the attributes
   Title, Description and Keyword are treated properly yet.)
  </para>
  <para>
   Besides the documents, all hyper links contained in a document
   are stored as object records as well. Hyper links which
   are in a document will be removed from it and stored as individual
   objects, when the document is inserted into the database.
   The object record of the link contains information
   about where it starts and where it ends.
   In order to gain the original document you will have
   to retrieve the plain document without the links and the list
   of links and reinsert them. The functions
   <function>hw_pipedocument</function> and <function>hw_gettext</function>
   do this for you. The advantage of separating links
   from the document is obvious. Once a document to which a link
   is pointing to changes its name, the link can easily be modified
   accordingly. The document containing the link is not affected
   at all. You may even add a link to a document without modifying
   the document itself.
  </para>
  <para>
   Saying that <function>hw_pipedocument</function> and
   <function>hw_gettext</function> do the link insertion automatically
   is not as simple as it sounds. Inserting links implies a certain
   hierarchy of the documents. On a web server this is given by the
   file system, but Hyperwave has its own hierarchy and names do not
   reflect the position of an object in that hierarchy. Therefore
   creation of links first of all requires a mapping from the Hyperwave
   hierarchy and namespace into a web hierarchy respective web namespace.
   The fundamental difference between Hyperwave and the web is the clear
   distinction between names and hierarchy in Hyperwave. The name does
   not contain any information about the objects position in the hierarchy.
   In the web the name also contains the information on where the object
   is located in the hierarchy. This leads to two possibles ways of mapping.
   Either the Hyperwave hierarchy and name of the Hyperwave object is
   reflected in the URL or the name only. To make things simple the second
   approach is used. Hyperwave object with name <literal>my_object</literal>
   is mapped to <literal>http://host/my_object</literal> disregarding where
   it resides in the Hyperwave hierarchy. An object with name
   <literal>parent/my_object</literal> could be the child of
   <literal>my_object</literal> in the Hyperwave hierarchy, though in a web
   namespace it appears to be just the opposite and the user might get
   confused. This can only be prevented by selecting reasonable object names.
  </para>
  <para>
   Having made this decision a second problem arises. How do you
   involve PHP? The URL <literal>http://host/my_object</literal> will
   not call any PHP script unless you tell your web server to rewrite it to
   e.g. <literal>http://host/php_script/my_object</literal> and the script
   <literal>php_script</literal> evaluates the <varname>$PATH_INFO</varname>
   variable and retrieves the object with name <literal>my_object</literal>
   from the Hyperwave server. Their is just one little
   drawback which can be fixed easily. Rewriting any URL would not allow
   any access to other document on the web server. A PHP script for
   searching in the Hyperwave server would be impossible. Therefore
   you will need at least a second rewriting rule to exclude certain
   URLs like all e.g. starting with <literal>http://host/Hyperwave</literal>
   This is basically sharing of a namespace by the web and Hyperwave server.
  </para>
  <para>
   Based on the above mechanism links are insert into documents.
  </para>
  <para>
   It gets more complicated if PHP is not run as a server module or CGI
   script but as a standalone application e.g. to dump the content of
   the Hyperwave server on a CD-ROM. In such a case it makes sense to
   retain the Hyperwave hierarchy and map in onto the file system. This
   conflicts with the object names if they reflect its own hierarchy
   (e.g. by choosing names including '/'). Therefore '/' has to be
   replaced by another character, e.g. '_'.
  </para>
  <para>
   The network protocol to communicate with the Hyperwave server is called
   <link xlink:href="&spec.hyperwave;">HG-CSP</link> (Hyper-G Client/Server
   Protocol). It is based on messages to initiate certain actions, e.g. get
   object record. In early versions of the Hyperwave Server two native
   clients (Harmony, Amadeus) were provided for communication with the
   server. Those two disappeared when Hyperwave was commercialised. As a
   replacement a so called wavemaster was provided. The wavemaster is like a
   protocol converter from <abbrev>HTTP</abbrev> to <abbrev>HG-CSP</abbrev>.
   The idea is to do all the administration of the database and
   visualisation of documents by a web interface. The wavemaster implements
   a set of placeholders for certain actions to customise the interface.
   This set of placeholders is called the <abbrev>PLACE</abbrev> Language.
   <abbrev>PLACE</abbrev> lacks a lot of features of a real programming
   language and any extension to it only enlarges the list of placeholders.
   This has led to the use of JavaScript which IMO does not make life
   easier.
  </para>
  <para>
   Adding Hyperwave support to PHP should fill in the gap of a
   missing programming language for interface customisation. It
   implements all the messages as defined by the <abbrev>HG-CSP</abbrev>
   but also provides more powerful commands to e.g. retrieve complete
   documents.
  </para>
  <para>
   Hyperwave has its own terminology to name certain pieces of
   information. This has widely been taken over and extended.
   Almost all functions operate on one of the following data types.

   <itemizedlist>
    <listitem>
     <simpara>
      object ID: A unique integer value for each object in the
      Hyperwave server. It is also one of the attributes of the
      object record (ObjectID). Object ids are often used as an
      input parameter to specify an object.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      object record: A string with attribute-value pairs of the form
      attribute=value. The pairs are separated by a carriage return
      from each other. An object record can easily be converted into
      an object array with <function>hw_object2array</function>.
      Several functions return object records. The names of those
      functions end with obj.
     </simpara>
    </listitem> 
    <listitem>
     <simpara>
      object array: An associative array with all attributes of an
      object. The keys are the attribute names. If an attribute occurs
      more than once in an object record it will result in another
      indexed or associative array. Attributes which are language
      depended (like the title, keyword, description) will form an
      associative array with the keys set to the language
      abbreviations. All other multiple attributes will form an
      indexed array. PHP functions never return object arrays.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      hw_document: This is a complete new data type which holds the
      actual document, e.g. HTML, PDF etc. It is somewhat optimized
      for HTML documents but may be used for any format.
     </simpara>
    </listitem>
   </itemizedlist>
  </para> 
  <para>
   Several functions which return an array of object records do also
   return an associative array with statistical information about
   them. The array is the last element of the object record
   array. The statistical array contains the following entries:
   <variablelist>
    <varlistentry>
     <term>Hidden</term>
     <listitem>
      <simpara>
       Number of object records with attribute PresentationHints
       set to Hidden.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>CollectionHead</term>
     <listitem>
      <simpara>
       Number of object records with attribute
       PresentationHints set to CollectionHead.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>FullCollectionHead</term>
     <listitem>
      <simpara>
       Number of object records with attribute
       PresentationHints set to FullCollectionHead.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>CollectionHeadNr</term>
     <listitem>
      <simpara>
       Index in array of object records with
       attribute PresentationHints set to CollectionHead.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>FullCollectionHeadNr</term>
     <listitem>
      <simpara>
       Index in array of object records with
       attribute PresentationHints set to FullCollectionHead.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>Total</term>
     <listitem>
      <simpara>
       Total: Number of object records.
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </preface>
 <!-- }}} -->
 
 &reference.hw.setup;
 &reference.hw.constants;
 &reference.hw.apache;
 &reference.hw.reference;

</book>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->