Interface between Middleware and DB-Adapter
References
Requirements
- Support for complex queries
- Programming language independecy
- Easy to use
- Fast transfers
- Standard protocols
Protocol overview
The Interface
The interface between Middleware and DB-Adapter consists of several PHP scripts.
All scripts are places in the same path - the URL of DB-Adapter.
Middleware stores this URL in it's database as "base_url" for each DB-Adapter.
SCRIPT: query.php
Represents the interface for searching.
- DBA uses it's own cache
- no problem with copyright
- cache refresh per day (for example...)
Queries will be case insensitive. The plus ("+") sign will be substitute spaces. There fill be no WHERE clause - searching is executed in all fields unless specified in the Google style like... author:Vasulka. The list of WHERE-like query modifiers will be defined elsewhere. The NOT modifier will be implemented as the preceeding minus ("-") sign. It is also planned to implement OR modifier later on.
Query example:
some fulltext search mediatype:Audio mediatype:Video
There will be constructed a temporary table in the DBA database for every query. Some columns will be just an extract from the daily generated table, the rest of columns will be created on the fly (but still the generation time will be very short, as it is planned to implement some hierarchical indexes and other sophisticated kinds of searching)
Accepts parameters (case-sensitive):
* QUERY: the google-like query string
* USERNAME: the username used by authorisation module of the DB-Adapter (this is optional)
* PASSWORD: the password used by authorisation module of the DB-Adapter (this is optional)
* LANGUAGE: DB-Adapter could use this value to generate language-specific values (this is optional)
* ATTR and FACTORS: tuples of attr. names and corresponding search factors
* NOCBMI: if the value is "1", values from indexing module will be excluded from result. (this is optional)
NOTE: NOCBMI was reimplemented as oasis attribute "nocbmi"
The result will be:
- First line is the return code
- Second line is the textual description
- Third line is the identifier of created temporary table
Example:
0
Temporary table is ready
tmp_table_123
Return codes:
* 0: OK
* 1: DB server down
* 2: General error
* >2: Something nasty has happened but we don't know what ;-)
SCRIPT: auth.php
Each search request could be extended with USERNAME and PASSWORD parameters.
This allows DB-AAdapter to alter results according to user privileges used in particular database. If the privileges are not supported by the database, DB-Adapter simply ignores the USERNAME/PASSWORD pair.
Accepts parameters:
* USERNAME
* PASSWORD
The result will be:
* 0: access granted
* 1: access denied
* >1: Something nasty has happened but we don't know what ;-)
SCRIPT: getids.php
Accepts parameters:
* TABLE: the temporary table created by DB-Adapter
The result will be:
* first two lines contain the error code and reply message
* next lines contain list of of all origin_ids in the requested temporary table - one origin_id per line
* It should be noted that each line must be terminated by newline character escpecially the last line.
* In case of error, following error-codes should appear.
** 1 Table name not specified
** 2 DB connection failed
** 3 DB query failed
- 4 Could not open config file
Example:
0
Result is ready
123123
234533
124242
568659
346347
567567
SCRIPT: cleanup.php
Drops the tamporary table created by DB-Adapter.
Accepts parameters:
* TABLE: identifier of the tamporary table generated by query.php
The result will be:
* 0: Temporary table deleted successfully
* 1: Temporary table does not exist.
* 2: Could not delete temporary table.
* 3: Table name not specified
* 4: DB connection failed
* 5: Could not open config file
* >5: Something nasty has happened but we don't know what ;-)
SCRIPT: detail.php
Loading values from all attributes of a given resource (improved version of load.php optimized for detail-view).
Accepts parameters:
* TABLE (optional): identifier of the tamporary table generated by query.php. If the parameter is not specified, data will be taken directly from daily cache.
* ORIGINID: unique identifier of the resource
The result will be:
* first two lines contain the error code and reply message
* next lines contain results - one value per line
* each line obeys following format:ATTRNAME VALUE
* if the value contains newlines, they must be converted to \n or \r as wll as backslashes must be converted to \\ (PHP function addcslashes($string, "\n\r\\") should do the work)
* In case of error, following error-codes should appear.
** 1 Wrong parameters
** 2 DB connection failed
** 3 DB query failed
** 4 Could not open config file
Example
QUERY:
http://foobar?ORIGINID=9675
REPLY:
origin_id 12345
title foobar title
language en
language cz
origin_id 23456
title This title\ncontains multiple\nlines
title Yet another title
language pl
SCRIPT: multiload.php
Loading multiple columns in a single request, suitable for big data transfers (improved version of load.php).
Accepts parameters:
* TABLE: identifier of the tamporary table generated by query.php
* ATTRNAME: comma separated list of names of attributes (columns of the temporary table)
* COMPRESS: 1, if the result will be compressed
The result will be:
* first two lines contain the error code and reply message
* next lines contain results - one value per line
* each line obeys following format:ORIGINID ATTRNAME VALUE
* if the value contains newlines, they must be converted to \n as wll as backslashes must be converted to \\ (PHP function addcslashes($string, "\n\r\\") should do the work)
* In case of error, following error-codes should appear.
** 1 Wrong parameters
** 2 DB connection failed
** 3 DB query failed
** 4 Could not open config file
Example
QUERY:
http://foobar?TABLE=tmp_1&ATTRNAME=origin_id,title,language
DB-Adapter could use mechanism similar to the following SQL code:
select origin_id, 'origin_id',origin_id from tmp_1
union select origin_id, 'title', title from tmp_1
union select origin_id, 'language', language from tmp_1
REPLY:
12345 origin_id 12345
12345 title foobar title
12345 language en
12345 language cz
23456 origin_id 23456
23456 title This title\ncontains multiple\nlines
23456 title Yet another title
23456 language pl
In the example above the multiload.php returned 2 resources, each resource contained 3 requested attributes and some of the attributes had multiple values. The 23456's title was an example of multiline value escaped by \n.
Notes:
* While calling multiload.php, middleware doesn't send any ORIDIN_IDS to DB-Adapter because DBA returns full columns from temporary table.
* if the requested ATTRNAME does not exist in DBA's temporary table, script should return array with empty strings for each origin_id or even better 'MISSING-IN-DBA' string for debugging purposes.
* The script could use gzipped HTTP respose if the client supports it. In PHP this is implemented like following example
<?php
ob_start('ob_gzhandler');
echo 'this will be compressed transparently';
?>
SCRIPT: player.php
Generats HTML code (web page with integrated media player) for playing the media from specified offset in the file/stream.
Accepts parameters:
* ORIGINID: the unique identification of artwork in remote database
* OFFSETS: list of offsets in miliseconds delimited by comma eg. 12,34,124
The result will be:
* HTML code with appropriate embed and object elements.
SCRIPT: institution.php
Generates redirector URL for the artwork. If you want to redirect user's browser to another location use HTTP header "Location".
EXAMPLE PHP CODE:
<?php header('Location: http://www.google.com') ?>
Accepts parameters:
* PROVENANCE: value of the attribute provenance
* ORIGINID: value of the attribute origin_id
The result will be:
* HTML page.
SCRIPT: logo.php
Accepts parameters:
* PROVENANCE: value of the attribute provenance
* ORIGINID: value of the attribute origin_id
* SIZE: possible values are:
** small (ciant proposed 32x16)
** medium (ciant proposed 64x32)
** large (ciant proposed 128x64)
The result will be:
* first line is the URL
DEPRECATED SCRIPT: load.php
Loading of values of attributes on demand.
Accepts parameters:
* TABLE: identifier of the tamporary table generated by query.php
* OFFSET: offset in the result-set (optional, default 0)
* SIZE: size of the result-set (optional, default infinite)
* ATTRNAME: column in the temporary table
* ID[]: list of origin_ids
The result:
* The result will be Serialized PHP array with key as origin_id and value as value of the requested attribute.
* In case of error, the result will be serialized PHP string with error code and message.
** 1 Wrong parameters
** 2 DB connection failed
** 3 DB query failed
** 4 Could not open config file
serialize("$errorCode $errorMessage");
Notes:
* if the requested ATTRNAME does not exist in DBA's temporary table, script should return array with empty strings for each origin_id or even better 'MISSING-IN-DBA' string for debugging purposes.
serialize(array('12345'=>)) or serialize(array('12345'=>'MISSING-IN-DBA'))
* in case of multiple values, the multiarray should be returned
serialize(array('123'=>array('ISBN','ISSN','UMID')))
* The script could use gzipped HTTP respose if the client supports it. In PHP this is implemented like following example
<?php
ob_start('ob_gzhandler');
echo 'this will be compressed transparently';
?>
| 
