Escolar Documentos
Profissional Documentos
Cultura Documentos
Getting Started:
Creating Fedora Objects using the
Content Model Architecture
Version 12/20/2007
Table of Contents
1
2
3
4
5
6
Figures
Figure 1 - Fedora repository as mediator for services and content ..................................... 4
Figure 2 Fedora Administrator Login Screen .................................................................. 5
Figure 3 - New object dialog .............................................................................................. 7
Figure 4 - Configuring an object......................................................................................... 8
Figure 5 - Datastream display ............................................................................................. 9
Figure 6 - Adding a new managed content datastream ..................................................... 10
Figure 7 - Complete datastreams for example 1 ............................................................... 11
Figure 8 - Example 1 digital object and datastreams ........................................................ 12
Figure 9 - Adding a datastream with type Redirect .......................................................... 13
Figure 10 - Example 2 datastream display........................................................................ 15
Figure 11 - Example digital object and redirected datastream ......................................... 16
Figure 12 - Abstract View: Key Fedora Components for Producing Disseminations of
Content .............................................................................................................................. 17
Figure 13 Relationships between Data objects and CModel/BDef/BMech objects for
CMA ................................................................................................................................. 19
Figure 14 Dynamic dissemination access ...................................................................... 20
Figure 15 Example 3 Linking a Digital Object to a Content Model.............................. 24
Figure 16 - Example 3 dissemination via CMA ............................................................... 25
Figure 17 - Dissemination with redirect datastream ......................................................... 27
Client
Uniform REST
and SOAP
Interface
Digital Objects
Fedora Repository
web
services
appropriate for more advanced content management tasks. These include management of
content and associated metadata, multiple versions of content, content available in
multiple formats, and dynamically generated content from local and dynamic sources.
You should read this document in order, since later examples assume knowledge of
techniques and definitions introduced earlier.
All pathnames assume that you have set your FEDORA_HOME environment variable and
descend from the directory defined by that variable.
All URLs that access the Fedora repository assume that the host:port of the repository is
localhost:8080.
Decisions about what to include in a digital object and how to configure its datastreams
are basic modeling choices as you develop your repository. The examples in this tutorial
demonstrate some common models that you may find useful as you develop your
application.
The Content Model field is available for more advanced applications and can be left blank
for now. Also, 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 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 in Figure 5. Note that at this point there is only
one datastream in the object the DC datastream for basic descriptive metadata that was
automatically created by Fedora. You can select that datastream and select the Edit
button to see the default contents of this Datastream, with the DC title and identifier
fields already filled in.
You will notice that the Control Group of the DC datastream is Internal XML
Metadata. As explained earlier, Fedora has a number of control group types, of
which this is one. This type is appropriate for metadata that is represented in
XML Dublin core metadata being one example. A digital object can have
multiple metadata datastreams, for example MARC, LOM, Dublin Core, and
others.
You can directly edit the Dublin Core metadata e.g., add new Dublin Core fields
- by selecting the Edit button and modifying the contents of the text pane. .
When you press Save Changes, Fedora will check that the datastream is wellformed XML.
You may also create Dublin Core metadata (or any other XML-based metadata) in an
external XML editor and use the Import button to replace the datastream with this data.
When you press Save Changes, Fedora will check that the datastream is well-formed
XML.
You will notice that there are optional fields on the datastreams pane for Format URI (to
refine the media type meaning with a URI that identifies the media type) and Alternate
Ids to capture any other existing identifiers you would like to associate with a datastream.
We will not be using these in this tutorial.
It is now time to add the eprint document formats as new datastreams. You can find
content for creating the datastreams in this example in:
FEDORA_HOME/userdocs/tutorials/2/example1/artex.html
FEDORA_HOME/userdocs/tutorials/2/example1/artex.pdf
FEDORA_HOME/userdocs/tutorials/2/example1/artex.tex
To do this, select the New tab on the left side of the window. Well start with the html
format. To insert data into the datastream, you use the Import button. This presents a
dialog that will allow you to import from your local file system or from a URL.
Your completed HTML datastream should look like the dialog as shown in Figure 6
(after you have imported the content).
Note that the Control Group is Managed Content. As shown in the descriptive
text this datastream type is appropriate for any type of data (mime type), in
contrast to Internal XML Metadata. Once you select this radio button, you can
select from the variety of Mime Types of the managed content in this case
text/html.
You can now select the Save Datastream button and repeat the same process to add the
pdf and TeX datastreams. For the pdf, you can select Mime Type: application/pdf and
import the file ex1.pdf. For TeX, you can select Mime Type: text/plain and import the file
ex1.tex. In each case you should enter appropriate IDs and Labels.
Youre 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 SOAPbased web services, there are also SOAP methods (getDataStream and getDissemination)
that provide digital object access. You can also try entering the root URL for the entire
digital object, 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 digital
object, 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).
demo:100
http://localhost:8080/fedora/get/demo:100
Digital Object Header Page
Fedora API
DC
HTML
http://localhost:8080/fedora/get/demo:100/PDF
application/pdf
TEX
Fedora Repository
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:
http://www.frogsonice.com/froggy/images/toads.gif
Pertaining to the selection of a Control Group, you have two choices if you want
the datastream to point to content that resides outside the Fedora repository
(External Referenced Content and Redirect). In this case we chose Redirect .
To review, the meaning of the two options for mapping to external content are:
Make sure that the MIME Type choice matches that of the content offered by the
external source, in this case image/gif.
In the same manner, you can now proceed to add the two other datastreams with locations:
http://www.werc.usgs.gov/fieldguide/images/hycafr.jpg and
http://www.aquariumofpacific.org/images/olc/treefrog600.jpg
You should respectively identify these datastreams as IMAGE2 and IMAGE3. (Note that if
these sample URLs are no longer active, you can enter other URLs pointing to jpeg
images to complete this tutorial exercise.)
Finally, add another datastream labeled MyText (containing some descriptive text about
the images), with MIME Type text/html. Assign this datastream a Control Group of
Managed Content indicating that the content will be imported and stored permanently in
the Fedora repository. Import the content from the following location:
FEDORA_HOME/userdocs/tutorials/2/example2/mytext.html.
The resulting datastream window should now look like that shown in Figure 10.
Youre done! Figure 11 illustrates the role of the redirected datastream at the time of
digital object access via the Fedora REST-based interface (API-A-LITE). You can see
this by going to the digital object profile page at:
http://localhost:8080/fedora/get/demo:200
You can access the datastreams for this digital object 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.
demo:200
http://localhost:8080/fedora/get/demo:200
Digital Object Header Page
Fedora API
DC
http://localhost:8080/fedora/get/demo:100/IMAGE3
Image/jpeg
IMAGE1
IMAGE2
IMAGE3
MyText
Fedora Repository
In both cases, static and dynamic, disseminations are available via REST or SOAP
requests from clients to the Fedora Access service (API-A and API-A-LITE). The
nature of the disseminated content the format of the underlying data, where it is located,
and whether it is static or dynamically generated is invisible from the client perspective.
As a result, a repository manager can significantly alter the nature of a digital object and
the web services that it uses while maintaining the same interface vis--vis the client.
Correspondingly, two digital objects with entirely different structure can appear the
same from the perspective of consuming clients.
The remainder of this section presents a series of examples demonstrating how to create
digital objects that exploit web services. The initial examples make use of services
available in the Fedora software release (they run as local services within the Fedora
server container). Later examples demonstrate how to construct your own custom objects
with external web services. Before proceeding with the examples, this introduction
summarizes the concepts and defines the terms used in the examples. Dont worry if the
concepts are not entirely clear at first. You should read them now and then refer back to
them as you work through the examples.
Figure 12 shows an abstract view of the different components of the Fedora repository
architecture that are key to how Fedora produces disseminations of digital object
content. .
Figure 12 - Abstract View: Key Fedora Components for Producing Disseminations of Content
3. Web Services: These are Web-accessible programs that are invoked by HTTP to
produce disseminations of digital object content. Note that the Fedora repository
itself is a Web service to access the default services of digital objects. Also,
Fedora can interact with other Web service to product custom access services that
transform digital object content on-the-fly. In this tutorial we will describe how
Fedora interacts 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: Digital objects are stored in the Fedora repository service. Datastreams
are constituent parts of digital objects essentially the content streams. Fedora
interacts with low-level storage to access digital objects to fulfull 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 another custom services
that are produced on-the-fly when the Fedora repository service calls upon
another Web service at runtime (using a raw datastream as input).
The process of creating digital objects with dynamic content disseminations involves
creating linkages between these layers. During this process you will create and employ
the following:
Behavior Definition (or BDef): A digital object that is a template for client-side
services, defining a set of abstract operations (methods) and their client-side
arguments. Association of a BDefwith a digital object augments the basic
behavior of the object with the operations defined in the BDef template. A BDef
may be associated with more than one digital object, thereby augmenting all of
them with the same operations.
Behavior Mechanism (or BMech): A digital object that registers within Fedora the
capability of web service(s) to perform the operations defined by a specific BDef.
This registration includes defining service binding metadata encoded in the Web
Service Description Language (WSDL) and also a data profile of the BMech.
The data profile defines the types of inputs that are considered compatible with
the service. In particular it declares the MIME types that are needed by the
respective web service to perform its task. Multiple BMechs may be registered
for an individual BDef, thereby exposing a generic client-side interface (defined
by the BDef) over multiple data and web service foundations (defined by the
BMechs).
Content Model (or CModel): A digital object that in addition to being used to
store information that will allow you to validate whether a data object constitutes
a valid object corresponding to that content model. The Content Model is also an
important piece for doing disseminations in the Content Model Architecture. A
Data Object will indicate which Content model they represent via a special RELS-
EXT relationship. The Content Model indicates which BDef (or BDefs) it is
associated with (also with a special RELS-EXT relationship).
These three kinds of special Fedora objects are stored in Fedora repositories. The set of
all BDefs represents a registry of all the kinds of abstract services supported by the
Fedora repository. The set of all BMechs represents a registry of all the concrete
service bindings for the abstract service definitions supported by the Fedora repository.
The set of all CModels represent a registry of the different user-defined types of data
objects that exist in that Fedora repository.
At the end of the day, other digital objects make references to BDefs, BMechs and
CModels as the way of providing extended access points for digital objects (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 Relationships between Data objects and CModel/BDef/BMech objects for CMA
Figure 14 illustrates the interactions among Fedora and Web services in response to a
access request. As indicated, a client makes a request to the Fedora API (with a URL in
this case), the Fedora repository service figures out what content model is associated with
the digital object that the request is being made for. Once it knows the content model,
the Fedora repository can discover what BDefs and BMechs are in play for this digital
object. 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 digital
object (demo:2). The Fedora repository service invokes an 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 digital
object.
Client Request
http://localhost:8080/fedora/get/demo:2/
demo:bdef1/m1?arg1=val1
Input
Datastreams
demo:2
Client Response
Fedora API
demo:cmodel1
DC
Datastream1
demo:bdef1
Datastream2
Datastream3
demo:mech1
Fedora Repository
Web Service
Response
Web Service
Browse the file system to select the ingest file for the BDef object whose file name is
FEDORA_HOME/userdocs/tutorials/2/example3/bDef.xml. Since this ingest file is encoded as
FOXML select the FOXML radio button as below:
This will create the digital object with PID demo:ex3bDef in your repository. This BDef
defines one method getContent. This generic method name is intentional one could
imagine this one BDef being used as the basis for several BMechs, each of which
produces content via a unique transformation of an underlying source. This is one of
Service Contract: the BMech indicates the PID of the BDef that it is related to.
This is like saying that the BMech provides and implementation of the BDef.
Service binding metadata (i.e., in WSDL) : concrete binding for the getContent
method that is defined. Specifically, the WSDL indicates that the getContent
operation binding exists at the base URL of http://localhost:8080/service/saxon.
Note that this service is hosted at the same host and port as the Fedora repository.
As noted earlier, this is a local service that is packaged with Fedora.
Data input profile that indicates that the BMech service operation getContent will
take the following inputs at runtime:
o xsl with MIME type text/xml.
o source with MIME type text/xml.
Next follow the same procedure to ingest a sample CModel object into the repository.
Select the file FEDORA_HOME/userdocs/tutorials/2/example3/cModel.xml. This will create the
digital object with the PID demo:ex3cModel. This CModel describes the datastreams that
should be present in data objects that conform to this content model, it also has a RELSEXT hasBDef relationship link to the digital object demo:ex3bDef ingested previously.
In the Enter Relationship dialog that appears, in the Predicate: drop-down dialog,
select the entry fedora-model:hasContentModel and in the Object: text entry box,
enter the string info:fedora/demo:ex3cModel, and then press the OK button.
You should then see the newly created relationship in the table at the bottom of
the New RELS-EXT window. Press the Save Datastream button to save this
newly created datastream.
The resulting Object window should look like that illustrated in Figure 15.
Youre done! Figure 16 illustrates the role of this digital object and disseminator in
response to a client request. You can go to the digital object 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:ex3bDef/getContent directly.
Client Request
http://localhost:8080/fedora/get/
demo:300/demo:ex3bDef/getContent
Input
Datastreams
demo:300
HTML response
Fedora API
demo:ex3cModel
DC
XSL
(XML to HTML)
demo:ex3bDef
Source
(poem data)
demo:ex3bMech
Fedora Repository
Saxon Service
Web Service
Create a new digital object (the XSL digital object). Assume that the system
assigns a PID of demo:400. Create one datastream in addition to the DC with ID
XSL. As before, this datastream should be configured as:
o ID - xsl
o Control Group - Managed Content
Create another digital object (the disseminator digital object). Assume assigns
the a PID of demo:500.
ID - source
Control Group - Managed Content
MIME type text/xml
Label - Poem XML Source
Import location: FEDORA_HOME/userdocs/tutorials/2/example3/poem.xml
o Now create the datastream that will redirect to the XSL in demo:400 as
follows:
ID - xsl
Control Group - Redirect
Mime Type text/xml
Label - Poem XSL Transform
location: http://localhost:8080/fedora/get/demo:400/XSL
Youre done! The demo:500 digital object should now behave exactly the same as the
demo:300 digital object in Example 3. Figure 17 refines Figure 16 (with some labeling
removed for clarity) with the new redirect configuration.
Client Request
http://localhost:8080/fedora/get/
demo:300/demo:ex3bDef/getContent
DC
HTM L Output
Fedora API
DC
Redirected
Datastream
access
XSL
(xml to HTML)
XSL
(redirect)
Source
(poem data)
Fedora Repository
Saxon Service
8 Whats next?
You should now understand the basic mechanisms through which BDefs, BMechs 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 BDef, a BMech, 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 full documentation. You can also join the Fedorausers mail list to ask questions and learn from the experience of other Fedora users.