Client-Server Communication

From Armarius

Jump to: navigation, search

In order to function properly with a large collection, the client side code running on the user's browser has to fetch information from the server. Similarly, when the user modifies an annotation, those changes have to be stored on the server to become permanent. Therefore the client side code has to communicate asynchronously with the server. This is accomplished by exchanging XML documents through the standard HTTP protocol. Form the client-side perspective, this means setting up an XMLHttpRequest JavaScript object, registering a callback function, and calling its open() method. On the server side, this is handed similary to any request to a web page, with the only exception that the script handling the request has to be able to parse the XML docuemnt it received and should output valid XML back to the client. XML was chosen over the much more compact JavaScript Object Notation (JSON) encoding format due to compatibility and security issues.

On the server, scripts that respond to remote calls are located in /app/remote/ directory.

There are 3 type of operations supported by remote invocation: getting the description and metadata for a page, posting an annotation back to server, and asking for keyword proposal.

[edit] Fetching the page description

This operation is initiated by the PageBrowser object. It's purpose is to find information about the image that has to be loaded, including the address of the image to load, the annoatations on the page. The following paramters have to be transmitted in the address:

  • volume - the id in the database of the collection that the user is browsing
  • sort - the id in the databse of the sorting order used to index pages.
  • pg - the position of the page to load, inside the specified ordering
  • search - search expression, if the the results of a search are presented to the user
  • lang - the language of the user interface. Used to filter out metadata from other languages

The server side should look up the requested page, the annotations on it, and then respond with an XML that conforms to the following schema (DTD): 

<?xml version="1.0"?>
<!ELEMENT pages (page+)>
<!ELEMENT page (id,index?,title?,filename,width?,height?,annotations)>
<!ELEMENT id (#PCDATA)>
<!ELEMENT index (#PCDATA)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT filename (#PCDATA)>
<!ELEMENT width (#PCDATA)>
<!ELEMENT height (#PCDATA)>
<!ELEMENT annotations (anno*)>
<!ELEMENT anno (....)> 
<!ATTLIST anno top CDATA #REQUIRED>
<!ATTLIST anno left CDATA #REQUIRED>
<!ATTLIST anno right CDATA #REQUIRED>
<!ATTLIST anno bottom CDATA #REQUIRED>

Note that the elements that the anno tag will contain are left to the implementation. Those elements are to be parsed by the metadata functions of the Annotation object's meta_types object. Here is an example of a page description XML: 

<?xml version="1.0" encoding="utf-8" ?>
<pages>
 <page>
   <id>1</id>
   <index>0</index>
   <title>BJ-23-1</title>
   <filename>data/images/pages/Bj-23_1.jpg</filename>
   <width>600</width>
   <height>800</height>
   <annotations>
     <anno top="0.006" left="0.0933" width="0.1" height="0.035" id="1">
       <keyword>page mark</keyword>
       <transcript>23 01</transcript>
     </anno>
     <anno top="0.698" left="0.48" width="0.1" height="0.038" id="3">
       <keyword>stamp</keyword>
       <keyword>library</keyword>
       <transcript>Bibliotheca Teleki-Bolyai</transcript>
     </anno>
     <anno top="0.356" left="0.313" width="0.046" height="0.07" id="109">
       <keyword>sign</keyword>
       <keyword>mathematical notation</keyword>
       <keyword>greek letter</keyword>
       <transcript>delta</transcript>
     </anno>
   </annotations>
 </page>
</pages>

If the page cannot be found, a response with the 404 HTTP error code will be sent back. If one of the paramters was invalid (for instance, a non-existent sort order was given), a 500 error code will be emitted.


[edit] Saving or deleting an annotation

Saving is performed by the Annotation object, when the user clicks on the save link or outside the annotation and its popup window. In this case a POST request has to be sent with an XML that describes the annotation. The following paramters have to be transmitted in the address:

  • lang - the language of the interface. used to store the language of metadata. Used only when saving
  • action - can be one of the following values:
    • ``add_anno" - means to add the annotation to the database;
    • ``mod_anno" - the current annotation is beign modified only;
    • ``del_anno" - delete the annotation from the database.

The changes made to the annotation have to be sent back to the server encoded as an XML file similar to the one described in , with the following differences: the index, id, title, filename, width, height tags have to be ommitted, and the file should contain one and only one anno tag for the edited annotation, together with its metadata. If the annotation is new, then the anno tag's id attribute has to be omitted as well. The server responds to this request by sending back a similar XML file, with the annotation's id attribute set, together with a filtered list of metadata. The annotation should be updated based on this new specificaition. A 500 HTTP error code will be sent in case of processing errors.

[edit] Keyword proposal

Keyword proposal is handled by the metadata functions from within Annotation.meta_types.keywod. When the user is editing the list of keywords, and presses the comman key, a request is sent back to the server for a list of suggested keywords. This request should be accompanied by the following GET parameters:

  • key - a comma-delimited list of keywords as entered by the user.
  • lang - the language of the interface. Used to filter out keyword in other languages.

The server should respond with an XML document of conforming to the following DTD

Retrieved from "http://www.armarius.org/wiki/index.php/Client-Server_Communication"
Personal tools