Authors: DMA TC Compound/Structured Document Subcommittee

Revision 0.00, 1999 July 28, Dennis Hamilton

• Initial Foundation draft, incorporating back matter contributions of Richard Sauvain, CSDocs Foundation as described in the current CSDocs sketch, and draft material previously created by Alan Babich. Detailed information on extant systems with related features (section 12) is moved to a separate document, with only a brief summary here.

1. Table of Contents

1 Revision History *

2 Table of Contents *

3 Functional Overview/Description *

3.1 Purpose *

3.2 Approach *

3.3 Model Overview *

3.3.1 CSRelationship *

3.3.1.1 Interoperability Considerations *

3.3.1.2 Backward Compatibility Considerations *

3.3.2 CSRoot Renditions *

3.3.3 Identifying Specific Elements in a CSRelationship *

4 Glossary/Nomenclature *

5 New/Changed Classes and Properties *

5.1 DMA Class Changes *

5.1.1 Instance Id {dmaProp_InstanceId} Introduction *

5.1.2 Instance Id Definition *

5.2 DocVersion Changes *

5.2.1 New DocVersion Properties *

5.2.1.1 CSRoots {dmaProp_CSRoots} *

5.2.1.2 CSComponents {dmaProp_CSComponents} *

5.2.1.3 CSRoot Style {dmaProp_CSRootStyle} *

5.2.2 CSRoots Usage *

5.2.3 CSComponents Usage *

5.2.4 CSRoot Style Usage *

5.3 New CSRelationship Class *

5.3.1 Restricted Relationship Properties *

5.3.1.1 Head {dmaProp_Head} *

5.3.1.2 Tail {dmaProp_Tail} *

5.3.2 New CSRelationship Properties *

5.3.2.1 Head Rendition Id {dmaProp_HeadRenditionId} *

5.3.2.2 Head Content Element Id {dmaProp_HeadContentElementId} *

5.3.2.3 Tail Rendition Id {dmaProp_TailRenditionId} *

5.3.2.4 Tail Content Element Id {dmaProp_TailContentElementId} *

5.3.3 Head Rendition Id Usage *

5.3.4 Head Content Element Id Usage *

5.3.5 Tail Rendition Id Usage *

5.3.6 Tail Content Element Id Usage *

6 New/Changed Interfaces *

7 New/Changed Types, Values, and Macros *

8 Architectural Impacts *

8.1 Integration Model *

8.2 Query *

8.2.1 Implementation Considerations for Query of CSDocs *

8.2.2 Interoperability Considerations for Query of CSDocs *

8.3 Internationalization/Localization *

8.4 Content *

8.4.1 Usage Considerations for CSDocs Content *

8.4.2 CSDocs Content Interoperability and Safety *

8.5 Containment *

8.6 Versioning *

8.6.1 Using Versioning with CSDocs *

8.6.2 CSDocs Versioning Interoperability and Safety Considerations *

8.7 Security *

8.8 Naming *

8.9 Locking and Transactions *

8.9.1 Lock Usage Considerations for CSDocs Structures *

8.9.2 Lock Implementation Considerations for CSDocs Structures *

8.9.3 Interoperability of Locking for CSDocs Structures *

9 Compliance & Conformance Issues *

10 Sample Usage *

11 What Requirement Does This Address? *

11.1 Why is this a good solution? *

12 Extant Systems with Similar Features and Related Experiences *

13 Impact on Existing Systems *

14 Backwards Compatibility *

15 Performance Impact *

16 Failure Modes/Crash Recovery *

17 How Is This Incorporated into the Specification? *

18 How Is This Incorporated into the Code and Library Configurations? *

19 Reference Materials *

19.1 Normative Specifications *

19.2 Informative References *

19.3 Background Materials *

 

 

2. Functional Overview/Description
1. Purpose

The Compound/Structured Documents (CSDocs) Foundation extensions to DMA 1.0 provide fundamental capabilities for introducing and managing compound/structured documents in DMA Document Spaces.

CSDocs Foundation establishes a general framework within which multiple compound/structured document families and their implementations may be expressed and used interoperably.

2. Approach

CSDocs extensions are introduced entirely by additions to the DMA 1.0 model. There is no change to anything already in DMA 1.0. The CSDocs Foundation employs mechanisms that are already provided under DMA 1.0.

These additions do not conflict with any other well-known DMA practice. In this way, CSDocs extensions are recognizable wherever supported by DMA-compliant products.

Three overall considerations have guided the formulation of CSDocs:

1. Upward Compatibility. CSDocs extensions are completely upward compatible from DMA 1.0.
1. Backward Safety. That CSDocs extensions can be encountered by DMA 1.0 requesters in a way that preserves DMA 1.0 operation where that is meaningful.
1. Interoperability. That CSDocs extensions are usable in a way that provides interoperability among CSDocs structures implemented on different collections and systems

1. Model Overview
1. CSRelationship

CSDocs introduces CSRelationship, a new subclass of the DMA Relationship class. The relationships between DMA objects representing compound/structured documents (CSRoots) and their components (CSComponents) are expressed using CSRelationship objects (fig. 1).

CSRelationship objects link DMA DocVersions together into CSDocs structures. These structures are used for every variety of compound/structured document represented under the CSDocs extensions. The CSRelationship can be interpreted as establishing that the CSRoot uses or has the specified CSComponent as part of a compound/structured document.

A CSRoot is a DocVersion that has a non-empty CSComponents enumeration property. The CSComponents values are CSRelationships that lead to the components via their Head properties.

 



Figure 1 Organization of CSDoc Structures

A CSComponent is a DocVersion that has a non-empty CSRoots enumeration property. The CSRoots values are CSRelationships with Tail properties that lead to the root documents having this component.

The required class of the CSRelationship Tail property is DocVersion. The reflective property of the Tail property is CSComponents.

The required class of the CSRelationship Head property is DocVersion. The reflective property of the Head Property is CSRoots. DocVersions at the head of a CSRelationship are known as CSRoot objects.

As illustrated in the figure, a CSRoot may also serve as a CSComponent.

A CSDocs structure is manually created by first establishing the CSRoot and CSComponent objects and then inserting the CSRelationship objects that reflect how the root and components are related in the structure. CSDocs structures might also be automatically created as a consequence of creating a CSRoot of a particular kind. Some or all CSComponents and CSRelationships might arise spontaneously as the result of requesting that such a CSRoot be created.

This is the essence of CSDocs and the heart of the foundation model.

This is a structural model. CSDocs Foundation does not specify what the mechanism of compounding or structuring is, nor what the interpretation of the structure is. The presence of CSRelationship linkages is simply the means by which an implementation of CSDocs structures signifies that there is a compound/structured-document interdependency present. There is great freedom in what the specific interpretation of CSRelationships and the semantics of the interdependency. [See the Sample Usages and References.]

1. Interoperability Considerations

The dmaClass_CSRelationship class is to be employed strictly as a virtual class. CSDocs-supporting configurations will use specific subclasses of CSRelationship to differentiate their particular forms and mechanisms of compound/structured-document relationships.

Requesters that are specialized to exploit particular CSDocs structures can distinguish when those mechanisms are supported. The applicable CSRelationship subclasses can be differentiated in the different DMA DocSpaces that are accessed. Multiple-repository queries will also operate more smoothly, finding matching uses of the same concepts. Providers and requesters can form interoperability agreements about particular kinds of CSDocs structures and make the specific subclasses and their definitions widely known.

The recommended sense of the CSRelationship class itself is as a base class for "some compound/structured-document composition relationship." This is consistent with the DMA Relationship class standing generically for "some relationship."

The CSRoot and CSComponent DocVersion subclasses that are linked by particular CSRelationship subclasses can also be restricted as needed to implement a particular structural mechanism. This is accomplished using existing provisions of the DMA 1.0 Object Model [DMA 1.0: sections 3.1.4 Metadata Spaces, 3.1.7 Required and Optional Features, 3.1.8 Extensibility, and section 4.1.35 dmaClass_PropertyDescriptionObject Required Class and Reflective Property Id descriptions].

2. Backward Compatibility Considerations

A CSDocs structure is opaque to a DMA 1.0 requester. This has several consequences:

1. CSRelationship objects can be recognized but will have no DMA 1.0 interpretation beyond "some relationship" and what can be learned by inspecting the class and property descriptions.
1. CSRoot and CSComponent DocVersions, when accessed by DMA 1.0 requesters, appear simply as DocVersion subclasses that may have additional properties for application-specific, local or proprietary additions beyond the well-known DMA 1.0 properties.
1. Access to objects of CSDocs structures will appear no differently than access to any customized DMA 1.0 DocVersion or Relationship subclass.
1. CSDocs-ignorant alteration of CSDocs-involved objects can lead to severing of the CSDocs relationships and their structural integrity. Prevention is by safeguarding against operations that violate an invariant of the implemented CSDocs structure. Such safeguards on the integrity of relationships are already provided [DMA 1.0: <add references>].
1. It is not expected that a CSDocs-ignorant requester will attempt to create a CSDocs structure or be equipped to succeed at such an attempt. A sufficiently-universal DMA 1.0 requester could be guided through a CSDocs construction by a CSDocs-knowledgeable operator.
1. Interoperable usage of DMA 1.0 requesters will diminish to the degree that classes of document previously implemented by DMA 1.0 DocVersions are replaced by CSRoot DocVersion implementations that the DMA 1.0 requester cannot create.

The CSDocs model allows for the possibility of CSDocs structures being automatically generated on the creation of a CSRoot for a suitable type of document. These operations are safe for DMA 1.0 requesters when the resulting CSRoot is successfully usable as the overall document without having to be attentive to the CSDocs structure (e.g., any Renditions are complete renditions).

1. CSRoot Renditions

In the ordinary interpretations of the DMA 1.0 Content Model, any renditions of a DocVersion are expected to be at the same level of abstraction – render what is considered the same document in different presentations or with different stored representations. Also, in the ordinary interpretations of the DMA 1.0 Content Model, it is assumed that the Renditions are complete for what the DocVersion is understood to represent.

With the introduction of CSRoot DocVersions, there is greater potential for ambiguity depending on whether the CSRoot is viewed as standing for the overall document or merely a piece of the overall document that happens to be tied to the other pieces.

For CSDocs, the following position is taken:

1. Any renditions of a particular CSRoot are at the same level of abstraction.
2. The default interpretation of any renditions of a CSRoot is that they are complete renditions and the CSRoot represents the overall document determined by the CSDocs structure that it is the root for.
3. Other interpretations of the renditions are selected by explicit presence of a CSRoot Style property on the CSRoot object. (See 5.2.4 below.)

This approach preserves interoperability with multi-part compound documents stored as single DMA 1.0 documents and with those same documents with their compound structure exposed in the CSDocs model but the CSRoot renditions left intact

1. Identifying Specific Elements in a CSRelationship

In the simplest case, the only thing known when a CSRelationship is present is that there is some interdependency between the CSRoot and the CSComponent of that relationship in realizing the overall compound/structured document represented by the particular CSRoot and all of its related components.

Additional properties are provided on the CSRelationship object to allow more-specific identification of those elements of the CSRoot and CSRelationship that are connected by the particular CSRelationship. (See section 5.3 below.)

The Head of the Relationship can be refined to a specific rendition or to a specific content element of a specific rendition of the CSComponent.

The Tail of the Relationship can be refined to a specific rendition or to a specific content element of a specific rendition of the CSRoot.

So that there is an interoperable way to identify specific elements in any CSDocs structure in any Document Space implementation, the CSDocs Foundation requires that any specific element (rendition or content element) used in this way have an InstanceId property (section 5.1 below).

InstanceId properties have DmaId values. A particular rendition is selected by having its InstanceId value for the Head Rendition Id or the Tail Rendition Id value in the CSRelationship. A particular content element of that rendition is selected by having its InstanceId value for the Head or Tail Content Element Id value.

1. Glossary/Nomenclature

Complete Rendition

A rendition which requires no content elements other than its own in order to render the content of the compound document as a whole.

A DMA DocVersion can have complete renditions even though the nature of those renditions is determined by compound/structured-document relationships. The complete rendition might be composed upon access to the rendition or it might be retained in complete form and adjusted as alterations are made to components on which it depends.

Compound Document

A compound document is an organization of two or more documents in which material of all of them is used to determine the complete document. It is common for one of the documents to be viewed as a "root" or "hub" that represents how its material is combined with those of the others, the "component documents", to produce the complete compound document.

A compound document may or may not also be a structured document (which see). Compound documents tend to be viewed as composed from the components that are supplied for them. An implementation may arrange for alteration of a complete rendition to be reflected in corresponding alterations of the differentiated component documents (and vice versa).

CSRoot

A role of a DocVersion: that of having components and being part of a CSDocs structure.

CSComponent

A role played by a DocVersion: that of being a component in a compound/structured document, i. e., being used/determined by a CSRoot.

Structured Document

Structured documents are ones whose internal architecture is of independent interest. The structural or logical elements of a structured document (pages, paragraphs, illustrations, images, bibliographic notes, and so on) are as if they are free-standing, independent (simple) documents. With structured documents, the separate components are often derived from the complete document and made separately accessible and reusable.

With structured documents, the components are often viewed as given by the complete document, but the electronic representation of both structured and compound views might be supported by a single underlying implementation. The term compound/structured documents reflects this range of application of CSDocs.

2. New/Changed Classes and Properties

Three classes are involved in the CSDocs Foundation:

1. dmaClass_DMA is extended to have the InstanceId property.
2. dmaClass_DocVersion is extended to have two enumerations (CSRoots and CSComponents) and a CSRootStyle property.
3. CSRelationship is introduced as a new subclass of Relationship objects.

1. DMA Class Changes

The extensions made to dmaClass_DMA are presented in a separate Web Page, dmaClass_DMA-CSDocs.html. (click to view).

The single addition is for a new property, InstanceId.

1. Instance Id {dmaProp_InstanceId} Introduction

Implementation not required

Read-only

System-derived

Value-optional

Data type is scalar DmaId

2. Instance Id Definition

This optional property is meaningful only on objects that have corresponding representations as persistent objects.  The object may be dependently persistent or independently persistent.

If a class description specifies that this property is supported, but an instance of the class is not derived from an already-persistent object, the Instance Id property of the instance will have no value.

When an instance of a class supporting Instance Id is an image of an already-persistent object, the value of Instance Id will be a globally-unique DmaId that applies specifically to that already-persistent object.  An Instance Id value is set when an object is first created as persistent using an Execute Change operation or equivalent.  An Instance Id for a persistent object is is never changed, even if the persistent object is updated.  If a persistent object is replaced, the replacement will have a different Instance Id value.

When an independently-persistent object has an Instance Id property, there is a relationship between the value of Instance Id and the OIID property.   When there is an InstanceId, either

1. the <object id> portion of the OIID string contains the Instance Id value in <Textualized Object DmaId> format, or else
1. the optional <object guid> portion of the OIID string is present and contains the Instance id value in <Textualized Object DmaId> format.

1. DocVersion Changes

The extensions made to dmaClass_DocVersion are presented in a separate Web Page, dmaClass_DocVersion-CSDocs.html (click to view).

Three properties are added.

1. New DocVersion Properties

 

1. CSRoots {dmaProp_CSRoots}

Implementation not required

Read-only

System-derived

Value-optional (can be empty)

Data type is enumeration of Object

Required class is dmaClass_CSRelationship

Reflective property is dmaProp_Head

2. CSComponents {dmaProp_CSComponents}

Implementation not required

Read-only

System-derived

Value-optional (can be empty)

Data type is enumeration of Object

Required class is dmaClass_CSRelationship

Reflective property is dmaProp_Tail

3. CSRoot Style {dmaProp_CSRootStyle}

Implementation not required

Value-optional

Data type is scalar DmaId

2. CSRoots Usage

This optional property is meaningful only on objects that may be employed as CSComponents in CSDocs structures.  The reflective property of CSRoots is always the dmaProp_Head property of an admissable dmaClass_CSRelationship subclass instance.   The property represents all of the CSRelationships in which this DocVersion occurs in some way as a CSComponent.

3. CSComponents Usage

This optional property is meaningful only on objects that may be employed as CSRoots in CSDocs structures.  The reflective property of CSComponents is always the dmaProp_Tail property of an admissable dmaClass_CSRelationship subclass instance.  The property represents all of the CSRelationships in which this DocVersion occurs in some way as a CSRoot.

4. CSRoot Style Usage

This optional property is meaningful only on objects that may be employed as CSRoots.  When present, it specifies whether any renditions of the DocVersion are complete documents or whether some style of consolidation must be applied to derive a complete rendition.

If CSRoot Style is not supported or it is supported and has no value, interpretation is the same as when CSRoot Style is supported and the value is the NULL DmaId (DMA_CSR_STYLE_COMPLETE).

When CSRoot Style is supported and it has a value other than DMA_CSR_STYLE_COMPLETE, the value is the DmaId of a registered scheme for how a rendition of the complete document can be obtained or derived.  For any value but DMA_CSR_STYLE_COMPLETE, it must be understood that no CSRoot Renditions is guaranteed to be a complete rendition of the compound/structured document represented by that DocVersion.  

It is anticipated that particular CSRoot DocVersion subclasses may fix the value of CSRoot Style as read-only and system-derived as part of subclass-specific realization of particular CSDoc structures.  Subclasses may also limit the values to selections from a particular set of allowed values.

The following values are defined for CSRoot Style:

• DMA_CSR_STYLE_COMPLETE

Any renditions of the CSRoot are complete renditions which can be used to render the complete document using the CSRoot rendition alone.  This is the corresponding default interpretation of any DMA 1.0 DocVersion that has renditions, without regard to the DocVersion's involvement in an explicit or implicit compound/structured document relationship

• DMA_CSR_STYLE_INCOMPLETE

The CSRoot Renditions do not by themselves provide complete renditions.  A complete rendition is obtained by other means specific to the implementation of this CSRoot DocVersion.   The particular means is made known by application agreement.  No particular means is specified with this value of CSRoot Style.

• other values

Other values of CSRoot Style are safely interpreted as DMA_CSR_STYLE_INCOMPLETE if the actual value is not one with a definition that the application is designed to recognize.  These other values are introduced as part of application agreements so that interoperable use can be made of the CSRoot DocVersion and its renditions.

CSRoot Style is implemented with a DmaId so that the definition and advertising of particular CSRoot styles can occur on a decentralized basis without need for a central assignment authority. 

1. New CSRelationship Class

The new dmaClass_CSRelationship is specified on a separate Web Page, dmaClass_CSRelationship.html (click to view). CSRelationship inherits from Relationship.

CSRelationship restricts the Head and Tail properties and introduces four new optional properties.

1. Restricted Relationship Properties
1. Head {dmaProp_Head}

This object-valued property has its required class restricted to a DocVersion subclass.

The reflective property of Head is CSRoots (dmaProp_CSRoots) for all CSRelationship subclasses.

2. Tail {dmaProp_Tail}

This object-valued property has its required class restricted to a DocVersion subclass.

The reflective property of Tail is CSComponents (dmaProp_CSComponents) for all CSRelationship subclasses.

2. New CSRelationship Properties
1. Head Rendition Id {dmaProp_HeadRenditionId}

Implementation not required

Value-optional

Data type is scalar DmaId

2. Head Content Element Id {dmaProp_HeadContentElementId}

Implementation not required

Value-optional

Data type is scalar DmaId

3. Tail Rendition Id {dmaProp_TailRenditionId}

Implementation not required

Value-optional

Data type is scalar DmaId

4. Tail Content Element Id {dmaProp_TailContentElementId}

Implementation not required

Value-optional

Data type is scalar DmaId

3. Head Rendition Id Usage

If this property is not supported, the CSComponent is simply the DocVersion at the Head. There is no further CSDocs information on how much of and in what way the CSComponent is employed in the compound/structured document via this CSRelationship.

If this property is supported, and it has no value (or the value is the NULL DmaId), then the employment of the CSComponent in the compound/structured document via this CSRelationship is not specific to a rendition of the CSComponent.   It must be assumed that changes anywhere in the CSComponent may impact the portion of the CSRoot that is involved in the relationship.

If this property is supported and it has a non-NULL DmaId value, then a specific rendition of the CSComponent participates in the compound/structured document via this CSRelationship.   The Rendition object involved is the one in the CSComponent's dmaProp_Renditions list property that has the matching InstanceId property value.  If there is no such Rendition, the CSRelationship has been broken.

4. Head Content Element Id Usage

If this property is not supported, the participating element of the CSComponent is determined in accordance with the definition of the Head Rendition Id property.

If this property is supported, the Head Rendition Id property must also be supported.

If this property is supported, and it has no value (or the value is the NULL DmaId), then the employment of the CSComponent in the compound/structured document via this CSRelationship is not specific to a content element of a rendition of the CSComponent.

If this property is supported and it has a non-NULL DmaId value, then so does the Head Rendition Id property.  A specific content element of the CSComponent participates in the compound/structured document via this CSRelationship.   The Content Element object involved is the one in the identified rendition's dmaProp_ContentElements list property that has the matching InstanceId property.  If there is no such Content Element, the CSRelationship has been broken.

5. Tail Rendition Id Usage

If this property is not supported, the CSRoot is simply the DocVersion at the Tail.  There is no further CSDocs information on how much of and in what way the CSRoot is related to the CSComponent via this CSRelationship.

If this property is supported, and it has no value (or the value is the NULL DmaId), then the employment of the CSComponent in the compound/structured document via this CSRelationship is not specific to a rendition of the CSComponent.   It must be assumed that any change to the identified CSComponent can impact any and all of the CSRoot participating in this CSRelationship.

If this property is supported and it has a non-NULL DmaId value, then a specific rendition of the CSRoot participates in the CSRelationship with the identified CSComponent..   The Rendition object involved is the one in the CSRoot's dmaProp_Renditions list property that has the matching InstanceId property value.   If there is no such Rendition, the CSRelationship has been broken.

6. Tail Content Element Id Usage

If this property is not supported, the participating element of the CSRoot is determined in accordance with the definition of the Tail Rendition Id property.

If this property is supported, the Tail Rendition Id property must also be supported.

If this property is supported, and it has no value (or the value is the NULL DmaId), then the portion of the CSRoot involved in this CSRelationship to the identified CSComponent  is not a specific content element of a rendition of the CSComponent. 

If this property is supported and it has a non-NULL DmaId value, then so does the Tail Rendition Id property and a specific rendition content element of the CSRoot is involved in the CSRelationship to the identified CSComponent.  The Content Element object involved is the one in the identified CSRoot Rendition's dmaProp_ContentElements list property that has the matching InstanceId property.  If there is no such Content Element, the CSRelationship has been broken.

1. New/Changed Interfaces

No changes

2. New/Changed Types, Values, and Macros

[add description here of new property identifications, new class identifications, and the new enumeration values.]

3. Architectural Impacts
1. Integration Model

No impact

2. Query

The CSDocs Foundation has no impact on the DMA Query model. The objects employed in CSDocs structures are as amenable to access via Query as any other persistent DMA objects.

The occurrence of CSDocs-related classes in the searchable classes of a document space scope, and the identification of properties as query-able, selectable, and orderable, is determined by the DocSpace implementation, the same as for any other objects usable in queries.

CSDocs-related classes and properties do no introduce any exceptions to the rules for merged scopes.

1. Implementation Considerations for Query of CSDocs

The CSDocs Foundation introduces new well-known properties (InstanceId and related properties on CSRelationship objects) that have DmaId values. If these properties are supported, it is valuable to also support the query operators dmaQueryOperator_EqualId and dmaQueryOperator_UnequalId for those properties. If joins on CSDocs structures are supported, DMA_JOIN_PARTICIPATION_OPERAND can be set as the value of the dmaProp_JoinParticipation property for the dmaQueryOperator_EqualId dmaClass_QueryOperatorDescription instance.

2. Interoperability Considerations for Query of CSDocs

Interoperability of operation across different document spaces is enhanced by ensuring that the different CSRelationship instances that might involve the identical CSRoot and CSComponent are completely differentiated by subclassing and/or user-meaningful searchable properties.

The use of advertised CSRelationship subclasses for particular structuring mechanisms will allow cross-repository search for compound/structured-document structures of the same kind, when that is important for a specialized requester. By having the provider’s CSRelationship also be a searchable class, with useful subclass properties supported, general CSDocs provisions can also be discovered by interoperable requesters.

3. Internationalization/Localization

No impact

4. Content

The CSDocs Foundation does not alter the DMA Content model. CSDocs does depend on the content model being employed in a way that is consistent with the presence of CSDocs structures and the new ways that content may then be viewed.

1. Usage Considerations for CSDocs Content

Any DMA 1.0 usable rendition type and organization generally remains usable as renditions of CSComponents without further consideration. Many DMA 1.0 usable rendition types and Rendition subclasses may also remain usable as renditions of CSRoots.

CSRoot DocVersion subclasses that can be created with initial Renditions may be more likely than DMA 1.0 DocVersions to restrict the usable Rendition subclasses. There may be similar constraints on renditions of CSComponents that are usable in a particular (type of) CSDocs structure.

These are all factors that apply in the DMA 1.0 applications of the DMA Content model. CSDocs implementations may have the effect of expanding the incidence of such restrictions.

2. CSDocs Content Interoperability and Safety

For those CSDocs structures that provide for it, a CSRoot can present complete renditions that are indistinguishable from the renditions that its DMA 1.0 counterpart would create and access. This interoperability does not extend to CSDocs structures that necessarily employ incomplete renditions of forms not safely recognized or modified in DMA 1.0 applications.

5. Containment

The CSDocs Foundation does not impact the DMA Containment model. CSDocs is neutral to the containment model. No conditions are placed on the independent Containable characteristics of CSRelationship objects and of CSRoot and CSComponent DocVersions. (CSRelationship objects are ordinarily not Containable subclasses.)

6. Versioning

CSDocs is neutral to the versioning model, and no modifications to DMA 1.0 Versioning is proposed for the CSDocs Foundation. No conditions are placed on the independent Versionable characteristics of CSRelationship objects and of CSRoot and CSComponent DocVersions. (CSRelationship objects are ordinarily not Versionable objects.)

Versioning of CSRoot, CSRelationship, and CSComponent objects is controlled by the implementation in the same manner as for any DMA objects.

1. Using Versioning with CSDocs

Checkout of a CSRoot will produce a working copy that is created from the CSRoot, usually without any associated relationship objects of any kind [DMA 1.0: section 4.2.44.1 IdmaVersionSeries::SetCheckOutNext].

It is understood that the cloning operation is not required to replicate any object-valued properties (including enumerations) that have independently-persistent objects as values. There is also no requirement to replicate system-derived properties or elements (e.g., automatically-created special renditions or other features, such as OIID and InstanceId properties). The creation of the CSRoot might spontaneously establish CSRelationship and CSComponent objects the same as when any CSRoot of that kind is created. The SetCheckOutNext operation takes no actions to preserve or clone any CSRelationship in which the original CSRoot is a participant.

The predictable automatic behavior is essentially the same behavior available if an application were to fabricate the copy without anything to go by but the class description of the given CSRoot instance, with no special knowledge of any semantics of properties and elements of the CSRoot.

The copying of a dependently-persistent element of a CSRoot is straightforward so long as the IdmaVersionSeries::SetCheckOutNext operation is dealing with objects for which it has complete access to the implementation (i.e., objects implemented by the same Document Space, which is always true under DMA 1.0). For example, the clone DocVersion object has all of the resources possible for dealing perfectly and appropriately with the individual dependently-persistent renditions of the original CSRoot that are inserted on the clone’s dmaProp_Renditions list property. (Appropriate operation may include failing the checkout operation. See section 8.6.2 below.)

Checkout of a CSComponent is subject to the same considerations. The SetCheckOutNext operation takes no actions to preserve or clone any CSRelationship in which the original CSComponent is a participant.

2. CSDocs Versioning Interoperability and Safety Considerations

DMA 1.0 versioning operations do not affect CSDocs structures. CSRelationship objects of the CSDocs Foundation always bind specific instances of DocVersions. The structure anchored on a specific CSRoot is not impacted by versioning of the CSRoot, any CSComponent, or even a CSRelationship (were that admissible). The creation of new DMA 1.0 versions is simply not noticed in the existing CSDocs Foundation structure having a given CSRoot. This is a straightforward, interoperable behavior.

If the checked-out CSRoot has renditions that cannot be represented without the existence of CSRelationships to components, the ExecuteChange operation to create the clone might fail.

The most-interoperable and safe case is to have SetCheckOutNext operation always produces a DMA 1.0 consistent form of the checked out object, whether or not there are any spontaneously-derived CSRelationships and CSComponents. If it is not possible or not safe to produce such an object from the given one, SetCheckOutNext operation should fail.

It may become desirable to extend the Versioning model by operations that go beyond SetCheckOutNext for the checkout of objects that may be CSRoot DocVersions. No such extension is proposed for the CSDocs Foundation.

7. Security

Not applicable

8. Naming

Not applicable

9. Locking and Transactions

The CSDocs Foundation does not impact the architecture of DMA Locking or the Transaction mechanisms of DMA.

1. Lock Usage Considerations for CSDocs Structures

For CSDocs, the locking and unlocking of a CSRoot or CSComponent might also require locking and unlocking of other portions of the structures in which the locked DocVersion participates. Any such implicit locking is accomplished silently by the implementation. No special provision is required on the part of requesters.

A CSDocs implementation might refuse to provide locks on CSDocs objects for locks that would otherwise be available.

2. Lock Implementation Considerations for CSDocs Structures

CSDoc implementations that preserve synchronization among the participants in a CSRelationship are not required to provide multiple locking. The DMA 1.0 requirement is that no lock be granted for which the necessary invariant cannot be delivered by the implementation.

3. Interoperability of Locking for CSDocs Structures

The greatest level of interoperability for use of CSDocs Structures is by

• providing all forms of locking that are available on DocVersions and Relationship objects generally
• supporting synchronization and ExecuteChange with DMA_MODIFY_PROTECTED wherever all forms of locking are not supported on non-read-only objects
• limiting the modification of synchronized participants in a CSRelationship to just one of them

1. typically the CSRoot for maximum backward interoperability with DMA 1.0 requesters
2. typically non-CSRoot CSComponents when the alteration is not one safely performed by DMA 1.0 clients

1. Compliance & Conformance Issues

[Address that the CSDocs Foundation extensions are completely optional, and that they have degrees of optionality among the extensions as well.

Capabilities for specific levels of conformance will be incorporated in a future draft of this CSDocs Foundation proposal.]

2. Sample Usage

[Samples illustrating application of the CSDocs Foundation will be incorporated in a future draft of this CSDocs Foundation proposal.]

 

3. What Requirement Does This Address?

[The CSDocs requirements matrix will be included with an indication of which requirements are satisfied by the CSDocs Foundation, and how. There will be verbal description of the key ideas as well.]

Edit this: Handling of compound documents is a DMA user requirement that was postponed in determining the scope of DMA 1.0. Increasing importance of document formats that allow multiple components and/or have internal structure makes it important to address this area in order to maintain the currency of DMA. SGML and XML are examples of such document formats.

1. Why is this a good solution?

Edit this after the beginning of Section 11 is expanded: The approach provides a relatively simple way of constructing documents from other documents, which seems the most critical element of compound / structured document functionality. It is simple in requiring only one new sub-class (of dmaClass_Relationship), no new interfaces, and a small number of new properties in existing classes.

Alternatives that were discarded include:

• A special kind of content element that is really a pointer to a complex object structure specialized for representing SGML documents. This was the basic idea in the original Hitachi CSDocs proposal. It was discarded because having an object in the content elements list that does not support the interfaces or properties of DMA 1.0 dmaClass_ContentElement subclasses was a violation of backwards compatibility.
• Modeling compound documents with containers, with or without adding a rendition property to the container class.

1. Extant Systems with Similar Features and Related Experiences

As part of our background research, we reviewed several repository products that have some form of compound document support. We characterized each product by considering the following areas. The approach to compound/structured documents in each of these systems, and the relationship to provisions of CSDocs, is collected in a separate document, CSDocsExisting.doc (click to open in Word or HTML). The current version of that document should be consulted for all details.

The systems currently surveyed are

• Documentum
• InterLeaf
• Lotus Domino.doc
• FileNET IDM

1. Impact on Existing Systems

[The impact on legacy systems of the basic requirements need to be assessed here, along with the conditions for being able to express legacy compound and structured documents features through the CSDocs Foundation.]

Edit this. We need to consider DMA 1.0 as a legacy impacted by these extensions.: This proposal will allow repositories that allow construction of documents from other documents to expose this capability through DMA.

 

2. Backwards Compatibility

[The requirement for upward compatibility – completely additive extensions, and for backward safety for legacy applications is addressed here. Hmm, has this always said Backwards compatibility?]

3. Performance Impact

[Assess that performance impact is at the same level as for containment and the considerations that were made in not having something more efficient than that.]

4. Failure Modes/Crash Recovery

[Assess the possible failures around DmaId exhaustion and duplication. Assess the impact of structure construction being incomplete or being broken as comparable to the same scenarios with containment and any structure defined using separate relationship objects.]

5. How Is This Incorporated into the Specification?

[Discuss presentation in a package with all approved CSDocs changes, in a standalone supplement that could eventually be a new section of the DMA Specification.]

6. How Is This Incorporated into the Code and Library Configurations?

[Propose an identified set of additions to the interface libraries and other code, a set that will be used for trial-use, and merger into the main DMA set in a way that does not interfere with software written to use the trial-use files that have not changed.]

The new property Id, class Id, and enumeration-value definitions will be incorporated in DMACSDOC.H for separate inclusion during the trial use period. This file will be structured so that, when CSDocs extensions are adopted as part of the DMA baseline reference interfaces, programs will compile properly whether they use a separate (current) DMACSDOC.H or not.

7. Reference Materials
1. Normative Specifications

[DCE RPC]

DCE 1.1: Remote Procedure Call.  Open Group Technical Standard.  Document Number C706.   The Open Group (Reading, UK: August, 1997).   737pp.  Electronic edition, $58.00.  HTML edition available on-line.  UUIDs are specified in an Appendix.  Registration is required to access the on-line material

[DMA1.0]

 

 

 

 

2. Informative References

[COMSpec]

Microsoft Corporation and Digital Equipment Corporation.  The Component Object Model Specification. Microsoft Corporation (Redmond, WA: 1992-1995).  Version 0.9, October 24, 1995.  This specification is available on the Microsoft Developer Network (MSDN) Library CD-ROM distribution, as late as April, 1999.  The specification can also be found at Microsoft's on-line pages.   There is an on-line (HTML) version and two downloadable versions as Microsoft Word 6.0 Master Documents with individual chapters.  A Word 6.0 version is required in order to have the footnotes and bibliography.  Chapter 3.2 Globally-Unique Identifiers, provides the description of GUID usage in COM

3. Background Materials

Original Hitachi Proposal

FileNet proposals

Cousins proposal

Documentum Server Reference Manual

Black Forest Group requirements document (April 1999?)

Original DMA Requirements Statement?

Original Statement of Work and Proposal for the Subcommittee

Requirements Documents adopted by the Subcommittee