Modification log
--------------------------------------------------------------------------------
Version Date Author Notes
-------- -------- -------------- ----------------------------------------------
0.02 10/2000 Andrei Nossov Documentation improved
0.01 08/2000 Andrei Nossov First cut
--------------------------------------------------------------------------------
NAME
DBIx::XMLMessage - XML Message exchange between DBI data sources
SYNOPSIS
OUTBOUND MESSAGE
use DBI;
use DBIx::XMLMessage;
# Template string
my $tpl_str =<< "_EOT_";
<?xml version="1.0" encoding="UTF-8" ?>
<TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'>
<KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' />
<COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' />
<COLUMN NAME='PasswordDate' EXPR='pwdate' DATATYPE='DATETIME'
BLTIN="fix_gmdatetime" />
<CHILD NAME='SysUsers' TABLE='sysusers'>
<KEY NAME='suid' PARENT_NAME='LoginId' DATATYPE='NUMERIC' />
<COLUMN NAME='UserId' EXPR='uid' DATATYPE='NUMERIC' />
<COLUMN NAME='UserName' EXPR='name' />
</CHILD>
</TEMPLATE>
_EOT_
my $msg = new DBIx::XMLMessage ('TemplateString' => $tpl_str);
my $ghash = { 'OBJECT_ID' => [ 1, 2 ] };
my $dbh = DBI->connect('dbi:Sybase:server=x;database=master','sa','secret');
$msg->rexec ($dbh, $ghash);
print "\n\n", $msg->output_xml(0,0);
print "\n\n", $msg->output_xml(0,1);
INBOUND MESSAGE
#!/usr/bin/perl
use DBI;
use DBIx::XMLMessage;
my $template_xml =<< "_EOD1_";
<?xml version="1.0" encoding="UTF-8" ?>
<TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'
ACTION='SAVE'>
<KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' />
<COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' />
<COLUMN NAME='PasswordDate' EXPR='pwdate' DATATYPE='DATETIME'
BLTIN="fix_gmdatetime" />
<CHILD NAME='SysUsers' TABLE='sysusers'>
<KEY NAME='suid' PARENT_NAME='LoginId' DATATYPE='NUMERIC' />
<COLUMN NAME='UserId' EXPR='uid' DATATYPE='NUMERIC' />
<COLUMN NAME='UserName' EXPR='name' />
</CHILD>
</TEMPLATE>
_EOD1_
my $message_xml =<< "_EOD2_";
<?xml version="1.0" encoding="UTF-8"?>
<SysLogins>
<LoginId>1</LoginId>
<PasswordDate>1999/08/17 08:31</PasswordDate>
<SysUsers>
<UserId>1</UserId>
<UserName>sa</UserName>
</SysUsers>
</SysLogins>
_EOD2_
my $xmlmsg = new DBIx::XMLMessage ('TemplateString' => $template_xml);
my $msgtype = $xmlmsg->input_xml($message_xml);
my $ghash = {
'OBJECT_ID' => [ 1 ]
};
$xmlmsg->populate_objects ($ghash);
my $dbh = DBI->connect('dbi:Sybase:server=x;database=master','sa','secret');
$xmlmsg->rexec ($dbh, $ghash);
print $xmlmsg->output_message();
DESCRIPTION
The package maintains simple XML templates that describe object structure.
The package is capable of generating SQL statements based on these templates
and executing them against DBI data sources. After executing the SQL, the
package formats the data results into XML strings. E.g. the following simple
template
<TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'
ACTION='SAVE'>
<KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' />
<COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' />
</TEMPLATE>
being executed with key value = 1, will be tranlated into this SQL:
SELECT suid LoginId FROM syslogins where suid = 1
and the result will be formatted into this XML string:
<SysLogins>
<LoginId>1<LoginId>
</SysLogins>
Inbound messages can be processed according to the same kind of templates
and the database is updated accordingly. Templates are capable of defining
the SQL operators, plus new SAVE operation which is basically a combination
of SELECT and either INSERT or UPDATE depending on whether the record was
found by the compound key value or not.
SALES PITCH
This package allows for objects exchange between different databases. They
could be from different vendors, as long as they both have DBD drivers. In
certain cases it is even possible to exchange objects between databases with
different data models. Publishing of databases on the web could
potentially be one of the applications as well.
TEMPLATE TAGS
TEMPLATE
This is manadatory top-level tag. It can correspond to a certain table and
be processed just like table-level REFERENCE and CHILD attributes described
below. Some of TEMPLATE attributes are related to the whole template (e.g.
TYPE or VERSION) while others desribe the table ti's based on (e.g. TABLE)
If the TABLE attribute is defined, the generated SQL is going to run against
some table. Otherwise a SQL with no table will be generated. This only makes
sense for outbound messages and only possible on certain engines, like
Sybase. Also, the immediate child columns should contain constants only for
apparent reasons.
REFERENCE
REFERENCE is a table-level tag. It's meant to represent a single record from
another table that's retrieved by unique key. E.g. if my current table is
EMPL then DEPARTMENT would be a REFERENCE since employee can have no more
than one departament.
CHILD
This tag meant to represent a number of child records usually retrieved by
a foreign key value (probably primary key of the current table). Right now
there's no difference in processing between CHILD and REFERENCE, but it may
appear in the future releases.
COLUMN
This tag is pretty self-explanatory. Each COLUMN tag will appear on the
SELECT, INSERT or UPDATE list of the generated SQL.
KEY
Key represents linkage of this table's records to the parent table. All
KEY's will appear on the WHERE clause as AND components. This way of linkage
is typical for most of relational systems and considered to be a good style.
I guess it shouldn't be much of a restriction anyway. If it gets that, you
could try tweak up the WHERE_CLAUSE attribute..
PARAMETER
This tag represents a parameter that will be passsed to a stored procedure.
Currently, only Sybase-style stored procedures are supported. Fixes are
welcome..
METHODS
new
my $xmsg = new DBIx::XMLMessage (
[ _OnError => $err_coderef, ]
[ _OnTrace => $trace_coderef, ]
[ _OnDebug => $debug_coderef, ]
[ Handlers => $expat_handlers_hashref, ]
[ TemplateString => $xml_template_as_a_string, ]
[ TemplateFile => $xml_template_file_name, ]
)
You can specify either TemplateString or TemplateFile, but not both. If any
of those specified, the template will be parsed.
set_handlers
$xmsg->set_handlers ($expat_handlers_hashref)
Set additional expat handlers, see XML::Parser::Expat. Normally you won't
use this. The only case I could think of is processing of encoding..
prepare_template
$xmsg->prepare_template ($template_xml_string)
This method can be invoked if the template was not specified in the 'new'
method invocation.
prepare_template_from_file
$xmsg->prepare_template_from_file ($template_file_name)
Same as above, but template is read from file here.
input_xml
$xmsg->input_xml ($inbound_xml_message_content)
Parse an inbound XML message. The values form this message will be used to
fill in COLUMNS and PARAMETERS. The structure of this message should comply
with template. Uses Tree parsing style.
input_xml_file
$xmsg->input_xml_file ($inbound_xml_message_file_name)
Same as above, but the XML message is read from a file.
populate_objects
$xmsg->populate_objects ($global_hash_ref [, $matching_object
[, $tag_name [, $tag_content, [$parameter_index]]]])
This method is trying to stuff the existing template with the inbound
message previously parsed by one of the 'input_xml' methods. The only
mandatory attribute is global hash reference, which has to contain key
values for the topmost tag TEMPLATE.
rexec
$xmsg->rexec ($dbh, $global_hash_ref)
This method is running the created query against a DBI/DBD source and fills
in the template with results in order to make them available for subsequent
output_message call. In case of INSERT/UPDATE operations only key values
will be filled in.
output_message
This method returns a string with query results in XML format suitable for
printing or whatever manupulations seem appropriate.
SEE ALSO
XML::Parser
XML::Parser::Expat
AUTHORS
Andrei Nossov <andrein@andrein.com>
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.