mcocomp to generate interface functions to retrieve,create and replace (update)
the contents of an object with the content of an XML string. In addition to the
common use of XML interfaces for porting data,these XML interface functions
can be used,for instance,in concert with the eXtremeDB event notifications,to
cause live data to be shared between eXtremeDB and other systems when an
object of interest changes in the database.
The XML interfaces can also be used to facilitate simple schema evolution by
exporting the database to XML,adding/dropping fields,indexes,and classes,and
importing the saved XML into the new database.
XML export and import
The XML export and import functions are used in conjunction with user-defined
file I/O helper functions to stream eXtremeDB database contents to and from
persistent media files:
MCO_RET mco_db_xml_export(mco_trans_h t,
void* stream_handle,
mco_stream_write output_stream_writer);
MCO_RET mco_db_xml_import(mco_trans_h t,
mco_stream_read input_stream_reader);
When mco_db_xml_export() is called the internal runtime implementation calls
the user-defined handler output_stream_writer to manage the output stream.
And likewise mco_db_xml_import() causes the handler input_stream_reader
to be called. Simple file I/O handlers look like the following:
mco_size_sig_t file_writer(void* stream_handle /* FILE* */,
const void* from,mco_size_t nbytes)
{
return (mco_size_t) fwrite(from,1,nbytes,(FILE*) stream_handle);
}
mco_size_sig_t file_reader(void* stream_handle /* FILE* */,
void* to,mco_size_t max_nbytes)
{
return (mco_size_t) fread(to,max_nbytes,(FILE*) stream_handle);
}
Chapter 13 : eXtremeDB XML Interfaces
264 eXtremeDB User’s Guide
Function mco_db_xml_export() may be called within a READ_ONLY transaction
but,as expected,mco_db_xml_import() must be called within a READ_WRITE
transaction. When importing data into an existing database,new data will be
added into the database and no existing data will be lost.
mco_db_xml_import()calls the internal function mco_w_xml_create_object()
to create a new object in the database for each object loaded from the XML
stream. Since the import procedure runs in the context of single transaction,there
are only two possible results: either the whole data set will be imported
successfully or no data will be imported. For example,if an object being imported
creates a duplicate for any unique index,the entire transaction will be rolled back.
It is necessary to explain how eXtremeDB handles unique identifiers,i.e. fields of
the types oid,autoid and autooid. As explained above,the import procedure
only creates new objects and never updates existing objects. So if a class contains
an oid field,the oid value from the XML stream is used in the newly created
object. Care must be taken to assure that imported oid values do not duplicate
values in existing database objects.
In the case of “automatic id” fields of type autoid and autooid,the import
procedure behaves according to the current XML policy settings. The policy
switches ignore_autoid and ignore_autooid,when set to value MCO_YES,
cause the procedure to ignore values for fields of this type in the XML stream and
mco_w_xml_create_object() will generate the id values for the newly created
objects just as if they were created by calling the classname_new() function.
The default setting of the XML policy is MCO_YES for both switches as the safest
setting to preserve database integrity
Policies:
typedef struct mco_xml_policy_t_
{
MCO_NUM_BASE int_base;
MCO_NUM_BASE quad_base;
MCO_TEXT_CODING text_coding;
MCO_TEXT_CODING blob_coding;
MCO_FLOAT_FORMAT float_format;
mco_bool indent;
mco_bool ignore_field; /* ignore field in xml that is not in
* class */
mco_bool encode_spec; /* encode chars with code < 32,except LF */
mco_bool encode_lf; /* encode line Feeds */
mco_bool encode_nat; /* encode national chars (code > 127) */
mco_bool truncate_sp; /* truncate trailing spaces in chars */
mco_bool use_xml_attrs; /* alternative XML representation,using */
/* attributes */
mco_bool ignore_autoid; /* ignore autoid value in create operations */
mco_bool ignore_autooid; /* ignore auto_oid in create operations */
}
mco_xml_policy_t;
The policy default values are set as follows: static mco_xml_policy_t default_xml_policy = { MCO_NUM_DEC,/* int_base is decimal */ MCO_NUM_HEX,/* quad_base is hexadecimal */ MCO_TEXT_ASCII,/* text_coding (strings) are ASCII */ MCO_TEXT_BASE64,/* blob_coding is Base64 */ MCO_FLOAT_EXPONENT,/* float_format is exponential */ MCO_YES,/* text is indented */ MCO_NO,/* all fields must be present in */ /* the incoming XML */ MCO_YES,/* encode special chars (< 32) */ MCO_YES,/* encode line Feeds */ MCO_NO,/* encode national chars (> 127) */ MCO_YES /* truncate trailing spaces */ MCO_NO,/* don't use attributes */ MCO_YES,/* ignore autoid values in input */ MCO_YES /* ignore autooid values in input */ };
