CLAM::XmlStorage Class Reference
[XML, Dumping and Restoring objects on XML, Customizing the XML format for your object]

Provides XML format storage for CLAM Component's. More...

#include <XMLStorage.hxx>

Public Member Functions
Atomic primitives to Dump and Restore
To be used only when you need to twickle the default behavior for summary operations (Dump, Restore. ..).
	XmlStorage ()
	~XmlStorage ()
void	Read (std::istream &is)
	Loads the DOM from the stream and selects the root node.
void	Create (const std::string &name)
	Creates a root node and selects it.
void	WriteSelection (std::ostream &os)
	Dumps the selected node on the stream.
void	WriteDocument (std::ostream &os)
	Dumps the full document on the stream.
void	DumpObject (const Component &component)
	Holds the component DOM to the selected node.
void	RestoreObject (Component &component)
	Restores the component from the selected node.
void	Select (const std::string &path)
	Moves the node selection to the specified path.
void	UseIndentation (bool useIndentation)
	Changes whether to output pretty formated XML or not.
Interface for Components to load/store their subitems
This is the interface to be used by the CLAM::Component::StoreOn and CLAM::Component::LoadFrom implementers.
void	Store (const Storable &storable)
	Components should use that function in their LoadFrom in order to store their subitems wrapped with XML*Adapters.
bool	Load (Storable &storable)
	Components should use that function in their LoadFrom in order to load their subitems wrapped with XML*Adapters.
Static Public Member Functions
Summary operations to Dump and Restore
Those operations are the simplest ones to use to dump and restore your objects in XML. XmlDump Module
static void	Dump (const Component &obj, const std::string &rootName, std::ostream &os, bool indentate=true)
	Dumps a Component as XML onto the named file with name as the root element.
static void	Restore (Component &obj, std::istream &is)
	Restore a Component from the given istream.
static void	RestoreFromFragment (Component &obj, const std::string &path, std::istream &is)
	Restore a Component from the xml fragment on the given xpath of the given document.
static void	AppendToDocument (const Component &obj, const std::string &xpath, const std::string &filename)
	Append the xml fragment corresponding to the given component on the given xpath of an existing file.
static void	Dump (const Component &obj, const std::string &rootName, const std::string &filename)
	Dump a Component from the named XML file.
static void	Restore (Component &obj, const std::string &filename)
	Restore a Component from the named XML file.

Detailed Description

Provides XML format storage for CLAM Component's.

Any class that derives from Component can be dumped and restored in XML (http://www.w3.org/XML) format. Components includes Arrays, DynamicType, ProcessingConfig, ProcessingData...

Warning:: XML storage is a very expensive task when dealing with big amounts of numeric data.

Dumping and restoring a component in XML

In its simplest usage, you can use the static functions Dump and Restore.

 MyComponent myComponent;

 // Here you can modify your Component

 CLAM::XmlStorage::Dump(myComponent, "Document", "MyComponent.xml")

Later you can restore the component:

 // An unmodified default constructed object!!!
 MyComponent comp;
 try
 {
        CLAM::XmlStorage::Restore(comp, "mycomponent.xml");
 }
 catch (CLAM::XmlStorageErr & err)
 {
        // Handle the error, a dirty way could be:
        std::cerr << err.what() << std::endl;
        exit(-1);
 }

Dump and Restore are overloaded to accept any C++ stream instead of a filename.

You can the AppendToDocument static function to add an object in a given path of an existing XML file, or using RestoreFromFragment to restore the object taking an XML fragment.

Step-By-Step Interface

The XMLStorage static methods used above provide shortcuts for the widely used funcionalities. The non-static methods that XMLStorage provides are the building blocks for implementing the static ones:

XmlStorage::Create: Creates an Empty DOM document.
XmlStorage::Read: Creates a DOM document from the XML that comps from an istream.
XmlStorage::WriteDocument: Writes on a stream the whole document
XmlStorage::Select: Changes the selected node (by default the root is selected)
XmlStorage::WriteSelection: Writes on a stream the selected target
XmlStorage::DumpObject: Dumps the CLAM object on the selected DOM node
XmlStorage::RestoreObject: Restores the CLAM object from the selected DOM node

You can convining them to achieve a diferent behaviour.

storing optimally the same object it onto two different streams,

   CLAM::XmlStorage storage;
   storage.Create("Document");
   storage.DumpObject(component);
   // Writting it to a file
   std::ofstream os("Document.xml");
   storage.WriteDocument(os);
   // Writting it to the standard output
   storage.WriteDocument(std::cout);

updating an existing xml by adding some objects to it,
extracting an object from a part of a document,
writing a document fragment
...

Static methods are not enough, but you still can instantiate an XMLStorage object and use the non-static methods with it. Non-static methods implements smaller steps than static methods do and you can combine them in order to obtain some concrete behaviour. For example, if you want to update an xml document by adding an object on XPath /Doc/element/subElement, you can use the sequence Read-Select-DumpObject-WriteDocument.

Author:: David Garcia.

Definition at line 44 of file XMLStorage.hxx.

Constructor & Destructor Documentation

CLAM::XmlStorage::XmlStorage ( )

Definition at line 94 of file XMLStorage.cxx.

CLAM::XmlStorage::~XmlStorage ( )

Definition at line 102 of file XMLStorage.cxx.

Member Function Documentation

void CLAM::XmlStorage::AppendToDocument	(	const Component &	obj,
		const std::string &	xpath,
		const std::string &	filename
	)			`[static]`

Append the xml fragment corresponding to the given component on the given xpath of an existing file.

Definition at line 123 of file XMLStorage.cxx.

References CLAM_WARNING, and Dump().

void CLAM::XmlStorage::Create ( const std::string & name )

Creates a root node and selects it.

Definition at line 50 of file XMLStorage.cxx.

Referenced by Dump().

void CLAM::XmlStorage::Dump	(	const Component &	obj,
		const std::string &	rootName,
		const std::string &	filename
	)			`[static]`

Dump a Component from the named XML file.

Definition at line 116 of file XMLStorage.cxx.

static void CLAM::XmlStorage::Dump	(	const Component &	obj,
		const std::string &	rootName,
		std::ostream &	os,
		bool	indentate = `true`
	)			`[inline, static]`

Dumps a Component as XML onto the named file with name as the root element.

Definition at line 103 of file XMLStorage.hxx.

References Create(), DumpObject(), UseIndentation(), and WriteDocument().

Referenced by AppendToDocument().

void CLAM::XmlStorage::DumpObject ( const Component & component )

Holds the component DOM to the selected node.

Definition at line 66 of file XMLStorage.cxx.

References CLAM::NullDomDocumentHandler::writeDocument().

Referenced by Dump().

bool CLAM::XmlStorage::Load ( Storable & storable ) [virtual]

Components should use that function in their LoadFrom in order to load their subitems wrapped with XML*Adapters.

Implements CLAM::Storage.

Definition at line 168 of file XMLStorage.cxx.

void CLAM::XmlStorage::Read ( std::istream & is )

Loads the DOM from the stream and selects the root node.

Definition at line 45 of file XMLStorage.cxx.

Referenced by Restore(), and RestoreFromFragment().

void CLAM::XmlStorage::Restore	(	Component &	obj,
		const std::string &	filename
	)			`[static]`

Restore a Component from the named XML file.

Definition at line 107 of file XMLStorage.cxx.

static void CLAM::XmlStorage::Restore	(	Component &	obj,
		std::istream &	is
	)			`[inline, static]`

Restore a Component from the given istream.

Definition at line 115 of file XMLStorage.hxx.

References Read(), and RestoreObject().

static void CLAM::XmlStorage::RestoreFromFragment	(	Component &	obj,
		const std::string &	path,
		std::istream &	is
	)			`[inline, static]`

Restore a Component from the xml fragment on the given xpath of the given document.

Definition at line 125 of file XMLStorage.hxx.

References Read(), RestoreObject(), and Select().

void CLAM::XmlStorage::RestoreObject ( Component & component )

Restores the component from the selected node.

Definition at line 73 of file XMLStorage.cxx.

References CLAM::NullDomDocumentHandler::SetWritingContext(), and CLAM::Component::StoreOn().

Referenced by Restore(), and RestoreFromFragment().

void CLAM::XmlStorage::Select ( const std::string & path )

Moves the node selection to the specified path.

Exceptions:

XmlStorageErr

whenever a step is not found The path is a subset of XPath. Absolute and relative paths can be used but node names are the only step specifier to be used.

 /Root/Element/SubElement
 Element/SubElement     // Relative being in /Root, the default)
 /                      // Equivalent to /Root but useful when 
                        // you don't know the root node name.

Sets the selection at the specified path (the default selection is the root node)

Definition at line 84 of file XMLStorage.cxx.

Referenced by RestoreFromFragment().

void CLAM::XmlStorage::Store ( const Storable & storable ) [virtual]

Components should use that function in their LoadFrom in order to store their subitems wrapped with XML*Adapters.

Implements CLAM::Storage.

Definition at line 141 of file XMLStorage.cxx.

void CLAM::XmlStorage::UseIndentation ( bool useIndentation )

Changes whether to output pretty formated XML or not.

By default, indentation and new lines are not inserted resulting in compact XML but dificult for humans to read. Use this method, to enable the indentation.