A Guide to Creating Collections

Collections in the DOPs Framework

Collections are special objects in the DOPs framework:

Collection are digital object instances. Treating collections as instances allows the framework to manipulate both collection instances and "ordinary" instances in a uniform manner. This means that for each collection a respective stored digital object should exist, used to store the information contained in the collection object itself. In most cases, supplying collection instances with metadata (desciption of the collection and its contents) and behavior schemes(for manipulating the collection as any other instance and have it participate in desired behavior execution contexts) should suffice.
Collections are DOPs. Given that collections are instances, they should belong to a DOP. Each collection definition refers to a separate DOP, used in the same manner as "ordinary" ones. Notice that collection instances are automatically created during bootstrap and you do not need to instantiate them manually.
Collections are namespaces. A collection acts as the namespace or scope of the sub-collections and the DOPs it contains. The framework allows a collection to contain sub-collections in order to be able to express hierarchical data, such as archival material, for example. Moreover, in order to support fine-grained definitions of digital object classes and/or types and also avoid DOP name collisions, collections are allowed to contain DOPs. More accurately, all DOPs should be defined in the context of a collection. Put in other terms, collections are also used to define the scope of DOPs.

The XML syntax for defining collections is specified in the DOPs XML DTD. Specifically, a collection can be defined as follows.

<!ELEMENT collection (label*, description*, metadata*, digitalContent*, batchImports*, relations*, behavior*, collections*, dops*)>
<!ATTLIST collection
    id CDATA #REQUIRED
    persistentId CDATA #REQUIRED
>
<!ELEMENT collections ((collection|collectionDef)+)>
<!ELEMENT collectionDef EMPTY>
<!ATTLIST collectionDef
    source CDATA #REQUIRED
>
<!ELEMENT dops (dop+)>

As you may notice, a collection definition is allowed to contain a superset of the attribute specifications allowed in a DOP: collections also support specifying labels, descriptions, metadata, digital content, relation contexts and behavior. Moreover, a collection definition may also contain other collection definitions (its sub-collections) and zero or more DOP definitions (the prototypes pertinent to the scope of this collection).

The persistentId collection's property is used to point to the underlying stored object that is used for storing the collection instance. This value depends on the repository you use and its persistent identifier naming scheme.

The Digital Library

In the DOPs Framework the Digital Library is also a collection, referring to the root of the collection hierarchy or, put in other terms, acting as the collection of all collections, DOPs, instances and Behavior Execution Contexts found in the digital library.

The digital library definition abides to the following.

<!ELEMENT dl (label*, description*, metadata*, digitalContent*, batchImports*, relations*, behavior*, collections*, dops*, behaviorExecutionContexts)>
<!ATTLIST dl
    persistentId CDATA #REQUIRED
    structuralRelationContextId CDATA "structure"
>
<!ELEMENT behaviorExecutionContexts (context+)>
<!ELEMENT context (param*)>
<!ATTLIST context
    id CDATA #REQUIRED
    interpreter CDATA #REQUIRED
>
<!ELEMENT param EMPTY>
<!ATTLIST param
    name CDATA #REQUIRED
    value CDATA #REQUIRED
>

As you may notice, a digital library definition contains similar specifications with a collection definition, with the addition of behavior execution contexts.

Moreover, the structuralRelationContextId property defines the common name that should be shared by all structural relation contexts. If you do not assign a value to this property, the default one is used ("structure"). Practically, the structuralRelationContext attribute exists solely for convenience --it is equivalent to defining a relation context identified by value of the structuralRelationContextId property.

Finally, the persistentId dl's property is used to point to the underlying stored object which is used to store the dl instance. This value depends on the repository you use and its persistent identifier naming scheme.

The Paintings, Books and Pages Example

The DOPs Framework offers flexibility in defining collections. Let us present two different scenarios of using the DOPs framework to realize the books and paintings digital library.

Scenario A

The Painting DOP is defined in the paintings collection and Book and Page DOPs are defined in the books collection as follows.

<dl perstistentId="dl-obj">
    ...
    <collections>
        <collection id="paintings" persistentId="col-paintings-obj">
            ...
            <structuralRelationContext>
                <child dop="dl.paintings.painting"/>
            </structuralRelationContext>
            ...
            <dops>
                <dop id="painting">
                    ...
                </dop>
            </dops>
        </collection>
        <collection id="books" persistentId="col-books-obj">
            ...
            <structuralRelationContext>
                <child dop="dl.books.book"/>
            </structuralRelationContext>
            ...
            <dops>
                <dop id="book">
                    ...
                </dop>
                <dop id="page">
                    ...
                </dop>
            </dops>
        </collection>
    </collections>
</dl>

This scenario defines six entities:

The digital library, always identified as "dl".
Two collections with the fully qualified names "dl.paintings" and "dl.books".
Three DOPs with the fully qualified names "dl.paintings.painting", "dl.books.book" and "dl.books.page".

Note: The collection in which a DOP is defined, if desired, can be supplied with a structural relation context in order to be able to store the instances of this DOP as direct children of this collection. This is not mandatory, since it provides the means to "connect" a collection instance with the instances of the DOPs it defines.

In the dl definition shown above, we want to preserve the parent/child hierarchy of instances and for this reason two structural relation contexts are defined in the "dl.paintings" and "dl.books" collections, each one being able to hold "dl.paintings.painting" and "dl.books.book" instances respectively. The "dl.books" collection does not need to treat "dl.books.page" instances as its children, since the latter are defined as children of "dl.books.book" instances.

This parent/child relationship is also active between a collection and its sub-collections. However, in such a case you do not need to explicitly denote each sub-collection as a child of its parent collection, since the DOPs framework performs it automatically. A collection definition that is comprised of sub-collections only, does not need to specify a structural relation context.

Scenario B

All three DOPs are defined in the digital library scope as follows.

<dl perstistentId="dl-obj">
    ...
    <structuralRelationContext>
        <child dop="dl.painting"/>
        <child dop="dl.book"/>
    </structuralRelationContext>
    <dops>
        <dop id="painting">
            ...
        </dop>
        <dop id="book">
            ...
        </dop>
        <dop id="page">
            ...
        </dop>
    </dops>
</dl>

This scenario defines no collections and Painting, Book and Page DOPs are defined in the root (dl) namespace, having the fully qualified names "dl.painting", "dl.book" and "dl.page" respectively.

One could argue that such an approach pollutes the dl namespace. By defining related DOPs in their own collection and avoiding "mixing" disparate DOPs in the same scope you can generate a more easily extensible dl namespace. Nevertheless, it is up to you to define your collections and DOPs in the way that best suits to your needs and such a "flat" configuration may fit well to your digital library needs and requirements.

The "dl.xml" File

The DOPs Framework requires a file named "dl.xml" to contain the definition of the Digital Library. An example "dl.xml" file is the following (Download).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dl SYSTEM "http://www.dops-framework.net/1.0a/dops.dtd">
<dl persistentId="col:dl" structuralRelationContextId="structure">
    <label lang="en">Digital Library</label>
    <metadata>
        <set id="DC">
            <label lang="en">Dublin Core Metadata</label>
            <fields>
                <field id="dc:identifier" isMandatory="true">
                    <label lang="en">Identifier</label>
                </field>
                <field id="dc:title" isMandatory="true">
                    <label lang="en">Title</label>
                    <description lang="en">The title of the resource</description>
                </field>
                <field id="dc:date">
                    <label lang="en">Date</label>
                </field>
                <field id="dc:creator" isRepeatable="true">
                    <label lang="en">Creator</label>
                </field>
                <field id="dc:publisher">
                        <label lang="en">Publisher</label>
                </field>
                <field id="dc:description" isMandatory="true" isBigText="true">
                    <label lang="en">Description</label>
                </field>
            </fields>
        </set>
    </metadata>

    <behavior>
        <scheme id="shortView">
            <label lang="en">Object's short view</label>
            <element id="identifier" ref="DC.dc:identifier"/>
            <element id="title" ref="DC.dc:title"/>
            <element id="creator" ref="DC.dc:creator"/>
            <element id="description" ref="DC.dc:description"/>
            <element id="date" ref="DC.dc:date"/>
        </scheme>
    </behavior>

    <behaviorExecutionContexts>
        <context id="velocity" interpreter="net.dops_framework.modules.VelocityInterpreter">
            <param name="input.encoding" value="UTF-8"/>
            <param name="output.encoding" value="UTF-8"/>
            <param name="file.resource.loader.path" value="d:/dops-modules/templates"/>
            <param name="file.resource.loader.cache" value="false"/>
            <param name="velocimacro.library" value="macros.vm"/>
            <param name="velocimacro.library.autoreload" value="true"/>
        </context>
    </behaviorExecutionContexts>

    <dops>
        <dop id="externalResource">
            <label lang="en">A DOP that models an external resource</label>
            <!-- You can use this DOP as a general purpose DOP modeling
            entities external to your DL and use it in cases that a DL
            pertinent object can reference an external entity. In the DOP
            definition of such a DL pertinent object, add:
            <relations>
                <relationContext id="externalReferences">
                    <target dop="dl.externalResource"/>
                </relationContext>
            </relations>
            -->
            <metadata>
                <set id="DC">
                    <fields>
                        <field id="dc:identifier"></field>
                        <field id="dc:relation_isPartOf"></field>
                        <field id="dc:title"></field>
                        <field id="dc:publisher"></field>
                        <field id="dc:description"></field>
                    </fields>
                </set>
            </metadata>
            <digitalContent>
                <stream id="content" type="referenced"/>
            </digitalContent>
        </dop>
    </dops>


    <collections>
        <!-- define your own collections here -->
    </collections>
</dl>

Navigation

Action