php-doc-en/reference/hw/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: pecl, external -->

 <reference xml:id="ref.hw" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Hyperwave Functions</title>
  <titleabbrev>Hyperwave</titleabbrev>

  <partintro>

   <section xml:id="hw.intro">
    &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>'ge: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>
   </section>

   <section xml:id="hw.requirements">
    &reftitle.required;
    <para>
     This extension needs a Hyperwave server downloadable
     from <link xlink:href="&url.hyperwave;">&url.hyperwave;</link>.
    </para>
   </section>

   &reference.hw.configure;

   <section xml:id="hw.apache">
    <title>Integration with Apache</title>
    <para>
     The Hyperwave extension is best used when PHP is compiled as an
     Apache module. In such a case the underlying Hyperwave server can
     be hidden from users almost completely if Apache uses its rewriting
     engine. The following instructions will explain this.
    </para>
    <para>
     Since PHP with Hyperwave support built into Apache is intended
     to replace the native Hyperwave solution based on Wavemaster, we
     will assume that the Apache server will only serve as a Hyperwave
     web interface for these examples. This is not necessary but it simplifies
     the configuration. The concept is quite simple. First of all you
     need a PHP script which evaluates the <varname>$_ENV['PATH_INFO']</varname>
     variable and treats its value as the name of a Hyperwave
     object. Let's call this script <literal>'Hyperwave'</literal>. The URL
     <literal>http://your.hostname/Hyperwave/name_of_object</literal>
     would than return the Hyperwave object with the name
     <literal>'name_of_object'</literal>. Depending on the type of the object
     the script has to react accordingly. If it is a collection, it will probably
     return a list of children. If it is a document it will return the
     mime type and the content. A slight improvement can be achieved
     if the Apache rewriting engine is used. From the users point of
     view it would be more straight forward if the URL
     <literal>http://your.hostname/name_of_object</literal> would
     return the object. The rewriting rule is quite easy:

     <informalexample>
      <programlisting role="apache-conf">
<![CDATA[
RewriteRule ^/(.*) /usr/local/apache/htdocs/HyperWave/$1 [L]
]]>
      </programlisting>
     </informalexample>

     Now every URL relates to an object in the Hyperwave server. This
     causes a simple to solve problem. There is no way to execute a
     different script, e.g. for searching, than the 'Hyperwave'
     script. This can be fixed with another rewriting rule like the
     following:

     <informalexample>
      <programlisting role="apache-conf">
<![CDATA[
RewriteRule ^/hw/(.*) /usr/local/apache/htdocs/hw/$1 [L]
]]>
      </programlisting>
     </informalexample>

     This will reserve the directory <filename>/usr/local/apache/htdocs/hw</filename>
     for additional scripts and other files. Just make sure this rule is
     evaluated before the one above. There is just a little drawback:
     all Hyperwave objects whose name starts with <literal>'hw/'</literal>
     will be shadowed. So, make sure you don't use such names. If you need
     more directories, e.g. for images just add more rules or place
     them all in one directory. Before you put those instructions, don't
     forget to turn on the rewriting engine with

     <informalexample>
      <programlisting role="apache-conf">
<![CDATA[
RewriteEngine on
]]>
      </programlisting>
     </informalexample>

     You will need scripts:

     <itemizedlist>
       <listitem>
        <simpara>
        to return the object itself
        </simpara>
       </listitem>
       <listitem>
        <simpara>
        to allow searching
        </simpara>
       </listitem>
       <listitem>
        <simpara>
        to identify yourself
        </simpara>
       </listitem>
       <listitem>
        <simpara>
        to set your profile
        </simpara>
       </listitem>
       <listitem>
        <simpara>
        one for each additional function like to show
        the object attributes, to show information about users,
        to show the status of the server, etc.
        </simpara>
       </listitem>
     </itemizedlist>
    </para>
    <para>
     As an alternative to the Rewrite Engine, you can also consider using
     the Apache <literal>ErrorDocument</literal> directive, but be aware,
     that <literal>ErrorDocument</literal> redirected pages cannot receive
     POST data.
    </para>
   </section>

    &reference.hw.ini;

   <section xml:id="hw.resources">
    &reftitle.resources;
    &no.resource;
   </section>

   &reference.hw.constants;

   <section xml:id="hw.todo">
    <title>Todo</title>
    <para>
     There are still some things to do:
     <itemizedlist>
      <listitem>
       <simpara>
        The hw_InsertDocument has to be split into
        <function>hw_insertobject</function> and
        <function>hw_putdocument</function>.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        The names of several functions are not fixed, yet.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Most functions require the current connection
        as its first parameter. This leads to a lot of typing, which
        is quite often not necessary if there is just one open
        connection. A default connection will improve this.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Conversion form object record into object array
        needs to handle any multiple attribute.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
   </section>
  </partintro>

&reference.hw.entities.functions;

 </reference>
<!-- 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:"../../../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
-->