<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Introduction</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="book.hw.html">Hyperwave</a></div>
<div class="next" style="text-align: right; float: right;"><a href="hw.setup.html">Installing/Configuring</a></div>
<div class="up"><a href="book.hw.html">Hyperwave</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="intro.hw" class="preface">
<h1 class="title">Introduction</h1>
<p class="para">
<span class="productname">Hyperwave</span> has been developed at
<a href="http://www.iicm.edu/" class="link external">» IICM</a> in Graz. It started with
the name <acronym>Hyper-G</acronym> and changed to Hyperwave when
it was commercialised (in 1996).
</p>
<p class="para">
Hyperwave is not free software. The current version, 5.5 is
available at <a href="http://www.hyperwave.com/" class="link external">» http://www.hyperwave.com/</a>.
A time limited version can be ordered for free (30 days).
</p>
<p class="para">
See also the <a href="ref.hwapi.html" class="link">Hyperwave API</a> module.
</p>
<p class="para">
Hyperwave is an information system similar to a database
(<acronym title="Hyperwave Information Server">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. <em>'en:Title in English'</em> or <em>'de:Titel
in deutsch'</em>. 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.
</p>
<p class="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.)
</p>
<p class="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
<span class="function"><a href="function.hw-pipedocument.html" class="function">hw_pipedocument()</a></span> and <span class="function"><a href="function.hw-gettext.html" class="function">hw_gettext()</a></span>
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.
</p>
<p class="para">
Saying that <span class="function"><a href="function.hw-pipedocument.html" class="function">hw_pipedocument()</a></span> and
<span class="function"><a href="function.hw-gettext.html" class="function">hw_gettext()</a></span> 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 <em>my_object</em>
is mapped to <em>http://host/my_object</em> disregarding where
it resides in the Hyperwave hierarchy. An object with name
<em>parent/my_object</em> could be the child of
<em>my_object</em> 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.
</p>
<p class="para">
Having made this decision a second problem arises. How do you
involve PHP? The URL <em>http://host/my_object</em> will
not call any PHP script unless you tell your web server to rewrite it to
e.g. <em>http://host/php_script/my_object</em> and the script
<em>php_script</em> evaluates the <var class="varname"><var class="varname">$PATH_INFO</var></var>
variable and retrieves the object with name <em>my_object</em>
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 <em>http://host/Hyperwave</em>
This is basically sharing of a namespace by the web and Hyperwave server.
</p>
<p class="para">
Based on the above mechanism links are insert into documents.
</p>
<p class="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. '_'.
</p>
<p class="para">
The network protocol to communicate with the Hyperwave server is called
<a href="http://citeseer.ist.psu.edu/andrews95serving.html" class="link external">» HG-CSP</a> (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 <abbr class="abbrev">HTTP</abbr> to <abbr class="abbrev">HG-CSP</abbr>.
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 <abbr class="abbrev">PLACE</abbr> Language.
<abbr class="abbrev">PLACE</abbr> 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.
</p>
<p class="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 <abbr class="abbrev">HG-CSP</abbr>
but also provides more powerful commands to e.g. retrieve complete
documents.
</p>
<p class="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.
<ul class="itemizedlist">
<li class="listitem">
<span class="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.
</span>
</li>
<li class="listitem">
<span class="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 <span class="function"><strong>hw_object2array()</strong></span>.
Several functions return object records. The names of those
functions end with obj.
</span>
</li>
<li class="listitem">
<span class="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.
</span>
</li>
<li class="listitem">
<span class="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.
</span>
</li>
</ul>
</p>
<p class="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:
<dl>
<dt>
<span class="term">Hidden</span>
<dd>
<span class="simpara">
Number of object records with attribute PresentationHints
set to Hidden.
</span>
</dd>
</dt>
<dt>
<span class="term">CollectionHead</span>
<dd>
<span class="simpara">
Number of object records with attribute
PresentationHints set to CollectionHead.
</span>
</dd>
</dt>
<dt>
<span class="term">FullCollectionHead</span>
<dd>
<span class="simpara">
Number of object records with attribute
PresentationHints set to FullCollectionHead.
</span>
</dd>
</dt>
<dt>
<span class="term">CollectionHeadNr</span>
<dd>
<span class="simpara">
Index in array of object records with
attribute PresentationHints set to CollectionHead.
</span>
</dd>
</dt>
<dt>
<span class="term">FullCollectionHeadNr</span>
<dd>
<span class="simpara">
Index in array of object records with
attribute PresentationHints set to FullCollectionHead.
</span>
</dd>
</dt>
<dt>
<span class="term">Total</span>
<dd>
<span class="simpara">
Total: Number of object records.
</span>
</dd>
</dt>
</dl>
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="book.hw.html">Hyperwave</a></div>
<div class="next" style="text-align: right; float: right;"><a href="hw.setup.html">Installing/Configuring</a></div>
<div class="up"><a href="book.hw.html">Hyperwave</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
