XView: MOA2 Object Presentation and Navigation
Technical Details

Overview

 
MOA2 objects are presented to the user through the cooperation of 2 main Java programs: the MOA2 Servlet and the MOA2 Repository Manager. The servlet receives a users request to view a particular MOA2 XML object, but passes this on (via RMI) to the  MOA2 Repository Manager. This Java program activates and loads into memory the MOA2 Java Object corresponding to the requested MOA2 XML Object; it then returns an RMI reference to this object to the servlet. The servlet then queries the MOA2 Java Object directly, and obtains the information that it needs to format an initial display for presentation to the user.  The servlet relays (again via RMI) most of the users subsequent navigation requests directly to the MOA2 Java Object, which processes them and returns the results to the MOA2 Servlet.The MOA2 Servlet formats the results of the users navigation requests for display in the users browser.  For a more complete overview of the XView architecture, see the MOA2 Object Life Cycle document. 

General Technical Information

Main Classes/Objects comprising the XView System

Objects created by the server-side MOA2 Java Objects and transmitted by value for use by the MOA2 Servlet.

Objects of the following classes are created on the server-side, but transmitted by value to the Servlet for use. Since they are referred to in sections on both client-side and server-side classes below, they are presented here first.
DSDescriptors (Datastream descriptors). ManifestationSets

Main server-side classes/objects.

The server-side of the MOA2 tools consists of two main classes of objects: the MOA2 Repository Manager Object (singleton) and MOA2 Java Objects (which correspond to the MOA2 XML Objects in the MOA2 XML Repository).
The MOA2 Repository Manager Object (ArchRepositoryImpl class). The MOA2 Repository Manager Object manages MOA2 Java Objects--the Java objects that represent the individual MOA2 XML Objects in the MOA2 XML Repository. It is responsible for repository services as defined in the ArchRepository Interface (an RMI interface). Its main function is to connect a client, such as the MOA2 Servlet, with the specific MOA2 Java Objects that correspond to the MOA2 XML Objects that a user asks to view. If an MOA2 Java Object corresponding to the requested MOA2 XML Object is already available in the Java Object Respository, then the MOA2 Repository Manager simply loads this into memory, and returns an RMI reference to it to the requesting client. If there is no MOA2 Java Object version of requested MOA2 XML Object already available in the MOA2 Java Object repository, then the MOA2 Repository Manager invokes the generateObject() method of an IDocGenerator object to process the source MOA2 XML Object and produce the corresponding MOA2 Java Object. The Repository Manager then delivers a reference to this MOA2 Java Object to the requesting client; and saves the MOA2 Java Object to the MOA2 Java Object Repository  (as a .ser file) for possible later use.

Moa2 Java Objects (ArchObjectImpl class) .  Clients obtain document manipulation services (including page turning services) via calls on the MOA2 Java Objects.  The available calls are defined in the ArchObject Iinterface (an RMI interface). MOA2 Java Objects are themselves composed primarily of the following objects:

A "table of contents" (or document hierarchy) in the form of an array of ManifestationSets. An ordered array of ManifestationSets represents the document hierarchy as set forth in the <StructMap> section of the corresponding MOA2 XML Object.  An MOA2 document object delivers its "table of contents"--the ordered array of Manifestation Sets--to a client on request.  The client can then use this to construct a table of contents to present to the user in the form of a nested hierarchy.

DataStreams. Aggregated by DSGroups, DataStreams point to the individual resources that together comprise a digitized document. Each DataStream in an MOA2 Java Object can generate a DSDescriptor to represent itself to a client. Furthermore, each DataStream object knows what other DataStream objects represent alternate manifestations of the same discrete division or section of the digitized document as itself. It is therefore able to generate a ManifestationSet comprising the DSDescriptors for itself and its associated DataStreams.

StructMap. The StructMap is a tree structure built from the <StructMap> portion of the source XML document. This tree is used to facilitate paging requests issued when a "Contents" view of the document is active. (It is not used for paging requests issued when a "Thumbnails" view is active, however. )

Main client (MOA2 Servlet) classes/objects.

The MOA2Servlet client derives from the HttpServlet class. For each active user session it creates and maintains the following "Frame" objects, each of which are responsible for generating the HTML for one of the three HTML Frames that together present a particular view of an MOA2 document object in the users browser, and that facilitate manipulation of that object by the user.
ContentsFrame. Used to display the table of contents to the user in the upper left-hand frame of the MOA2 Viewer when a contents view is active.

ResourceFrameRight.. Used to display both image and text transcription resources to the user in the right-hand frame of the MOA2 Viewer. This frame offers the user paging capabilities, as well as the ability to control and alter the current view of the MOA2 object. It allows the user, for example, to choose between the various available manifestations of the portion of the MOA2 object that is currently on display.

ResourceFrameLeft. Derives from same base class as ResourceFrameRight. Used to display image and text transcription resources in the upper left-hand frame of the MOA2 viewer (in place of the table of contents). Unlike the ResourceFrameRight, it offers no MOA2 object navigation options.

ThumbnailFrame. Supports a thumbnail approach to an MOA2 object. Presents the thumbnail images associated with an MOA2 object in blocks of 10.

LinkFrame. Presents hot links in the lower left-hand frame that enable the user to view descriptive and administrative metadata associated with the resource currently on display. These links are updated each time a new resource displays, as some of the links presented pertain only to the resource currently on display, and some pertain to the entire MOA2 object.

Technical Overview of main XView functionality.

Document activation.

The following sequence describes how a document is activated for use in the MOA2 servlet client.

Page turning

Selecting an alternate manifestation for viewing in the right-hand or left-hand resource frame.

Selecting an entry point into the document from the table of contents.

Viewing Thumbnails--activating a thumbnail display.

Selecting a Resource for display from the Thumbnail Frame

Requesting next (or previous) set of thumbnails.

MOA2 remote interfaces.

MOA2 services are provided to the servlet via two RMI interfaces: the ArchObject Interface and the ArchRepository Interface
 

ArchObject Interface.

The servlet invokes methods defined in this interface to obtain services from individual MOA2 document objects. Currently there are 3 methods specified in the interface. These are:
 
public ManifestationSet[] getManifestationSets(Object parms[])

public DSDescriptor[] getDSDescriptors (Object[] parms)

public Resource[] getResources(Object[] parms)


Note that the first Object in the parms list for each of these methods is an Integer containing an int constant defined in the ArchObject interface. This constant identifies the requested action The methods defined in the ArchObject interface and their uses are described more fully below.

public ManifestationSet[] getManifestationSets(Object parms[]). This method call allows the client to obtain specific groups of ManifestationSets from an ArchObject. This call is the one most often issued by the servlet against an MOA2 document object; and provides the basis for fulfilling most navigation requests.

Use 1: Obtaining the document "table of contents". The document table of contents or hierarchy is delivered as an array of ManifestationSets. Each ManifestationSet knows its position in the document hierarchy and the servlet can present the table of contents to the user as a nested hierarchy. The array of ManifestationSets that constitute the document hierarchy are obtained from the MOA2 document object via the following form of this method call:
 
ManifestationSet[] ms = getManifestationSets(CONTENTS)


Use 2: Page turning, simple case. Next, Prev and First requests are all fulfilled via a getManifestationSets() call. All paging requests are fulfilled relative to the current resource appearing in the right-hand resource frame, and the DSDescriptor for the currently displayed resource is passed as a parameter in all of the getManifestationSets calls that support paging. Note that although the method call supports the return of an array of ManifestationSets, in the case of simple page turning calls, the array returned consists of just a single ManifestationSet. The forms of the call used for simple paging are:
 

ManifestationSet[] ms = ArchObject.getManifestationSets(NEXT, DSDescriptor)

ManifestationSet[] ms = ArchObject.getManifestationSets(PREV, DSDescriptor)

ManifestationSet[] ms = ArchObject.getManifestationSets(FIRST, DSDescriptor)


Use 3: Page turning, compound case. User may be viewing two manifestations of the same portion of an MOA2 document side-by-side: for example, a page image and its transcription. In the servlet version of our MOA2 client the two views keep pace with one another during page turning. To support page turning in this compound case, the following forms of the getManifestationSets command are used. Note that the DSDescriptors for both of the resources currently on display are included in these forms of the call; and that in the compound case an array of two ManifestationSets is returned.
 

ManifestationSet[] ms =

ArchObject.getManifestationSets(NEXT, DSDescriptor,DSDescriptor)

ManifestationSet[] ms = ArchObject.getManifestationSets(PREV, DSDescriptor,DSDescriptor)

ManifestationSet[] ms = ArchObject.getManifestationSets(FIRST, DSDescriptor, DSDescriptor)


Use 4: Requesting the ManifestationSet for the current resource. Occasionally the servlet may need to ask for the full ManifestationSet that includes the DSDescriptor for a particular resource. To do this, the following form of the getManifestationSets call is used.
 

ManifestationSet[] ms = ArchObject.getManifestationSets(THIS, DSDescriptor)


Use 5: Requesting sets of thumbnail images. The thumbnail images from an available thumbnail group can be presented to the user in blocks of 10 in the thumbnail frame of the MOA2 "viewer". User can move forwards and backwards 10 thumbnail images at a time in the thumbnail frame. The following calls support the presentation of thumbnail images in blocks of 10. Note that the DSDescriptor in the calls below references the thumbnail image relative to which the request is to be fulfilled. An array of 10 ManifestationSets that include the DSDescriptors for the relevant thumbnails are returned.
 

ManifestationSet[] ms = ArchObject.getManifestationSets(THIS,DSDescriptor,10)

ManifestationSet[] ms = ArchObject.getManifestationSets(NEXT, DSDescriptor, 10)

ManifestationSet[] ms = ArchObject.getManifestationSets(PREV, DSDescriptor, 10)


public DSDescriptor[] getDSDescriptors (Object[] parms). Servlet uses this call to obtain specific DSDescriptors and sets of DSDescriptors that it may need to fulfill the users requests for certain services.

Use 1: Obtaining the first DSDescriptor for each of the available thumbnail groups. An MOA2 document may have various categories of images associated with it. For example, there may be page images and photographic images. The page images could include a group of page image thumbnails and the photographic images could include a group of photographic image thumbnails. To present the available thumbnail groups to the user the client uses the following form of the getDSDescriptors call to obtain the first DSDescriptor for each available thumbnail group:
DSDescriptor[] dsd = ArchObject.getDSDescriptors(THUMBNAILS)
The client then presents the available thumbnail groups to the user by asking each of the Thumbnail DSDescriptors to describe itself (DSDescriptor.toString())

Use 2. Obtaining the DSDescriptor for the XML source code. User can ask to view the XML source code for the active MOA2 document object. The servlet gets the DSDescriptor it will need to obtain the XML source code by using the following form of the getDSDescriptors command:

DSDescriptor[] dsd = ArchObject.getDSDescriptors(SOURCE)


public Resource[] getResources(Object[] parms). Various forms of the getResources call were heavily used by a previous applet version of the MOA2 client, because the applet had to obtain all resources to be displayed to the user directly from the MOA2 document object. Nearly all of these uses have been rendered obsolete in the servlet architecture. One use remains, but even this is really just a holdover from the Applet architecture, and will probably eventually be replaced.

Use 1: Obtaining Administrative metadata. Users can ask to view the administrative metadata for the resource currently on view in the right-hand frame of a view of an MOA2 document. The servlet obtains the administrative metadata as a Resource object via a getResources call as follows.
Resource[] r = ArchObject.getResources(ADMINMD, DSDescriptor)
The DSDescriptor referenced represents the resource for which the administrative metadata is desired.

ArchRepository interface.

The ArchRepository provides very basic repository services to a client via two method calls defined in the ArchRepository interface. These are:
public ArchObject getArchObject(String moa2DocumentID)

public String[] listDigitalObjects (Object[] parms)
 

public ArchObject getArchObject(String moa2DocumentID). The servlet can obtain a reference to a specific ArchObject using this call and, passing the moa2DocumentID as a parameter. Currently the moa2DocumentID is either the full URL of the source XML file, or the file path and file name of the source xml file relative to the repository's default directory.

public String[] listDigitalObjects (Object[] parms). The client can obtain lists of the available documents in groups of any size by using this call. The user can then request any document from the list for viewing. (Note that this call is only used to obtain list of documents in the MOA2 Project testbed; it currently has no application in production uses of XView). The specific form of the call used follows. Note that "start" is the sequential number of the document with which the list is to start, and "count" is the number of documents the ArchRepository should include in the list that is returned.

String[] moa2list = ArchRepository.listDigitalObjects(start,count)