Accusoft.PrizmViewer10.AnnotationServer
Annotation Server Source Code Overview
| Concepts > Annotation Server Source Code Overview |
The Prizm® Annotation Server sample source code is designed using an object-oriented methodology, which can be thought of as having an interface layer, and classes that are used by the interface layer.
The interface layer is written in ASPX for the ASP.NET sample, and JSP for the Java Server Pages sample. This layer interfaces to the RequestHandler class, which then interfaces with other classes.
The following chart displays these relationships:
The major components of the source code are:
The interface layer provides a code layer which allows for native communication between the web server and the RequestHandler class. This layer is not a class, but code which provides a bridge between the web server interface to the RequestHandler class. The code in this layer should be minimal. This class will always return data to the web server, using either XML or HTML data and always returning a success code to the web server. The HTTP response code is always set to 200 by Prizm Annotation Server.
For ASP.NET, global.asax is responsible for loading configuration parameters from the Web.config file.
The RequestHandler Class is responsible for evaluating requests from the web server, to validate the request, determine whether it is a request to retrieve or save annotations, validate the XML annotation data, and use the PersistentStore class to retrieve or save annotations as appropriate. It performs a "merge" where changes from the annotations from Prizm Viewer modify the annotations that already existed, demonstrating how the server can service multiple users concurrently. It is also responsible for returning the appropriate XML or HTML which is returned to the Interface Layer.
For the JSP sample, this class will load the configuration parameters from the Web.xml file.
This is an abstract class which is used to support retrieving and saving annotation data to a persistent store. This class defers the details of reading and writing annotation data to the persistent store. This class serves as the base class for the FileStore and DatabaseStore classes.
The FileStore class is derived from the PersistentStore class, and provides additional code for actually reading and writing data to a file system based store. It uses a file which is located in a hierarchical directory structure which uniquely maps to the image specified in the Request's F (filename) and P (page) parameters.
The DatabaseStore Class is derived from the PersistentStore class, and provides additional code for actually reading and writing data to a database store. It uses a database record which is located in a table, which can be uniquely mapped to the image specified in the Request's F (filename) and P (page) parameters.
Prizm Annotation Server uses the framework XML classes to read, validate, and modify the annotation data using the XML Schema (PV10AnnotationsSchema), developed for NotateXpress and used with Prizm Viewer.
There are three required parameters to specify on both the Get and Post requests made to a Prizm Annotation Server. These parameters provide Prizm Annotation Server with information needed to uniquely identify the image to retrieve or save annotation data. See the Communication with Prizm Viewer topic for more detailed information.
If you are annotating images, you must uniquely identify images. The source code sample requires that an image URL be unique. It is possible that this could be modified to utilize session information to uniquely identify images instead, but this is outside the scope of the sample.
The f parameter identifies the image that the annotations are associated with. This value should contain the URL of the image the annotations apply to.
The p parameter identifies the page in the image file that the annotations are associated with. The first page in the file is 0. If the image is not a multi-page file, this value must be 0.
Prizm Annotation Server code immediately increments this value, so that the first page is 1 after the parameter is read. This is done to adhere to a requirement for NotateXpress, that the first page is 1.
This parameter identifies the version of the annotation server interface to be used. For Prizm Viewer, this value is 2.0.
Interface Layer
This layer consists of code that provides the application interface to the web server. It instantiates the RequestHandler object, and invokes the ProcessRequest method to process the request.
Config Class
This class contains the configuration settings for the annotation server. The class member variables contain default values, which are updated by the Configuration File application (global.asax in ASP.Net and ProcessRequest in Java) when the web configuration file is processed.
See the Accusoft.PrizmViewer10.Admin.chm and Accusoft.PrizmViewer10.Configuration.chm Help files for more information on installation customization and configuration settings. RequestHandler Class
This class is the most complex class. It performs the following steps:
1) Parses and validates the parameters
2) Determines the type of request:
a. GET (retrieve) request:
i. Retrieves the persisted annotation data if it exists, using the FileStore or DatabaseStore, as appropriate
ii. Optionally validates the XML retrieved
iii. Saves the value to return, either XML (success) or HTML (failure)
b. POST (save) request:
i. Obtains the data to be saved from the request object
ii. Optionally validates the XML data to save
iii. Obtains the data already stored in the persistent class
iv. Optionally merges the data from the request object with the data from the persistence object.
1. The annotation data from the request object will have attributes set to identify lists of annotations (identified by a GUID attribute) that have been added, deleted, or modified.
2. The modified list is converted to delete, then add. This results in modified annotations being replaced.
v. Saves the merged data to the appropriate persistent store (FileStore or DatabaseStore).
vi. Saves the return value in HTML. The ErrorNumber value is set to 0 if no error occurred, or non-zero if an error occurred.
Additional functionality can be implemented in this class, such as setting/verifying security for annotations. For example, the end of the code that performs the "GET" processing, prior to the XML validation step, could modify the XML to set annotation security (please see Annotation Security).
PersistentStore Class
This class is the base class for persistent storage classes. Actual classes for storing data must be derived from this class.
Public Methods: Initialize - method used to initialize the persistent store class. GetAnnotData, SaveAnnotData - methods for retrieving or saving data to a persistent store.
Public Properties: AnnotationsExisted - Boolean property indicating whether annotations already existed (file/database record already existed). This is needed to properly process the merge in the RequestHandler class. OpenEdit - Boolean used to control whether the store is opened in edit mode, which will lock out other changes until the operation completes.
This class also contains a private member function, GetEmptyAnnotData(), that returns a string containing XML that represents the case that no annotations exist for the image. All derived classes will likely need to make use of this member function. FileStore Class
The FileStore class is a persistent store class that uses the file system for storing annotation data. It is derived from the PersistentStore class.
This class contains logic for mapping a image file URL to the local file system. It contains a private method, MapUrlToLocalFile, that takes as an input the image URL, and create a local file system path that uniquely maps to that URL.
The local filename is generated using the following approach:
1) Path = (RootAnnPath) + (image path) + "." + (page) + ".ann"
2) (RootAnnPath) is specified in the Config class: Config.RootAnnPath
3) (image path) is the value specified by the f=(imagepath) parameter, with the following adjustments:
4) The URI portion of (imagepath) is removed
5) Each directory in the path is changed so that every "/" character is changed to ".ad\"
6) The following is appended: "." + "p=" parameter value + ".ann" (i.e.) if Config.RootAnnPath is "C:\annots", and the parameters given to the annotation server are "?f=http://server/images/image.tif&p=1&v=2.0", then the mapping would be"C:\annots\images.ad\image.tif.1.ann"
This class will return the following value:
DatabaseStore Class
The DatabaseStore class is a persistent store class that uses an ODBC database for storing annotation data. It is derived from the PersistentStore class.
Database Schema
The schema provided with this implementation needs to support retrieval by searching for the annotations using the image URL and page number. Because Microsoft Access limits a text field to 255 characters, this implementation breaks the URL into the path (directory) and filename portions. This means that there is a limit on the length of the directory path and filename that can be supported when using an MS Access database as the persistent store.
Below is a breakdown of the fields in the MS Access database table used for annotation persistence:
Field Name
Data Type
Description
Searchable
ImagePath
Text (255 characters)
URL of the image (path portion only)
Yes
ImageFile
Text (255 characters)
Image filename (filename portion only)
Yes
PageNumber
Long Integer
Page within the image file (1 is the first page)
Yes
Data
Memo
Annotation data (XML)
No
If using a database that is more robust than MS Access, the ImagePath and ImageFile fields can be combined into a single field. This class will return the following value:
- If record exists: XML (Record content)
- If record does not exist: XML (Default annotation data)
- If error occurs: HTML (see "Error Response" in "Technical Reference - Prizm Annotation
Server")Error Codes
These values are values that are set in the HTML error response that Prizm Viewer is expecting when an error occurs processing a request for annotation retrieval or storage. See the Debug and Troubleshooting topic for the Error Code values and descriptions.
