1/*
2 * Copyright (c) 1999-2000, Eric Moon.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 *    notice, this list of conditions, and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 *    notice, this list of conditions, and the following disclaimer in the
14 *    documentation and/or other materials provided with the distribution.
15 *
16 * 3. The name of the author may not be used to endorse or promote products
17 *    derived from this software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
23 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
26 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
27 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30
31
32// IPersistant.h
33// * PURPOSE
34//   Interface to be implemented by objects that want to
35//   be persistent (loadable/savable) via XML.
36//
37// * TO DO +++++ IN PROGRESS 8jul99
38//   - Make the export API friendlier: classes shouldn't have to
39//     know how to format XML, and it should be easy to extend
40//     the serialization capabilities in a subclass. [8jul99]
41//     * should this stuff be exposed via ExportContext methods?
42//
43//   - FBC stuffing? [29jun99]
44//
45// * HISTORY
46//   e.moon		29jun99		Reworking; merging with the interface
47//                      formerly known as Condenser.
48//   e.moon		28jun99		Begun
49
50#ifndef __IPersistent_H__
51#define __IPersistent_H__
52
53#include "ImportContext.h"
54#include "ExportContext.h"
55
56#include <iostream>
57
58#include "cortex_defs.h"
59__BEGIN_CORTEX_NAMESPACE
60
61class IPersistent {
62
63public:
64	// empty virtual dtor
65	virtual ~IPersistent() {}
66
67public: 					// *** REQUIRED INTERFACE
68
69// 8jul99 export rework
70//	// EXPORT:
71//	// write an XML representation of this object (including
72//	// any child objects) to the given stream.  use the
73//	// provided context object to format the output nicely.
74//
75//	virtual void xmlExport(
76//		ostream& 					stream,
77//		ExportContext&		context) const =0;
78
79	// EXPORT:
80	// implement this method to write a start tag via
81	// context.startElement().  You can also write comments or
82	// processing instructions directly to the stream.
83
84	virtual void xmlExportBegin(
85		ExportContext& context) const=0;
86
87	// EXPORT:
88	// implement this method to write all the attributes needed
89	// to represent your object, via context.writeAttribute().
90	// (If subclassing an IPersistent implementation, don't forget
91	// to call up to its version of this method.)
92
93	virtual void xmlExportAttributes(
94		ExportContext& context) const=0;
95
96	// EXPORT: optional
97	// implement this method to write any child objects, using
98	// context.writeObject().  You can also write text content
99	// directly to the stream.
100	// (If subclassing an IPersistent implementation, don't forget
101	// to call up to its version of this method.)
102
103	virtual void xmlExportContent(
104		ExportContext& context) const { TOUCH(context); }
105
106	// EXPORT:
107	// implement this method to write an end tag via
108	// context.endElement().
109
110	virtual void xmlExportEnd(
111		ExportContext& context) const=0;
112
113	// IMPORT:
114	// called when the start tag of the element corresponding to
115	// this object is encountered, immediately after this object
116	// is constructed.  no action is required.
117	//
118	// context.element() will return the element name that produced
119	// this object.
120
121	virtual void xmlImportBegin(
122		ImportContext&		context) =0;
123
124	// IMPORT:
125	// called for each attribute/value pair found in
126	// the element corresponding to this object.
127
128	virtual void xmlImportAttribute(
129		const char*					key,
130		const char*					value,
131		ImportContext&		context) =0;
132
133	// IMPORT:
134	// called when character data is encountered for the
135	// element corresponding to this object.  data is not
136	// 0-terminated; this method may be called several times
137	// (if, for example, the character data is broken up
138	//  by child elements.)
139
140	virtual void xmlImportContent(
141		const char*					data,
142		uint32						length,
143		ImportContext&		context) =0;
144
145	// IMPORT:
146	// called when an object has been successfully
147	// constructed 'beneath' this one.
148	//
149	// context.element() will return the element name corresponding
150	// to the child object.
151
152	virtual void xmlImportChild(
153		IPersistent*			child,
154		ImportContext&		context) =0;
155
156	// IMPORT:
157	// called when close tag is encountered for the element
158	// corresponding to this object.  a good place to do
159	// validation.
160	//
161	// context.element() will return the element name that produced
162	// this object.
163
164	virtual void xmlImportComplete(
165		ImportContext&		context) =0;
166
167public: 					// *** OPTIONAL CHILD-IMPORT INTERFACE
168								//     These methods allow an IPersistent object
169								//     to directly import nested elements: handy for
170								//     condensing more complicated document structures
171								//     into a single object (see MediaFormatIO for an
172								//     example.)
173
174	virtual void xmlImportChildBegin(
175		const char*					name,
176		ImportContext&		context) {
177		TOUCH(name);
178		context.reportWarning("Nested element not supported.");
179	}
180
181	virtual void xmlImportChildAttribute(
182		const char*					key,
183		const char*					value,
184		ImportContext&		context) {TOUCH(key); TOUCH(value); TOUCH(context);}
185
186	virtual void xmlImportChildContent(
187		const char*					data,
188		uint32						length,
189		ImportContext&		context) {TOUCH(data); TOUCH(length); TOUCH(context);}
190
191	virtual void xmlImportChildComplete(
192		const char*					name,
193		ImportContext&		context) {TOUCH(name); TOUCH(context);}
194};
195
196__END_CORTEX_NAMESPACE
197
198#endif /*__IPersistent_H__*/
199