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

Both client and server sides of the MOA2 tools are written in Java. Coding is current with JDK1.2.2.
Client functionality is currently provided via a Java servlet running under Tomcat 3.2.2. Initially client functionality was provided via an applet; however this proved problematic on several fronts.
The servlet communicates with the MOA2 Repository Manager and the MOA2 Jave Objects via RMI. We have experimented with CORBA as well; but the current demo tools use RMI.
Client/Server communication is bootstrapped via the RMI Registry running on the server's host machine. The MOA2 Repository Manager registers with the RMI Registry. The Servlet client obtains a reference to the Repository Manager via the RMI Registry; it then obtains references to the individual MOA2 Java Objects that the user asks to view from the Repository Manager.
In addition to the standard Java Class Libraries, the server side of the MOA2 Repository Manager currently use xerces classes from Apache.org and jdom-b5 classes from Jdom.org to process the MOA2.DTD compliant xml files and help convert these into MOA2 Java Objects. The Repository Manager currently has two alternative xml processing classes available to it for producing the MOA2 Java Objects from the raw xml source files. One uses xerces parsing classes to parse the source xml files into a DOM-compliant org.w3c.dom.Document Object. The alternative uses the xerces SAX parser to produce a org.jdom.Document Object (using beta5 JDOM classes from jdom.org). Both of the alternative MOA2 XML processing classes implement the same IDocGenerator interface and can be used interchangeably to process source xml files and build the MOA2 Java Objects.
Tools work thus far has not been done primarily with an eye towards developing a "production" system, but rather to gain experience with technologies new to us (Java, RMI & CORBA, applets), and to explore and demonstrate the potential of the MOA2.DTD as an encoding standard. XView tools, however, are currently being put to some production uses--for presenting of some of the complex MOA2 Objects being mounted as part of Museum Online Archive of California, for example. (These MOA2 objects may be activated in XView by selecting them from the finding aid for University Art Museum's Cha Collection).
Tools have not yet been tested on a large range of MOA2 documents, nor on documents of much complexity (thus far we have very few documents with multiple level hierarchies; and few with associated SGML text transcriptions).The tools will undoubtedly require refinement as they are tested against more complex objects.

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).

Each DSDescriptor identifies a particular DataStream object maintained as part of the corresponding MOA2 Java Object.. DataStream objects are roughly analogous to <File> elements in an MOA2 XML Object and each is associated with (and points to) a particular resource on disk or in memory. This resource could be page image, a pictorial image, text transcription file, embedded or external descriptive metadata, etc.

Each DSDescriptor can provide a user-meaningful description of the resource pointed to by its associated DataStream.

Each DSDescriptor knows and can provide the URL for the resource it represents.

DSDescriptors are generated on demand by the DataStream Objects they represent.

DSDescriptors are lightweight, and hence suitable for transmission to and manipulation by the Servlet.

ManifestationSets

ManifestationSets represent discrete physical or logical divisions of a digitized document or collection; for example, a ManifestationSet might represent page in a diary, or a photograph in a collection of photographs.

A ManifestationSet aggregates (in an array) the DSDescriptors that represent the different available manifestations of the same discrete division of a digitized document that the ManifestationSet represents. For example, the ManifestationSet for the first page of the Breen Diary in the MOA2 testbed includes a DSDescriptor for a gif image of the page, a DSDescriptor for a small jpeg of the page, a DSDescriptor for a large jpeg of the page, and a DSDescriptor for the text transcription of the page.

A ManifestationSet knows which of its DSDescriptors points to the DataStream (and Resource) that represents the default or current view of the section of the digitized document it represents (for example, a medium resolution jpeg)..

Each ManifestationSet can provide a user-meaningful description of the division of the digitized document that it represents (For example "Page 1" for a page in a book; " "January 1, 1889" for an entry in a diary).

The "table of contents" for a particular digitized document consists of an array of ManifestationSets that can be presented to the user as a nested hierarchy. The ManifestationSets comprising the document table of contents or hierarchy know (and can describe) their position in the document hierarchy.

ManifestationSets, like DSDescriptors, are also very lightweight, and suitable for transmission to and manipulation by the Servlet.

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.

Servlet requests reference to selected document object. User selects the desired document from the container list in a finding aid or from some external source such as a catalog record that includes a link to an MOA2 XML Object in the Repository. The servlet "client" receives the users document choice in the form of the name of the source .xml file; the servlet sends this choice to the MOA2 Repository Manager. The Repository Manager determines if the corresponding MOA2 Java Object (ArchObjectImpl object) is already available as a .ser file from the MOA2 Java Object Repository; if so, it activates this MOA2 Java Object and returns a reference to the activated object to the servlet. If the Java Object version of the requested MOA2 object is not available, the repository asks its IDocGenerator object to generate the needed MOA2 Java Object from the source xml file. The repository then returns a reference to the newly generated MOA2 Java Object to the servlet.

Servlet requests table of contents from document object. Using the MOA2 Java Object reference returned by the Repository Manager, the servlet asks the MOA2 Java Object for the document table of contents (in the form of an array of ManifestationSets). It uses this to prepare a table of contents display for the user. Basically it reconstructs the array of ManifestationSets into a tree structure; and then asks the ManifestationSet at each node of the tree to describe itself (ManifestationSet.toString())

Servlet obtains DSDescriptors for Thumbnail groups. As part of its document initialization process, the Servlet also requests and obtains from the MOA2 Java Object an array of DSDescriptors that represent the available Thumbnail groups. (In general there would be a thumbnail group for each level of the document hierarchy for which thumbnail images are available). The DSDescriptors in the array that is returned represent the first DataStreams of each DSGroup (DataStream group) that constitutes a group of thumbnail images. The servlet uses these as the basis for offering the available thumbnail views to the user by thumbnail group..

Servlet displays the root resource .

The servlet takes the ManifestationSet that is at the root of the document table of contents (or hierarchy), and obtains from this the DSDescriptor for the default manifestation of the root (probably a page image).

The servlet obtains the URL for the default manifestation of the root from the DSDescriptor, and displays the associated resource via the ResourceFrameRight for the users session. (That is, the servlet asks the ResourceFrameRight to generate the HTML necessary to display the resource in the right-hand frame of the MOA2 viewer "running" in the users browser). In the course of preparing the display, the ResourceFrameRight queries the ManifestationSet representing the root of the document hierarchy for a full list of the manifestations of the root that are available; it presents these as "alternate view" options to the user.

In addition, using the DSDescriptors for the available Thumbnail groups obtained as described above, the ResourceFrameRight also offers the available thumbnail views as alternate view options that the user can activate in the left-hand frame. User can ask either to view an alternate manifestation in the left-hand frame (in place of the table of contents); or s/he can ask to approach the document via one of the available thumbnail groups.

Page turning

User can ask to view the next or previous section of an MOA2 object by clicking the "next" or "prev" buttons at the top of the right-hand resource frame.
The servlet asks the MOA2 Java Object for the ManifestationSet that represents the next or previous "page" (depending on which way the user is moving). The servlet sends along the DSDescriptor for the resource currently on display as a parameter in its request..
Using the DSDescriptor sent by the servlet, the MOA2 Java Object determines the DataStream that represents the next or previous resource that should be displayed to the user as a result of the next/prev operation.. The exact way it goes about this depends on whether a thumbnail view or a table of contents view is currently active in the requesting client.
The MOA2 Java Object asks the DataStream representing the next or previous resource to be viewed to generate a ManifestationSet that aggregates the DSDescriptors for all of the available manifestations of the "next" or "prev" view of the object, including itself. In this ManifestationSet the DSDescriptor for the DataStream generating the ManifestationSet is marked as the default manifestation. The server returns this ManifestationSet to the servlet.
The servlet takes the ManifestationSet, and obtains from it the DSDescriptor for its default manifestation. The servlet obtains the URL for this manifestation from the DSDescriptor, and generates the HTML to displays this resource in the right-hand resource frame of the MOA2 Viewer. Again, in the course of preparing the display, the ResourceFrameRight queries the ManifestationSet representing the result of the "next" or "prev" operation for a full list of the available manifestations; these are presented these as "alternate view" options to the user.
If the table of contents is currently on view, the ManifestationSet representing the result of the "next" or "prev" operation is queried as to its position in the document hierarchy. The ContentsFrame then highlights the corresponding entry in the table of contents.

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

The right-hand resource frame of the MOA2 viewer has two scroll-down list boxes. These offer to the user all of the available manifestations of the portion of the document currently on view. The left scroll-down list box controls what appears in the upper left-hand frame of the "viewer". The right scroll-down list box controls what appears in the right-hand frame. The user can select the manifestation s/he wants to view in the right-hand or left-hand resource frames from the appropriate scroll-down list box.
Once the user has selected an alternate manifestation for viewing, the servlet obtains the DSDescriptor for the selected manifestation (this is on-hand; the servlet does not need to go back to the server for it). The servlet then gets the URL for the corresponding resource from this DSDescriptor, and displays the requested manifestation in the right-hand or left-hand resource frame.

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

User can select her/his entry point into a document by clicking on one of the entries in the table of contents.
The servlet client gets the ManifestationSet corresponding to the entry in table of contents selected by the user. From this ManifestationSet it obtains the DSDescriptor for the Resource that is to be displayed. (Client asks the ManifestationSet for the DSDescriptor in its set of DSDescriptors that represents the resource that is closest in format to the resource currently on display. Thus if a medium-sized jpeg is currently on display, the servlet will ask for the DSDescriptor for a medium-sized jpeg when it prepares to display a resource corresponding to the newly selected table of contents entry).
The servlet then gets the URL for the resource to be displayed from this DSDescriptor, and displays the resource in the right-hand resource frame.

Viewing Thumbnails--activating a thumbnail display.

User selects the desired Thumbnail group from the scrolling list of views available for the left-hand frame. (The available thumbnails are presented by group based on the encoding in the xml source document. For example, in the case of a photoalbum, two groups of thumbnails might be available for selection from the left-frame view selection list: one of thumbnails of the page images and one of thumbnails of the individual photographs).
The servlet has on hand the DSDescriptor for the first Thumbnail resource in the Thumbnail group selected by the user. (See above) Using this DSDescriptor as a parameter, the servlet (via the ThumbnailFrame for the users session) asks the MOA2 Java Object for the ManifestationSets corresponding to the first 10 thumbnails in the thumbnail group indicated by the DSDescriptor.
The ThumbnailFrame queries each of the 10 ManifestationSets returned by the MOA2 Java Object in turn, and obtains the URL for its default manifestation (the thumbnail). It uses the 10 URLs obtained thus to display the set of 10 thumbnail images to the user.
Using the first ManifestationSet in the set of 10 ManifestationSets returned above, the servlet asks this ManifestationSet for the DSDescriptor from its set of DSDescriptors that most closely corresponds to the DSDescriptor of the Resource currently on display in the right-hand Resource Frame.
The servlet then gets the URL for the resource to be displayed from this DSDescriptor, and generates the HTML necessary to display this resource to the user.

Selecting a Resource for display from the Thumbnail Frame

User selects desired Thumbnail by clicking on it in the Thumbnail Frame.
The servlet asks the ManifestationSet corresponding to the selected thumbnail for the DSDescriptor of the manifestation that most closely matches the format and resolution the Resource currently on display in the right-hand resource frame.
The servlet then uses this DSDescriptor to get the URL for the resource corresponding to the selected thumbnail that is to be displayed; it generates the HTML necessary to display this resource to the user in the right-hand frame.

Requesting next (or previous) set of thumbnails.

User can explicitly or implicitly request the next or previous set of 10 thumbnails in the group of thumbnails currently being viewed. (User makes an explicit request by clicking "Next set" or "Prev set" button in the thumbnail frame. User makes an implicit request by paging beyond the limits of the current thumbnail set.)
The servlet obtains the DSDescriptor for the last (or first) thumbnail in the set currently on display in the thumbnail frame. (If the operation is a "next" operations, the servlet will pick up the DSDescriptor for the last thumbnail in the group of 10 on display; if the operation is "prev" the servlet will pick up the DSDescriptor for the first thumbnail in the group of 10 on display).
Using this DSDescriptor as a parameter, the servlet asks the MOA2 Java Object for the ManifestationSets that correspond to the next 10 (or previous 10) thumbnails in the currently active thumbnail group. The MOA2 document object returns these ManifestationSets to the servlet.
Via the ThumbnailFrame for the users session, the servlet queries each of the 10 ManifestationSets returned by the MOA2 Java Objectt in turn, and obtains the URL for its default manifestation (the thumbnail). It uses the 10 URLs obtained thus to display the next or previous set of 10 thumbnail images to the user.

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)

XView: MOA2 Object Presentation and Navigation Technical Details