CLAM::XmlStorage Class Reference
[XMLDumping and Restoring objects on XMLCustomizing the XML format for your object]

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

#include <XMLStorage.hxx>

List of all members.

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:

You can convining them to achieve a diferent behaviour.

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.

Todo:
Not implemented yet

Definition at line 89 of file XMLStorage.cxx.

References CLAM::NullDomDocumentHandler::selectPath().

Referenced by Dump().

void CLAM::XmlStorage::WriteDocument ( std::ostream &  os  ) 

Dumps the full document on the stream.

Definition at line 61 of file XMLStorage.cxx.

References CLAM::NullDomDocumentHandler::writeSelection().

Referenced by Dump().

void CLAM::XmlStorage::WriteSelection ( std::ostream &  os  ) 

Dumps the selected node on the stream.

Definition at line 56 of file XMLStorage.cxx.

References CLAM::NullDomDocumentHandler::create().


The documentation for this class was generated from the following files:
Generated by  doxygen 1.6.3