Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Introduction
Parts, like all other persistent objects have a storageUnit in which they can store their content data and state persistently. However, Parts are intimately involved in actions like Binding, Translation, Data Interchange (Clipboard, Drag & Drop). As a result, Parts need to satisfy many more requirements than the other persistent objects, and so they need to be more disciplined about how they use their storageUnits.
Rules and Requirements
1. Parts need to be able to store multiple representations of their content, ordered by fidelity.
2. Each representation of a Part’s content must be a full representation, i.e. it cannot just be a delta of another representation.
3. It must be possible to extract exactly one representation from the part’s storageUnit, without understanding the format of any of the representations in the part.
4. It must be possible to remove all but one representation from the part’s storageUnit, without understanding the format of any of the representations in the part.
5. It must be possible to distinguish annotations/metainformation on/about the part, and content of the part.
6. Annotations/metainformation on/about a part may go away at any time, independent of the part editor, and therefore CANNOT be depended on to store critical content. However, they can be used to store non-critical optimizations such as caches.
7. Property names are ISO strings which constrain the naming conventions we can place on properties to that of ISO strings. The only naming conventions we can apply to ISO strings is that of prefix ownership, i.e. TC corporation may decide and control the format and meaning of all ISO strings beginning with “TC:”.
Details of the Part Storage Model
As a result of the above rules/requirements, Parts store their contents as follows:
Every part creates a Contents property, the constant for which (kODPropContents) is defined in StdProps.idl.
For every representation it wishes to store, the part creates a value, the valuetype of which is the Kind of the representation. Please refer to the Binding & Translation documents for more information about Kinds.
These values are ordered by fidelity, e.g. highest fidelity first, lowest fidelity last.
Into each of these values, the part streams out its contents using the appropriate data format.
One representation, one value.
No content should be stored outside of the Contents property.
All other properties on a part’s storageUnit are for metainformation/annotations and should not contain content.
Example
property OpenDoc:Property:Contents
value Apple:Kind:TestDrag
value Apple:Kind:StyledText
value Apple:Kind:PlainText
Q&A
Q: But how do you tell the difference between annotations and content?
A: There is often a misconception that there is a lot of overlap between annotations and content. In fact, it is difficult to come up with a precise definition which separates the two. However, more often than not, it is fairly easy to categorize any particular piece of information as annotation or content.
Here are some questions to ask yourself about a piece of info X which you are unsure of whether it is annotation or content.
Would users be upset if they thought they had saved X and it disappeared?
Do you want X to be persistent across machines?
Do you want X to be persistent across editors?
Do you want X to be persistent across platforms (for cross-platform formats)?
If you answered yes to any of the above, then X is content.
Q: But can’t we just distinguish metainformation from content by using a property naming convention, and store them both as sets of top level properties?
A: No. Storing content outside the Contents property would violate requirements 3 and 4 above. Also, placing a more restrictive naming convention on property names would violate requirement 7 above.
Q: But what if a part wants to store a particular representation using more than one property in a structured way?
A: Any part may store a particular representation in a structured fashion by requesting additional storageUnits from the draft and tying them together with references.
Q2: followup: Wouldn’t it be more efficient to keep the multiple properties in the part’s storage unit instead of requesting another storageUnit?
A2: It is hard to be more efficient when it does not even work! That approach would violate requirements 3 and 4. It is not a question of efficiency, it is a question of functionality.
Q: Usually when a Mac application stores a document, it stores some data in the data fork of the document’s file and then a bunch of other information as resources in the resource fork. Isn’t the Part Storage Model more restrictive than this?
A: No. The Part Storage Model is only as restrictive as you want it to be. If, like most applications, your part uses only a single stream to store its contents, then your storage model fits right into the Part Storage Model, you simply use a single value to store your contents. However, if you are using resources or some other form of structured storage, then you can ask your storageUnit’s draft object for additional storageUnits, and then store references to these storageUnits inside your primary content value. See the Persistent Reference document for more information about using Storage Unit References. It is important to note that because you can always ask for more storageUnits and then save references to them in any value, you can construct any kind of arbitrary graph structure for your storage representation. This is much more powerful than current day files and streams. Each additional storage unit can have multiple properties (you may think of these as multiple forks), and each property can have multiple values (again, different values within the same property should only be used for multiple representations of the same data).
Also, note that 1. most applications on the Macintosh use only the data fork. 2. On DOS, Windows, Unix and any other major OS out there, the files have a single fork, and therefore their applications use only a single flat stream for storing document content. Cross platform applications which want document portability also use only the data fork on the Macintosh. This single flat stream to store one representation is the model we are leveraging. This the 90% (if not more ) case of applications which are out there today.
