$Id: demos.dbx,v 1.12 2003/08/29 15:56:49 cwilper Exp $
Copyright © 2003 The Rector and Visitors of The University of Virginia and Cornell University
Table of Contents
This manual describes the demonstration objects that are distributed with the Fedora open-source repository software. These objects can be loaded into the repository in one of two ways. The xml source files can be "ingested" into the repository via the Fedora Admin GUI client (from the command prompt, run: fedora-admin). Otherwise, they can be loaded with all other demos by running the demo load script (from the command prompt, run: fedora-ingest-demos [hostname] [port] [username] [password]). The demo object source xml files for the demo objects can be found in the following directory: [FEDORA_HOME]/client/demo
There are two categories of demonstrations:
Local Server Demos - These demos can be run under any conditions. They are intended to work when the Fedora repository server is in a stand-alone condition, for example, if the repository is running without a network connection, or if the repository is behind a firewall and not set up to receive outside connections.
Open Server Demos - These demos can only be run if the Fedora repository server is running as a network accessible server, meaning that it can make outgoing connections AND accept incoming connections. If the repository server is running behind a firewall, the firewall must be configured to allow incoming connections on the port that the repository server is running. The Open Server Demos use distributed content and services that are remote to the repository server.
Once demo objects are ingested into the repository, they can be viewed via a web browser using API-A-LITE or API-A. Remember the URL syntax to get the object profile via API-A-LITE is : http://{hostname}:{port}/fedora/get/{objectPID}
Example: http://localhost:8080/fedora/get/demo:5
Table of Contents
These can be run in two ways. The xml source files can be "ingested" into the repository via the Fedora Admin GUI client (from the command prompt, run: fedora-admin). Otherwise, they can be loaded with all other demos by running the demo load script (from the command prompt, run: fedora-ingest-demos [hostname] [port] [username] [password]).
Simple Document Demo - This Fedora data object (objectPID is demo:18) demonstrates the simplest Fedora digital object scenario. It is the case where we aggregate content in the Fedora object, and let Fedora's default object behaviors provide access to the content. This is an example of a Fedora digital object that has NO DISSEMINATORS. In this case, there are 3 datastreams in the object, one for each format of a particular document (in this case the recent Fedora paper presented at ECDL2002). Since there are no disseminators on the object, we can use the default Fedora object behaviors (the "Default Disseminator" which is identifiable by the behavior definition PID of "fedora-system:3"). The Default Disseminator is dynamically associated with every object in the repository. Its behavior methods are on every object and include the ability to list items in the object, get an item, get the dissemination index, get Dublin Core record, and other information about the object. The results of these methods can be returned as either HTML (method names begin with "view...") or XML (method names begin with "get..."). The end result in that the object is simply a container for content and metadata. The user can view the contents and get any item from the object. While this scenario may be easy to implement and useful, it does not take advantage of Fedora's extensible behavior model where custom behaviors can be associated with the object.
Simple Image Demo - The Fedora data object (objectPID is demo:5) demonstrates the UVA Simple Image behaviors by associating a simple disseminator with the object. There are 4 datastreams in the object, one for each of four different image resolutions. The object has one disseminator that is subscribes to the "UVA Simple Image" behavior definition and uses the Fedora HTTP Image Getter service (behavior mechanism). Four behavior methods are available (getVeryHigh, getHigh, getMedium, and getThumbnail). The fulfillment of the behavior contract entails the Fedora HTTP Image Getter resolving the URL of the appropriate datastream for each of the UVA Simple Image behaviors. There are no transformations performed on the datastreams. This object shows how a behavior definition can be used to create a normalized set of methods for a particular type of object, in this case image objects. The idea here, is that the Simple Image behavior definition provides a standard set of dissemination methods that can be used on any image object that subscribes to the Simple Image behavior definition. As we will see later, different variants of image objects can subscribe to the same behavior definition, and is some cases the datastreams will be dynamically transformed by a service to provide the appropriate image disseminations. This demo shows a simple one-to-one mapping of the datastreams in the object to the behavior methods.
Document Transformation Demo - The Fedora data object (objectPID is demo:14) demonstrates the Document Transformation behaviors. There are 3 datastreams in the object, one XML source document, and two XSLT stylesheets. The object has one disseminator that is associated with the "Document Transform" behavior definition and the Fedora Local Saxon Service (behavior mechanism). Two behaviors are available (getDocumentStyle1 and getDocumentStyle2). When these methods are run as disseminations, the repository mediates access to the Fedora Local Saxon Service to produce the appropriate transformation on the XML source in the object. The dissemination result will be one of two document styles.
These can be run in two ways. The xml source files can be "ingested" into the repository via the Fedora Admin GUI client (from the command prompt, run: fedora-admin). Otherwise, they can be loaded with all other demos by running the demo load script (from the command prompt, run: fedora-ingest-demos [hostname] [port] [username] [password]).
Simple Image Demos - These Fedora data objects (objectPIDs are demo:6 and demo:7) demonstrate the UVA Simple Image behaviors by associating more complex disseminators with the objects. They also demonstrate how two objects with different kinds of datastreams can be made to fulfill the UVA Simple Image behavior contract. The key thing to note here is that both the demo:6 and demo:7 objects have a disseminator that subscribes to the UVA Simple Image behavior definition. However, they each use a different service (behavior mechanism) to fulfill the behavior contract. In the case of demo:7, we have an object with 4 image datastreams, one for each of four different image resolutions. In this object the UVA ImageZoomer service is used to add value to the image datastreams at runtime. When a behavior method is run, the UVA ImageZoomer service will be called upon the wrap the image in a Java applet that provides a standardized, zoomable viewer for the images. No matter which UVA Simple Image behavior is run (getVeryHigh, getHigh, getMedium, getThumbnail), the applet is provided. In the case of demo:6, we have an object with one image datastream, a wavelet-encoded MrSID file. The object has one disseminator that is subscribes to the "UVA Simple Image" behavior definition and uses the UVA MrSID Service (behavior mechanism). Again, the same four behavior methods are available (getVeryHigh, getHigh, getMedium, and getThumbnail). This time, fulfillment of the behavior contract entails the use of the MrSID service to derive the appropriate image resolution out of the MrSID file. Another notable feature of the demo:6 object is that it shows how XML metadata can be put in the object as datastreams too. The XML metadata datastreams can be viewed via the Default Disseminator (run getItemIndex or viewItemIndex). A final important point about these demos is that the behavior mechanism services run remote from the repository. Both the UVA ImageZoomer service and the UVA MrSID Service run as web services at University of Virginia. These demonstrations show how Fedora objects can leverage distributed web services, and most importantly, now the Fedora repository system handles the mediation and binding to these services in a manner that is transparent to the user.
The Fedora data object (objectPID is demo:30) demonstrates the UVA Simple Image behaviors by associating a simple disseminator with the object. There are 4 datastreams in the object, one for each of four different image resolutions. The object has one disseminator that is subscribes to the "UVA Simple Image" behavior definition and uses the Fedora HTTP Image Getter service (behavior mechanism). Four behavior methods are available (getVeryHigh, getHigh, getMedium, and getThumbnail). The fulfillment of the behavior contract entails the Fedora HTTP Image Getter resolving the URL of the appropriate datastream for each of the UVA Simple Image behaviors. There are no transformations performed on the datastreams. This object is almost identical to the Fedora object (objectPID of demo:5) created under the local-server-demos. The major distinction is that the datastreams for this object are of type "R" indicating that their external URLs are to be redirected by Fedora. The Fedora server typically protects the true location of external datastreams by functioning as a proxy service, thereby not exposing the physical datastream locations stored in the Fedora objects. However, there are certain situations where users may not want Fedora to proxy the location of external datastreams. For example, streaming audio and video providers may provide special optimization and performance tuning designed to function with a direct connection between a web browser and the content provider. Another example is datastreams that are protected by HTTP Basic authentication. Fedora will provide its own authentication and access policy in a future release to handle access restrictions. In the interim, the redirected datastream type can be used to access external datastreams that are protected with Basic authentication. In the Fedora object in this example, all 4 datastreams are protected on the external web server using HTTP Basic authentication which requires a username and password in order to access the datastreams. When attempting to execute the disseminations for these datastreams, you will be prompted for a username and password. The required username and password is "fedora".
Userinput Image Demos - These Fedora data objects (objectPIDs are demo:10 and demo:11) demonstrate the UVA Userinput Image behaviors by associating a more complex disseminator with the objects. The UVA Userinput Image behavior definition was constructed as a demonstration to show how a behavior definition can allow for user input parameters at run time. In this case, the behavior definition has two methods (getThumbnail and getImage). The getImage method takes two user input parameters: the size of the image (e.g., small, medium1, medium2) and whether to wrap the image in a zoomable applet (yes, no). Both objects share this behavior definition and both use the same the UVA MrSID service. Depending on what the user enters, the MrSID Service will derive the proper size of the image, and wrap it with a zoomable applet if the user requested. The UVA MrSID Service runs as web services at University of Virginia. As with the Open Server Simple Image Demos, these demonstrations show how Fedora object can leverage distributed web services.
EAD Finding Aid Demo - This is the most elaborate of the demonstration objects. This Fedora data object (objectPID is demo:17) demonstrates the UVA Encoded Archival Description (EAD) Finding Aid behaviors. It uses the Finding Aid behavior object (bDef objectPID) and the Finding Aid mechanism object ( bMech objectPID is demo:16). The behavior definition for a Finding Aid was constructed to provide a real-life example of a complex disseminator used with electronic texts. In this case, the behavior definition consists of thirteen methods which provide different views of a Finding Aid document.
getTitlePage - displays the Title Page of the Finding Aid.
getAdminInfo - displays the Administrative Info section of the Finding Aid.
getSummaryInfo - displays the Summary section of the Finding Aid.
getBiogHistInfo - displays the Biographical and Historical section of the Finding Aid.
getScopeContentInfo - displays the Scope and Content Notes section of the Finding Aid.
getComponentInfo - displays the Components section of the Finding Aid.
getArrangeInfo - displays the Arrangement section of the Finding Aid.
getOrgInfo - displays the Organization section of the Finding Aid.
getEntireDoc - displays the entire Finding Aid document.
getMenu - displays a list of available behaviors for this Finding Aid.
viewFindingAid - displays the default preferred view of the Finding Aid.
getTitle - retrieve the title of the Finding Aid
searchFindingAid - perform a full-text search on this Finding Aid.
The Finding Aid mechanism object provides the implementation of these behaviors. Note in the mechanism object that the method bindings point to external services that exist on one of the UVA web servers. The majority of the methods are implemented as XSL stylesheets; applying the appropriate stylesheet to the source document and rendering the results in HTML-format. The preferred means of viewing the Finding Aid is through the viewFindingAid method which provides a special web-based presentation of the document consisting of three html-frames. The top frame is generated by using the getTitle method to extract the title of the document and form a banner. The left frame is generated by calling the getMenu method which displays a list of possible behaviors for this particular Finding Aid. The right frame, displays the results of the specific dissemination; the default view is to display the Title Page.
In the sample object, you can select one of the individual methods like getAdminInfo to see how each method functions independently or you can select viewFindingAid to see an example of how the methods have been neatly integrated into a single presentation. For the viewFindingAid, method you will need to supply the PID of this object which is demo:17. This is required since the underlying mechanism is a generic one that can be applied to any Finding Aid in the collection. We have pulled out this single object from the collection to use as an example. You can perform a full-text search on the Finding Aid by selecting the searchFindingAid method. Here, you must supply the PID of the object (demo:17) and your search query string.