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// XML.h
33// * PURPOSE
34//   A central access point for Cortex's XML import/export
35//   services.  A completely static class.
36//
37// * RESPONSIBILITIES
38//   - Maintain a set of XML::DocumentType objects, each
39//     containing the information needed to import a particular
40//     kind of XML document into native objects.
41//
42//   - Provide a simple API for importing and exporting
43//     IPersistent objects from/to streams.
44//
45// * HISTORY
46//   e.moon		4oct99		API changes:
47//											- BDataIO used in place of standard streams.
48//											- Factory folded into XML::DocumentType
49//
50//   e.moon		29jun99		Begun
51
52#ifndef __XML_H__
53#define __XML_H__
54
55#include "IPersistent.h"
56#include "XMLElementMapping.h"
57
58#include <map>
59#include <set>
60
61#include <DataIO.h>
62#include <Locker.h>
63#include <Mime.h>
64#include <String.h>
65
66#include "cortex_defs.h"
67__BEGIN_CORTEX_NAMESPACE
68
69class Importer;
70
71// -------------------------------------------------------- //
72// class XML
73// -------------------------------------------------------- //
74
75class XML {
76	// internal import helper
77	friend class Importer;
78
79public:													// *** types
80	class DocumentType;
81
82public:													// *** document type operations
83
84	// takes responsibility for the given type object
85	static void AddDocumentType(
86		XML::DocumentType*					type);
87
88public:													// *** import/export operations
89
90	// identify object in stream.
91	// returns:
92	// - B_OK on success, or
93	// - B_BAD_TYPE if no document type matches the root
94	//   element of the stream, or
95	// - B_IO_ERROR if the document is malformed, or if a
96	//   read error occurs.
97
98	static status_t Identify(
99		BDataIO*										stream,
100		DocumentType**							outType,
101		std::list<BString>*						outErrors);
102
103	// create & populate the root object from the given
104	// XML stream.
105	// returns:
106	// - B_OK on success, or
107	// - B_IO_ERROR if the document is malformed, or if a
108	//   read error occurs, or
109	// - B_ERROR
110
111	static status_t Read(
112		BDataIO*										stream,
113		IPersistent**								outObject,
114		std::list<BString>*						outErrors);
115
116	static status_t Read(
117		BDataIO*										stream,
118		IPersistent**								outObject,
119		ImportContext*							context); //nyi
120
121	// [e.moon 26nov99]
122	// populate the provided root object from the given
123	// XML stream.  you need to provide a document type
124	// that corresponds to the given object.
125	// returns:
126	// - B_OK on success, or
127	// - B_IO_ERROR if the document is malformed, or if a
128	//   read error occurs, or
129	// - B_ERROR
130
131	static status_t Read(
132		BDataIO*										stream,
133		IPersistent*								rootObject,
134		XML::DocumentType*					documentType,
135		std::list<BString>*						outErrors);
136
137	static status_t Read(
138		BDataIO*										stream,
139		IPersistent*								rootObject,
140		XML::DocumentType*					documentType,
141		ImportContext*							context);
142
143	// create an ExportContext and use it to write the given object
144	// to the given stream
145
146	static status_t Write(
147		BDataIO*										stream,
148		IPersistent*								object,
149		BString*										outError);
150
151private:												// static members
152
153	typedef std::map<BString, DocumentType*> doc_type_map;
154
155	static doc_type_map						s_docTypeMap;
156	static BLocker								s_docTypeLock;
157
158private:												// implementation
159	static status_t _DoRead(
160		BDataIO*										stream,
161		Importer&										i,
162		std::list<BString>*						outErrors); //nyi
163};
164
165// -------------------------------------------------------- //
166// class XML::DocumentType
167// -------------------------------------------------------- //
168
169class XML::DocumentType {
170public:													// *** constant members
171	const BString									rootElement;
172	const BMimeType								mimeType;
173
174	static const BMimeType				s_defaultMimeType;
175
176public:													// *** ctor/dtors
177	virtual ~DocumentType();
178
179	DocumentType(
180		const char*									_rootElement,
181		const char*									_mimeType=0);
182
183public:													// *** 'factory' interface
184
185	// The DocumentType takes ownership of the given mapping
186	// object.  If a mapping for the element already exists,
187	// the provided object is deleted and the method returns
188	// B_NAME_IN_USE.
189	virtual status_t addMapping(
190		XMLElementMapping*					mapping);
191
192	// returns 0 if no mapping found for the given element
193	virtual IPersistent* objectFor(
194		const char*									element);
195
196private:												// implementation
197
198	typedef std::set<XMLElementMapping*, _mapping_ptr_less> mapping_set;
199	mapping_set										m_mappingSet;
200};
201
202__END_CORTEX_NAMESPACE
203
204#endif /*__XML_H__*/
205