Section
Center Image Added

{center}!worddav3482baa3c6b1e77ba7c5ed081a8e157a.png|height=124,width=574!{center}

Author: The Fedora Development Team

...

A number of these features are illustrated in Figure 1.

Why Should You Use Fedora?

...

This document is intended to be hands-on, with you trying the examples on a running Fedora repository. You should therefore, have already downloaded and installed Fedora, and started a server. You should then access the Fedora repository by running the Fedora Administrator interface, fedora-admin, which is located in the FEDORA_HOME/client directory (you can start this program from the command line if you have configured your environment variables properly). Upon starting up the administrator interface you will be presented with the Login screen shown in Figure 2. This document assumes that you have not changed any of the configuration defaults for your Fedora server so the password you enter should be fedoraAdmin. If you have changed your configuration values or are running the Fedora Administrator from a machine different from the machine on which your Fedora server is running you will need to change the values in the Login screen appropriately.

You should read this document in order, since later examples assume knowledge of techniques and definitions introduced earlier.

...

Start by selecting File/New/Data Object in the Fedora Admin GUI. Complete the New Object dialog box as shown in Figure 3.

Check the box for Use Custom PID and enter demo:100. Note that when you do not assign your own PID, the Fedora repository will create one for you. Select the Create button and you should see a window like that shown in Figure 4. Observe that the PID of the created object (in this case demo:100) is displayed in the title bar.

Since our task here is to define the Datastreams in the object, click on the Datastreams tab and you will see a window like that shown in Figure 5. Note that at this point there is only one Datastream in the object – the DC Datastream containing basic descriptive metadata that was automatically created by Fedora. You can select that Datastream and select the Edit button to see the its default contents, with the DC title and identifier fields already filled in.

A few points to note about what you have done so far:

...

Your completed HTML Datastream should look like the dialog as shown in Figure 6 (after you have imported the content).

A few notes on the contents of this dialog:

...

You're done! Your Datastreams window should now look something like that shown in Figure 7, showing all the Datastreams you have entered in the left-side tabs in the window.

You will notice as you click through each Datastream that there is a Fedora URL, giving the unique URL to access each Datastream from the Fedora repository. Try going to a browser and entering one of these URLs – the browser will download the Datastream and display it. These URLs can be used by web applications and REST-based web services that access Datastreams from Fedora Digital Objects. Note that if you are building SOAP-based web services, there are also SOAP methods (getDataStream and getDatastreamDissemination) that provide Datastream access. You can also try entering the root URL for the entire FDO, which is simply the common prefix of all the Datastream URLs – e.g., http://localhost:8080/fedora/get/demo:100. This accesses the header page for the FDO, which allows you to access its Datastreams (available through the item index hyperlink) and disseminations (available through the dissemination index hyperlink).

Figure 8 illustrates the structure of the object you have created and the correspondence of REST-based access requests to the object and its components (via API-A-LITE).

Example 2: Creating a Surrogate for Distributed Content

...

To get started follow the same procedure as illustrated in Figure 3, this time entering Example 2 as the Label and demo:200 as the custom PID. As in Example 1, select the Datastreams tab and then enter the information as shown in Figure 9.

You will enter the Datastream identifier of IMAGE1, a label for this Datastream, and then information about the content. The content is of MIME type image/gif. You should select the Control Group of Redirect, and then enter a URL that specifies the Location of the image file, specifically:

...

The resulting Datastream window should now look like that shown in Figure 10.

You're done! Figure 11 illustrates the role of the redirected Datastream at the time of FDO access via the Fedora REST-based interface (API-A-LITE). You can see this by going to the FDO profile page at: http://localhost:8080/fedora/get/demo:200

You can access the Datastreams for this FDO by viewing the item linked to from the object profile page. Then, select the link for one of the redirected Datastreams. Fedora will redirect your browser to the location of the Datastream content, without streaming the content through the Fedora repository server.

Using Fedora to Produce Dynamic Content

...

Figure 12 shows an abstract view of the different components of the Fedora repository architecture that are key to how Fedora produces "disseminations" of FDO object content.

These layers are:

1. Client: Clients make requests for content disseminations through the Fedora Access service APIs (i.e., API-A-LITE and API-A). These interfaces include operations for discovering and accessing all disseminations that are available for a particular FDO. A FDO can have both static and dynamic disseminations, which are described below.
2. Fedora APIs: The Fedora repository service is exposed via a uniform set of APIs. Fedora's API-A and API-A-Lite provide operations (methods) for accessing FDO content. While the default mode of accessing a FDO delivers the Datastreams (i.e., repository returns the bitstream represented by the Datastream un-transformed), the CMA (Content Model Architecture) enables defining any number of custom services for accessing Datastream content. These custom services are produced when the Fedora repository service calls another Web service to transform Datastream content. Such transformations can be thought of "virtual" views of FDO content, since these views are created dynamically at runtime.
3. Web Services: These are Web-accessible programs that are invoked by HTTP to produce disseminations of FDO content. Note that the Fedora repository itself is a Web service to access the default services of FDOs. Also, Fedora can interact with other Web services to product custom access services that transform FDO content on-the-fly. In this tutorial we will describe how Fedora interacts with simple REST-based services to product such custom services. Custom services are produced when the Fedora repository service itself makes outbound service calls to other Web services using simple REST-based requests. We will not discuss Fedora interacting with SOAP-based web services here.
4. Storage: FDOs objects are stored by the Fedora repository service. Datastreams are constituent parts of FDOs – essentially metadata about the bytestreams. Fedora interacts with low-level storage to access FDOs to fulfill client requests for access to content. Datastreams capture the raw content. As shown in the previous examples, Datastreams can be directly disseminated via the Fedora Access service. Also, Datastreams can serve as input to other custom services that are produced on-the-fly when the Fedora repository service calls upon another Web service at run time (using a raw Datastream as input).

...

At the end of the day, FDOs make references to SDefs, SDeps and CModels as the way of providing extended access points for FDOs (i.e., dynamic content disseminations.) This is done by adding special relationships between the objects that are stored in the RELS-EXT Datastreams of those objects.
Figure 13 indicates the relationships that exist between the four object types. Data objects assert that they conform to a particular Content Model using the hasModel relationship. Content Model objects assert they provide the services included in an SDef using the hasService relationship. Service Deployment objects assert the services for which they provide binding information by using the isDeploymentOf relationship, as well as asserting the Content Models for which they provide service bindings using the isContractorOf relationship.

Figure 14 illustrates the interactions among Fedora and Web services in response to an access request. As indicated, a client makes a request to the Fedora API (with a URL in this case.) The Fedora repository service then determines the content model that is associated with the FDO for which the request is being made. Once it knows the content model, the Fedora repository can discover what SDefs and SDeps are in play for this FDO. Once all of this information is gathered, the Fedora repository can construct a request to the appropriate web service to transform the Datastreams of the target FDO (demo:2). The Fedora repository service invokes a REST-based request to the web service via HTTP, sending along arguments to enable the web service to obtain the required Datastream inputs to fulfill the request. The Fedora repository mediates all invocations with the external web service. When it receives a response from the web service it streams it back to the original calling client. In this case, the response is a transformation based on the raw material of Datastream1 and Datastream2 in the FDO.

Example 3: Using SDefs, SDeps and CModels

...

Select File/Ingest/One Object/From File… in the Fedora Administrator. This will bring up a file selection dialog box as follows:

Browse the file system to select the ingest file for the SDef object whose file name is FEDORA_HOME/userdocs/tutorials/2/example3/SDef.xml. Since this ingest file is encoded as FOXML 1.1 select the FOXML 1.1 radio button as below:
:

This will create the FDO with PID demo:ex3SDef in your repository. This SDef defines one method getContent. This generic method name is intentional – one could imagine this one SDef being used as the basis for several SDeps, each of which produces "content" via a unique transformation of an underlying source. This is one of the advantages of Fedora – providing a common interface despite multiple underlying representations.

...

The resulting Object window should look like that illustrated in Figure 15.

You're done! Figure 16 illustrates the role of this FDO and dissemination service in response to a client request. You can go to the FDO header page at http://localhost:8080/fedora/get/demo:300 and select the View Dissemination Index link. Your newly added dynamic dissemination should now appear, alongside the primitive behaviors for the object. To see the results of this dynamic dissemination, you can either select the Run button for getContent in the Method Index display or simply enter the URL http://localhost:8080/fedora/get/demo:300/demo:ex3SDef/getContent directly.

Example 4 – Modifying Example 3 Using a Redirect Datastream

...

You're done! The demo:500 FDO should now behave exactly the same as the demo:300 FDO in Example 3. Figure 17 refines Figure 16 (with some labeling removed for clarity) with the new redirect configuration.

What's next?

You should now understand the basic mechanisms through which SDefs, SDeps and CModels interact with Data objects to provide a richer dynamic view of the data stored in those objects. The next tutorial (Tutorial 3 – Not yet available) steps you through the process of using the admin client to create a SDef, a SDep, and a CModel from scratch and a Data Object that will function with the control objects to provide customized services similar to those described in the last example of this tutorial. To explore the other features of Fedora, refer to the Fedora Repository Documentation. You can also join the Fedora-users mailing list to ask questions and learn from the experience of other Fedora users.