storage Namespace Reference

Namespace containing all functions and classes related to VVE persistence. More...

Classes

struct  ConvertType
 Convert object of type from to object of type to. More...
struct  Frame
 Data holding properties of a frame. More...
struct  TypeTraits
 Defines main traits for types directly handled. More...
class  VVEStorage
 Abstract base class defining the interactions with the persistence module. More...
class  VVEStorage_BINReader
 Implementation reading an BIN file. More...
class  VVEStorage_BINWriter
 Implementation writing an BIN file. More...
class  VVEStorage_XMLReader
 Implementation reading an XML file. More...
class  VVEStorage_XMLWriter
 Implementation writing an XML file. More...

Enumerations

enum  BIN_TYPES {
  BT_BOOL = 0, BT_WCHART, BT_CHAR, BT_SIGNED_CHAR,
  BT_UNSIGNED_CHAR, BT_SHORT, BT_UNSIGNED_SHORT, BT_INT,
  BT_UNSIGNED_INT, BT_LONG, BT_UNSIGNED_LONG, BT_LONG_LONG,
  BT_UNSIGNED_LONG_LONG, BT_FLOAT, BT_DOUBLE, BT_LONG_DOUBLE,
  BT_STRING, BT_START_REFERENCE, BT_START_COMPOUND
}
enum  NUMBER_CLASS {
  SIGNED_INTEGER, UNSIGNED_INTEGER, FLOATING_POINT, CHAR,
  NOT_A_NUMBER
}
enum  Options { TypeChecking }
 

Common options for reader/writer.

More...
enum  STORAGE_ERROR {
  NO__ERROR = 0, IO_ERROR, BAD_CONTENT, TYPE_CHECK_ERROR,
  TYPE_CONVERSION_ERROR, NO_FIELD_ERROR, REFERENCE_ERROR, USER_ERROR,
  UNKNOWN_ERROR
}
 

Enumeration describing the basic errors.

More...
enum  TypeCheckingOption {
  TCO_Exact, TCO_Strict, TCO_Permissive, TCO_PermissiveNoWarning,
  TCO_NoCheck
}
 

Enumeration describing how the type of the elements should be handled.

More...
enum  TYPES {
  T_INVALID = -1, T_BOOL = 0, T_WCHART, T_CHAR,
  T_SIGNED_CHAR, T_UNSIGNED_CHAR, T_SHORT, T_UNSIGNED_SHORT,
  T_INT, T_UNSIGNED_INT, T_LONG, T_UNSIGNED_LONG,
  T_LONG_LONG, T_UNSIGNED_LONG_LONG, T_FLOAT, T_DOUBLE,
  T_LONG_DOUBLE, T_STRING
}

Functions

template<typename From , typename To >
bool convert_type (const From &from, To &to)
 Function converting from to to.
template<typename Ptr >
Ptr create_object (Ptr const &p)
TYPES find_type (NUMBER_CLASS klass, size_t bytes)
 FOR_ALL_TYPES_NOSTRING (CONVERT_FROM_STDSTRING)
 FOR_ALL_TYPES_NOSTRING (CONVERT_TO_STDSTRING)
bool isStrictConversion (TYPES from, TYPES to)
template<typename Ptr >
ReferencePtr make_reference (Ptr &p)
TYPES read_type (QFile *file)
template<typename T >
bool serialization (VVEStorage &storage, T &value)
 Function implementing the serialization.
template<typename T >
TYPES type_id (const T &=T())
template<typename T >
const QStringtype_name (const T &=T())
const QStringtypeid_to_name (TYPES id)
TYPES typename_to_id (const QString &name)
int versionNumber (const QString &file_version)
 Helper function to parse version number.

Detailed Description

Namespace containing all functions and classes related to VVE persistence.

Principle

The storage works using the storage::VVEStorage objects. This abstract class defines the generic behavior of a serialized storage for VVE. The implementations are created by the interpreter and given to the model. The storage implement an interface that is the same for reading and writing.

Defining the serialization

To allow for serialization the model should implement at least one method:

 bool serialize(storage::VVEStorage& store);

This method actually implements the serialization of the model. It should returns true if the serialization worked, false otherwise. To test for the existence of this method, the interpreter will call it using a dummy storage object, simulating a storage writer always succeeding. If the result of this dummy call is true, then the object is recognised as being able to serialize data.

For every object, other than the model itself, you want to serialize, you can define its serialization in two ways:

  1. via a method in the object:
     bool serialize(storage::VVEStorage& store);
    
  2. via an external function:
     bool serialization(storage::VVEStorage& store, MyClass& object);
    

The first way is more intrusive but has the advantage to be inherited. The second way is non-intrusive but won't be inherited by sub-classes. In case the serialization method does not exist, the serialize method will be looked for.

File versionning

Optionnally, the model can define a version string. To do so, the class should define the method:

 QString version() const;

The method will be called when saving a file.

Once the version is obtained (either from a file or by calling the version method), the storage object will call the method:

 int versionNumber(const QString& version);

the version given is the model or file version prepended with the file format and a hyphen. For example, if the version of a model is 1.2.3 and the current file is an XML one, the version will be: XML-1.2.3

The number returned by the versionNumber() method is stored by the storage object and can be retrieved using the VVEStorage::version() method. As a helper, you can use the function storage::versionNumber(const QString&).

Using the VVEStorage object

The VVEStorage object allows you to define your data structure as a hierarchical set of named fields. As the system is a serialization one, fields should always be read and written in the same order. The storage object is not a random access object but a serial one.

To help you structure your data, you can create three kind of elements:

  1. Fields This is the basic type. If you want to store an element by value, you use a field. All the basic C++ types and strings are handled directly by the storage object. Any other type must have either a serialization function associated or a serialize method. If a field contains an object, a compound will actually be created. A field is created by the method:
      template <typename T>
      bool VVEStorage::field(const QString& name, T& value);
    
    The name must not be more than 255 characters but can be empty. An empty field is valid only as sole member of a compound. In this case, the storage object can decide to simply create a field reusing the name of the compound (this is actually done both for the XML and BIN implementation). A typical exemple would be for a class with only one member:
      struct MyStructure
      {
        int value;
        bool serialize(storage::VVEStorage& store) {
          return store.field("", value);
        }
      };
    
  2. References References are similar to fields but are used for pointers. The element stored should be an actual pointer or a smart pointer. A reference is created with the method:
      template <typename Ptr>
      bool VVEStorage::reference(const QString& name, const QString& ref_type, Ptr& p);
    
    The point is using a reference is that:
    1. if the same object is saved twice, it will be only once in the file
    2. if two pointers share the same object when writing, they will be reconstructed as pointing to the same object.
    A typical example in VVE is the vertices. If you store a vertex, the serialization function defined in <storage/graph.h> is defined as:
      bool serialization(storage::VVEStorage& store, vertex& v) {
        return store.reference("", "Vertex", v);
      }
    
    The empty name tells the storage object that it can reuse the compound name (and actually not have a compound but just a reference). Then, the type is usefull mostly for user-editable files where the reference ids are unique per type. Then, if you use the same vertex twice, only one instance will be stored and recreated later. And the two vertices will still share the same data. Once a reference is identified, a namesless field is created to hold the content of the reference.
  3. Compounds Compounds are created using the two methods: This will group all element defined in between the two. A compound should always be closed. As for references and fields, a compound can be nameless and can then be optimized. In the end, a compound is rarely useful unless you have a very complicated structure. It is used for example in the VVGraph serialization. And of course, a compound is implicitely created for every composed object.

Enumeration Type Documentation

Common options for reader/writer.

Enumerator:
TypeChecking 

Change the way type is checked while extracting a structure.

Definition at line 185 of file storage.h.

00186   {
00188     TypeChecking
00189   };

Enumeration describing the basic errors.

Enumerator:
NO__ERROR 

No error occured.

The wierd name is due to the definition of NO_ERROR and NOERROR by windows already. Any complain should be sent to Microsoft.

IO_ERROR 

Error occuring during an IO access.

Typically while reading or writing a file.

BAD_CONTENT 

Bad content error.

This mean the format of the file is not correct. For example, an XML file does not respect the XML format.

TYPE_CHECK_ERROR 

Type error.

It can occur either if the typing is strict and the type is different in the file and in the model or if the typing is permissive but the conversion does not exist.

TYPE_CONVERSION_ERROR 

Type conversion error.

It can occur if the type conversion should be possible but the content is invalid. The typical case is the conversion from string to number if the string doesn't contain a number.

NO_FIELD_ERROR 

The field requested doesn't exist.

REFERENCE_ERROR 

Error while using a reference.

Either the reference does not exist or the user try to access a non-reference as reference.

USER_ERROR 

Error of the user.

The succession of commands of the user are invalid.

UNKNOWN_ERROR 

Error set if the serialize method fails without an error being set.

Definition at line 226 of file storage.h.

00227   {
00233     NO__ERROR = 0,
00239     IO_ERROR,
00246     BAD_CONTENT,
00254     TYPE_CHECK_ERROR,
00262     TYPE_CONVERSION_ERROR,
00266     NO_FIELD_ERROR,
00273     REFERENCE_ERROR,
00279     USER_ERROR,
00283     UNKNOWN_ERROR
00284   };

Enumeration describing how the type of the elements should be handled.

Enumerator:
TCO_Exact 

The type asked for must be the same as the one read.

TCO_Strict 

The conversion should be loss-less.

For example, you'll be able to convert from short to int but not the other way around

TCO_Permissive 

The conversion can induce loss.

However, any loss of precision conversion will lead to a warning in the starndard output.

TCO_PermissiveNoWarning 

Same as Permissive, but without the warnings.

TCO_NoCheck 

No check is performed.

An error will be raised only if the string cannot be interpreted as the type claimed.

Definition at line 194 of file storage.h.

00195   {
00197     TCO_Exact,
00204     TCO_Strict,
00211     TCO_Permissive,
00215     TCO_PermissiveNoWarning,
00220     TCO_NoCheck
00221   };


Function Documentation

template<typename From , typename To >
bool storage::convert_type ( const From &  from,
To &  to 
) [inline]

Function converting from to to.

This allows custom (compile-time) conversion.

Definition at line 202 of file types.h.

00203   {
00204     static const ConvertType<From,To> converter = ConvertType<From,To>();
00205     return converter(from, to);
00206   }

TYPES storage::find_type ( NUMBER_CLASS  klass,
size_t  bytes 
)
Returns:
a type corresponding to the number class and size.

If no such type exist, return T_INVALID

Referenced by storage::VVEStorage_BINReader::serialize(), and storage::old::VVEStorage_BINReader::serialize().

bool storage::isStrictConversion ( TYPES  from,
TYPES  to 
)
Returns:
True if you can convert from from to to without loosing any information
template<typename T >
bool storage::serialization ( VVEStorage &  storage,
T &  value 
) [inline]

Function implementing the serialization.

The default implementation expects a serialize method in the type:

   bool T::serialize(VVEStorage&)

Definition at line 703 of file storage.h.

Referenced by storage::VVEStorage::field().

00704   {
00705     return value.serialize(storage);
00706   }

const QString & storage::typeid_to_name ( TYPES  id  ) 
Returns:
the name associated to the type id
TYPES storage::typename_to_id ( const QString name  ) 
Returns:
the type id associated to the name
int storage::versionNumber ( const QString file_version  ) 

Helper function to parse version number.

Returns:
the version number of 0 if no number found.

This function will find any version on the form MAJOR[.MINOR[.MICRO]] and will return a unique integer on 32 bits supposing MAJOR and MINOR are less than 256 and micro is less than 65536. If the version numbers are too big, only the least significant bits are kept.

Any string other than the version number will be ignored.

Examples of valid versions:

File Version    Version     Number
VVE 1.2.20      1.2.20      0x01020014
XML 1.3         1.3         0x01030000
MyModel1.3.2a   1.3.2       0x01030002
OBJ 12.32.254   26.32.254   0x1a2000fe
FILE 12         12          0x0c000000
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Generated on Fri May 31 15:38:13 2013 for VVE by  doxygen 1.6.3