Return to README.rtf CVS log

Up to [NeXTSTEP 3.3 examples] / Examples / EnterpriseObjects / Archiving / ArchivingNSObject

Sample Programs from NeXSTEP 3.3

{\rtf0\ansi{\fonttbl\f2\fswiss Helvetica;\f1\fmodern Ohlfs;}
\paperw10800
\paperh11300
\margl120
\margr100
{\colortbl;\red0\green0\blue0;}
\pard\tx960\tx1920\tx2880\tx3840\tx4800\tx5760\tx6720\tx7680\tx8640\tx9600\f2\b\i0\ulnone\fs36\fc0\cf0 ArchivingNSObject
\b0\fs24 \
by Daniel Willhite, NeXT Engineering\
and Mai Nguyen, NeXT Developer Support \
\

\b\fs28 Overview
\b0\fs24 \
\
This example shows how to archive enterprise objects that descend from NSObject using the new archiving scheme. Please see also the example ArchivingObject  to archive objects that descend from Object for completeness.\
 \
Both examples use the Sybase pubs database as the underlying data model.\

\fc1\cf1 \

\b\fs28 Program Organization
\b0\fs24 \
\

\b How to build the eomodel file and NSAuthor.[hm]
\b0 \

\i Important note: 
\i0 The Enterprise Object class 
\i NSAuthor
\i0  should be specified in the EOModeler inspector window of the authors entity to ensure the proper archiving of the NSAuthor objects. All names in the authors entity should match with the names used in the actual NSAuthor code. \
You can automatically generate the template files NSAuthor.[hm] by selecting the menu items "Property"/ "Create Template" in EOModeler.\
 \

\b User Interface
\b0 \
To show how archiving/unarchiving works, you need to first archive the selected object, then unarchive it. The text scrollview will show the contents of the archived object. A temporary file named "NSObjectArchive" will be used during the archiving process.\
\

\b Major Classes in the Application
\b0 \
 \

\pard\tx1920\tx2880\tx3840\tx4800\tx5760\tx6720\tx7680\tx8640\tx9600\fi-1900\li1900\fc1\cf1 Owner	The heart of the functionality of the program.  It handles the archiving and unarchiving at the UI level.\

\pard\tx960\tx1920\tx2880\tx3840\tx4800\tx5760\tx6720\tx7680\tx8640\tx9600\fc1\cf1  \

\pard\tx1920\tx2880\tx3840\tx4800\tx5760\tx6720\tx7680\tx8640\tx9600\fi-1900\li1900\fc1\cf1 NSAuthor	An example of an enterprise object that descends from NSObject. \

\pard\tx560\tx1120\tx2060\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\fi-2060\li2060\fc1\cf1 \

\pard\tx960\tx1920\tx2880\tx3840\tx4800\tx5760\tx6720\tx7680\tx8640\tx9600\fc1\cf1 \

\b\fs28 Notes on Archiving\

\b0\fs24 \

\pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\b\fc0\cf0 Archiving Objects and NSObjects\

\b0 This program illustrates a technique for archiving graphs of objects that consist of\
descendents from both Object and NSObject. Archives that use this technique will be readable by future releases of NEXTSTEP. While this technique is very useful in certain situations it has certain restrictions that prevent it from being totally general.\
\

\b New Archiving Scheme\

\b0 Archiving in the NSObject world is similar to archiving in NEXTSTEP 3.2. NSObjects are archived using two classes from the Foundation library: NSCoder and NSArchiver. \
Every class that inherits from NSObject should implement the following two methods which are analogous to the methods read: and write: in NEXTSTEP 3.2. These methods are:\
\

\fs20 - (void)encodeWithCoder:(NSCoder *)aCoder;\

\fs24\fc1\cf1 \
which is corresponds to the write: method in NEXTSTEP 3.2 and\
\

\fs20\fc0\cf0 - initWithCoder:(NSCoder *)aDecoder;\

\fs24\fc1\cf1 \
Details of these two methods can be obtained from the NSObject.h file in /NextDeveloper/Headers/foundation.\
\
\

\b Compatibility Methods\

\b0 There are some cases when an object that inherits from Object will have an outlet that holds an object which descends from NSObject. In this case, the outlet can be archived along with the object by invoking the following functions from the Object's write: method.\
\

\fs20 extern void NXWriteNSObject(NXTypedStream *typedStream, NSObject *object);\

\fs24 \
which is analogous to the function NXWriteObject() and\
    \

\fs20 extern NSObject *NXReadNSObject(NXTypedStream *typedStream);\

\fs24 \
which is analogous to the fuction NXReadObject();\
\
In the inverse case an NSObject may need to archived which has an outlet that holds an object which descends from Object. In this case the outlet can be archived along the NSObject by invoking the following methods from on the NSCoder object:\
\

\fs20 - (void)encodeNXObject:(Object *)object;\

\fs24 \
and\
    \

\fs20 - (Object *)decodeNXObject;\

\fs24 \
\

\b Restrictions
\b0 \
There are severe restrictions on the normal archiving functionality when archiving objects from both the Object and NSObject world. These are:\
\

\fi-360\li720 1)  There is no sharing of information between the two worlds. Normally, if you archive a complex graph that has cycles are where several objects reference a single object, NEXTSTEP keeps enough information about the objects that cycles are detected and objects that are pointed at by many other objects are only archived once.  This is still true as long as the graph of objects being archived resides entirely in the Object world or in the NSObject world. However there is no sharing of objects information across worlds so care must be taken not to have cycles in a graph of objects that transcends both worlds.\

\fi0\li0 \

\fi-360\li720 2) Container objects cannot contain objects from the other world when being archived. NSArray, NSDictionary, NSValue, etc. May not be archived if they contain any descendents of Object. Inversely, List and the other containers from the Object world may not be archived if they contain any descendents of NSObject.\

\fi0\li0 \
\

\b Forward Compatibility\

\b0 Whenever possible, try not to mix objects from the different hierarchies in your object graphs.  Archiving a mixed-world graph of objects will be much slower, take up more space, and be less reliable (due to the lack of object sharing) than archiving graphs of objects that all inherit from the same root class.\
\
This is the only technique for archiving graphs of mixed objects that is guaranteed to compatible with later releases of NEXTSTEP. Pre-existing archives consisting of objects which inherit from from Object and new archives consisting entirely of objects that inherit from NSObject will also be forward compatible.\

\pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc1\cf1 		\

\b\fs28 Other References
\b0\fs24 \
\
See also the Foundation Reference.\

\b\fs28 \

\b0\fs24 Valid for Enterprise Objects Framework Release Version 1.0, 1.1,  with NEXTSTEP Developer Release 3.2 \
\
\

\b\fs28 Change History
\b0\fs24 \
\
August 94		Created example for EOF Version 1.0
}

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.