Debian Codegraph @

README

raw
1 INSTALLATION:
2
3 $ perl Makefile.PL
4 $ make
5 $ make install
6
7 NOTE: There is no test against a "live" datasource anymore. Please edit the
8 sybase.t.removed and move it to t/sybase.t if you'd like to perform one.
9
10
11 Modification log
12 --------------------------------------------------------------------------------
13 Version Date Author Notes
14 -------- -------- -------------- -----------------------------------------------
15 0.05 9/01 Andrei Nossov Removed $self->debug() and test against Sybase
16 0.04 3/01 Andrei Nossov Root compound key bug fixed
17 0.03 11/00 Andrei Nossov Bug fixes, more documentation
18 0.02 10/00 Andrei Nossov Documentation improved
19 0.01 8/00 Andrei Nossov First cut
20 --------------------------------------------------------------------------------
21
22 NAME
23
24 DBIx::XMLMessage - XML Message exchange between DBI data sources
25
26
27
28 --------------------------------------------------------------------------------
29
30 SYNOPSIS
31
32
33 --------------------------------------------------------------------------------
34
35 OUTBOUND MESSAGE
36
37 #!/usr/bin/perl
38
39
40
41 use DBI;
42 use DBIx::XMLMessage;
43
44
45
46 # Template string
47 my $tpl_str =<< "_EOT_";
48 <?xml version="1.0" encoding="UTF-8" ?>
49 <TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'>
50 <KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' />
51 <COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' />
52 <COLUMN NAME='PasswordDate' EXPR='pwdate' DATATYPE='DATETIME'
53 BLTIN="fix_gmdatetime" />
54 <CHILD NAME='SysUsers' TABLE='sysusers'>
55 <KEY NAME='suid' PARENT_NAME='LoginId' DATATYPE='NUMERIC' />
56 <COLUMN NAME='UserId' EXPR='uid' DATATYPE='NUMERIC' />
57 <COLUMN NAME='UserName' EXPR='name' />
58 </CHILD>
59 </TEMPLATE>
60 _EOT_
61 my $msg = new DBIx::XMLMessage ('TemplateString' => $tpl_str);
62 my $ghash = { 'OBJECT_ID' => [ 1, 2 ] };
63 my $dbh = DBI->connect('dbi:Sybase:server=x;database=master','sa','secret');
64 $msg->rexec ($dbh, $ghash);
65
66
67
68 print "\n\n", $msg->output_xml(0,0);
69 print "\n\n", $msg->output_xml(0,1);
70
71
72
73
74 --------------------------------------------------------------------------------
75
76 INBOUND MESSAGE
77
78 #!/usr/bin/perl
79
80
81
82 use DBI;
83 use DBIx::XMLMessage;
84
85
86
87 my $template_xml =<< "_EOD1_";
88 <?xml version="1.0" encoding="UTF-8" ?>
89 <TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'
90 ACTION='SAVE'>
91 <KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' />
92 <COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' />
93 <COLUMN NAME='PasswordDate' EXPR='pwdate' DATATYPE='DATETIME'
94 BLTIN="fix_gmdatetime" />
95 <CHILD NAME='SysUsers' TABLE='sysusers'>
96 <KEY NAME='suid' PARENT_NAME='LoginId' DATATYPE='NUMERIC' />
97 <COLUMN NAME='UserId' EXPR='uid' DATATYPE='NUMERIC' />
98 <COLUMN NAME='UserName' EXPR='name' />
99 </CHILD>
100 </TEMPLATE>
101 _EOD1_
102
103
104
105 my $message_xml =<< "_EOD2_";
106 <?xml version="1.0" encoding="UTF-8"?>
107 <SysLogins>
108 <LoginId>1</LoginId>
109 <PasswordDate>1999/08/17 08:31</PasswordDate>
110 <SysUsers>
111 <UserId>1</UserId>
112 <UserName>sa</UserName>
113 </SysUsers>
114 </SysLogins>
115 _EOD2_
116
117
118
119 my $xmlmsg = new DBIx::XMLMessage ('TemplateString' => $template_xml);
120 my $msgtype = $xmlmsg->input_xml($message_xml);
121 my $ghash = {
122 'OBJECT_ID' => [ 1 ]
123 };
124 $xmlmsg->populate_objects ($ghash);
125
126
127
128 my $dbh = DBI->connect('dbi:Sybase:server=x;database=master','sa','secret');
129 $xmlmsg->rexec ($dbh, $ghash);
130 print $xmlmsg->output_message();
131
132
133
134
135 --------------------------------------------------------------------------------
136
137 DESCRIPTION
138 The package maintains simple XML templates that describe object structure.
139
140 The package is capable of generating SQL statements based on these templates
141 and executing them against DBI data sources. After executing the SQL, the package
142 formats the data results into XML strings. E.g. the following simple template
143
144
145 <TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'
146 ACTION='SAVE'>
147 <KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' />
148 <COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' />
149 </TEMPLATE>
150
151
152 being executed with key value = 1, will be tranlated into this SQL:
153
154 SELECT suid LoginId FROM syslogins where suid = 1
155
156 and the result will be formatted into this XML string:
157
158
159 <SysLogins>
160 <LoginId>1<LoginId>
161 </SysLogins>
162
163
164 Inbound messages can be processed according to the same kind of templates and
165 the database is updated accordingly. Templates are capable of defining the SQL
166 operators, plus new SAVE operation which is basically a combination of SELECT
167 and either INSERT or UPDATE depending on whether the record was found by the
168 compound key value or not.
169
170
171
172 --------------------------------------------------------------------------------
173
174 SALES PITCH
175 This package allows for objects exchange between different databases. They could
176 be from different vendors, as long as they both have DBD drivers. In certain
177 cases it is even possible to exchange objects between databases with different
178 data models. Publishing of databases on the web could potentially be one of the
179 applications as well.
180
181
182
183 --------------------------------------------------------------------------------
184
185 TEMPLATE TAGS
186
187
188 --------------------------------------------------------------------------------
189
190 TEMPLATE
191 This is manadatory top-level tag. It can correspond to a certain table and be
192 processed just like table-level REFERENCE and CHILD attributes described below.
193 Some of TEMPLATE attributes are related to the whole template (e.g. TYPE or
194 VERSION) while others desribe the table ti's based on (e.g. TABLE)
195
196 If the TABLE attribute is defined, the generated SQL is going to run against
197 some table. Otherwise a SQL with no table will be generated. This only makes
198 sense for outbound messages and only possible on certain engines, like Sybase.
199 Also, the immediate child columns should contain constants only for apparent
200 reasons.
201
202
203
204 --------------------------------------------------------------------------------
205
206 REFERENCE
207 REFERENCE is a table-level tag. It's meant to represent a single record from
208 another table that's retrieved by unique key. E.g. if my current table is EMPL
209 then DEPARTMENT would be a REFERENCE since employee can have no more than one
210 departament.
211
212
213
214 --------------------------------------------------------------------------------
215
216 CHILD
217 This tag meant to represent a number of child records usually retrieved by a
218 foreign key value (probably primary key of the current table). Right now there's
219 no difference in processing between CHILD and REFERENCE, but it may appear in the
220 future releases.
221
222
223
224 --------------------------------------------------------------------------------
225
226 COLUMN
227 This tag is pretty self-explanatory. Each COLUMN tag will appear on the SELECT,
228 INSERT or UPDATE list of the generated SQL.
229
230
231
232 --------------------------------------------------------------------------------
233
234 KEY
235 Key represents linkage of this table's records to the parent table. All KEY's
236 will appear on the WHERE clause as AND components. This way of linkage is typical
237 for most of relational systems and considered to be a good style. I guess it
238 shouldn't be much of a restriction anyway. If it gets that, you could try tweak
239 up the WHERE_CLAUSE attribute..
240
241
242
243 --------------------------------------------------------------------------------
244
245 PARAMETER
246 This tag represents a parameter that will be passsed to a stored procedure.
247 Currently, only Sybase-style stored procedures are supported, i.e.
248
249 exec proc_name @param_name = 'param_value', ...
250
251 Fixes for Oracle, DB2 and Informix are welcome..
252
253
254
255 --------------------------------------------------------------------------------
256
257 TEMPLATE TAG ATTRIBUTES
258
259
260 --------------------------------------------------------------------------------
261
262 NAME
263
264 Applicable to: All template tags
265 Required for: All template tags
266
267
268 NAME is the only required attribute for all of the template tags. The main
269 purpose of it is to specify the tag name as it will appear in the resulting XML
270 document. Also, depending on the template tag type (COLUMN, PARAMETER and KEY)
271 it may serve as default value for EXPR discussed below. Here's a small example
272 of how it works. If my column is represented in the template like this:
273
274
275 <COLUMN NAME='ObjectId' />
276
277
278 the resulting SQL will contain
279
280
281 SELECT ObjectID, ...
282
283
284 whereas if I have
285
286
287 <COLUMN NAME='ObjectId' EXPR='igObjectId' />
288
289
290 it will generate the following SQL:
291
292
293 SELECT igObjectId ObjectID, ...
294
295
296 I.e. in the latter example, NAME used as an alias and EXPR as a real database
297 column name. The column in the first example has no alias.
298
299
300
301 --------------------------------------------------------------------------------
302
303 ACTION
304
305 Applicable to: TEMPLATE, REFERENCE, CHILD
306 Required for: None
307
308
309 Possible values for this attibute are SELECT, INSERT, UPDATE, EXEC and SAVE. If
310 action is not provided, it is assumed that t he action should be SELECT. The
311 first 4 values correspond to SQL data management operators (EXEC is
312 vendor-specific and represents execution of a stored procedure). The fifth
313 value, SAVE, is basically a combination of SELECT and either INSERT or UPDATE,
314 depending on whether the record was found by the compound key value or not. This
315 often helps to avoid usage of complicated stored procedures with primary key
316 generation and keep things generic and scalable. Primary key generation issue is
317 addressed separately by using of the GENERATE_PK attribute (see below).
318
319
320
321 --------------------------------------------------------------------------------
322
323 BLTIN
324
325 Applicable to: COLUMN
326 Required for: None
327
328
329 Represents a perl built-in function. before invocation of this subroutine the
330 package prepares array @_ and makes it visible to the built-in function. The 3
331 arguments received by the built-in are: $self - DBIx::XMLMessage object $node -
332 Correspondent DBIx::XMLMessage::COLUMN object. You can use it to obtain other
333 column attributes, e.g. $node->{DATATYPE} $value - The column value
334
335 Meaning of the value depends on direction of the message, i.e. whether the
336 message is inbound or outbound. In case of inbound message, this is the value
337 received by the package from outside world; if the message is inbound then this
338 is the value selected from database. There's one built-in function that comes
339 with the package -- fix_gmdatetime. It converts date and time to GMT for outbound
340 messages and from GMT to the database date/time for inbound messages. Just add
341 one attribute to your datetime column:
342
343
344 ... BLTIN="fix_gmdatetime" ...
345
346
347
348
349 --------------------------------------------------------------------------------
350
351 CARDINALITY
352
353 Applicable to: KEY, PARAMETER, REFERENCE, CHILD
354 Required for: None
355 Possible values: REQUIRED, OPTIONAL
356 Default: REQUIRED
357
358
359 This parameter has different meaning for different element types. Optional KEYs
360 and PARAMETERs allow to proceed execution if the value for it was not found at
361 some point of execution. Optional CHILDs and REFERENCEs will be skipped from
362 execution, and hence from output, if the package failed to collect all the key
363 values.
364
365
366
367 --------------------------------------------------------------------------------
368
369 DATATYPE
370
371 Applicable to: KEY, PARAMETER, COLUMN
372 Required for: None
373 Possible values: CHAR, VARCHAR, VARCHAR2, DATE, DATETIME, NUMERIC
374 Default: CHAR
375
376
377 This attribute loosely corresponds to the database column type. The only
378 processing difference in the core package is quoting of the non-numeric
379 datatypes, particularly those containign substrings CHAR, DATE or TIME. The
380 built-in fix_gmdatetime utilizes this attribute more extensively.
381
382
383
384 --------------------------------------------------------------------------------
385
386 DEBUG
387 Recognized but not currently supported
388
389
390
391 --------------------------------------------------------------------------------
392
393 DEFAULT
394
395 Applicable to: PARAMETER, COLUMN
396 Required for: None
397 Possible values: Any string or number
398
399
400 This attribute allows to provide a default value for COLUMNs and PARAMETERS.
401 Please note that default values are not being formatted, so they have to
402 represent the literal value. E.g. if you want to provide a string DEFAULT it
403 would look somewhat like this: ... DEFAULT = ``'UNKNOWN'''
404
405
406
407 --------------------------------------------------------------------------------
408
409 EXPR
410
411 Applicable to: All template tags
412 Required for: None
413
414
415 For COLUMN and KEY this attribute represents the actual database column name or
416 a constant. For PARAMETER
417
418
419
420 --------------------------------------------------------------------------------
421
422 FACE
423
424 Applicable to: COLUMN
425 Required for: None
426 Possible values: ATTRIBUTE, TAG
427 Default: TAG
428
429
430 This attribute allows to output certain columns as attributes, as opposed to
431 the default TAG-fasion output. Since it's not supported for inbound messages
432 yet, usage of this feature is not recommended.
433
434
435
436 --------------------------------------------------------------------------------
437
438 GENERATE_PK
439
440 Applicable to: COLUMN
441 Required for: None
442 Possible values: HASH, SQL returning one value or name
443
444
445 This attribute allows you to specify how to generate primary key values. You
446 have 2 options here:
447
448 1. You can write your own Perl function, put its reference to the global hash
449 under the name of the table for which you intend to generate primary key values
450 and provide the value of 'HASH' as the GENERATE_PK value
451
452 2. You can put the generating SQL block/statement into the GENERATE_PK value
453
454
455
456 --------------------------------------------------------------------------------
457
458 HIDDEN
459
460 Applicable to: COLUMN
461
462
463 Indicates that the column will be excluded from the output. This attribute only
464 makes sense for outbound messages.
465
466
467
468 --------------------------------------------------------------------------------
469
470 MAXROWS
471
472 Currently not supported. In future, intends to limits the number of selected
473 rows.
474
475
476
477 --------------------------------------------------------------------------------
478
479 PARENT_NAME
480
481 Applicable to: KEY
482
483
484 Indicates the name of the tag one level up to which this one tag is
485 corresponding. E.g.
486
487
488 ...
489 <COLUMN NAME='OBJECT_ID'/>
490 <REFERENCE ...>
491 <KEY NAME='nOrderId' PARENT_NAME='OBJECT_ID'/>
492 </REFERENCE>
493
494
495 This feature is a workaround allowing to have two columns descending from the
496 same parent column at the same level. There was some other prolem it was helping
497 to resolve, but I forgot what it was ;^)
498
499
500
501 --------------------------------------------------------------------------------
502
503 PROC
504
505 Applicable to: TEMPLATE, REFERENCE, CHILD
506
507
508 Used in conjunction with ACTION='PROC'. Defines the name of the stored procedure
509 to invoke.
510
511
512
513 --------------------------------------------------------------------------------
514
515 RTRIMTEXT
516 Currently not supported. The package does automatic right-trimming for all the
517 character data.
518
519
520
521 --------------------------------------------------------------------------------
522
523 TABLE
524 Name of the table against which the SQL will be run.
525
526
527
528 --------------------------------------------------------------------------------
529
530 TOLERANCE
531
532 Applicable to: TEMPLATE, REFERENCE, CHILD
533 Possible values: IGNORE, CREATE, REJECT
534 Default: IGNORE
535
536
537 Allows to adjust package behaviour when SQL execution produces unexpected result
538 columns. E.g. if there's a stored procedure that will return the results for your
539 message, you can omit describing of all the resulting COLUMNS in the template and
540 instead specify ... TOLERANCE='CREATE' Whatever columns are returned by the
541 stored procedure (Sybase & MS SQL) will be added on-the-fly and available for
542 the output.
543
544
545
546 --------------------------------------------------------------------------------
547
548 WHERE_CLAUSE
549 Additional where clause. Added as an AND component at the end of generated
550 where clause.
551
552
553
554 --------------------------------------------------------------------------------
555
556 METHODS
557
558
559 --------------------------------------------------------------------------------
560
561 new
562
563 my $xmsg = new DBIx::XMLMessage (
564 [ _OnError => $err_coderef, ]
565 [ _OnTrace => $trace_coderef, ]
566 [ _OnDebug => $debug_coderef, ]
567 [ Handlers => $expat_handlers_hashref, ]
568 [ TemplateString => $xml_template_as_a_string, ]
569 [ TemplateFile => $xml_template_file_name, ]
570 )
571
572
573 You can specify either TemplateString or TemplateFile, but not both. If any of
574 those specified, the template will be parsed.
575
576
577
578 --------------------------------------------------------------------------------
579
580 set_handlers
581
582 $xmsg->set_handlers ($expat_handlers_hashref)
583
584
585 Set additional expat handlers, see XML::Parser::Expat. Normally you won't use
586 this. The only case I could think of is processing of encoding..
587
588
589
590 --------------------------------------------------------------------------------
591
592 prepare_template
593
594 $xmsg->prepare_template ($template_xml_string)
595
596
597 This method can be invoked if the template was not specified in the 'new'
598 method invocation.
599
600
601
602 --------------------------------------------------------------------------------
603
604 prepare_template_from_file
605
606 $xmsg->prepare_template_from_file ($template_file_name)
607
608
609 Same as above, but template is read from file here.
610
611
612
613 --------------------------------------------------------------------------------
614
615 input_xml
616
617 $xmsg->input_xml ($inbound_xml_message_content)
618
619
620 Parse an inbound XML message. The values form this message will be used to fill
621 in COLUMNS and PARAMETERS. The structure of this message should comply with
622 template. Uses Tree parsing style.
623
624
625
626 --------------------------------------------------------------------------------
627
628 input_xml_file
629
630 $xmsg->input_xml_file ($inbound_xml_message_file_name)
631
632
633 Same as above, but the XML message is read from a file.
634
635
636
637 --------------------------------------------------------------------------------
638
639 populate_objects
640
641 $xmsg->populate_objects ($global_hash_ref [, $matching_object
642 [, $tag_name [, $tag_content, [$parameter_index]]]])
643
644
645 This method is trying to stuff the existing template with the inbound message
646 previously parsed by one of the 'input_xml' methods. The only mandatory
647 attribute is global hash reference, which has to contain key values for the
648 topmost tag TEMPLATE.
649
650
651
652 --------------------------------------------------------------------------------
653
654 rexec
655
656 $xmsg->rexec ($dbh, $global_hash_ref)
657
658
659 This method is running the created query against a DBI/DBD source and fills in
660 the template with results in order to make them available for subsequent
661 output_message call. In case of INSERT/UPDATE operations only key values will
662 be filled in.
663
664
665
666 --------------------------------------------------------------------------------
667
668 output_message
669 This method returns a string with query results in XML format suitable for
670 printing or whatever manupulations seem appropriate.
671
672
673
674 --------------------------------------------------------------------------------
675
676 SEE ALSO
677
678 DBI
679 DBD
680 XML::Parser
681 XML::Parser::Expat
682
683
684
685
686 --------------------------------------------------------------------------------
687
688 AUTHORS
689
690 Andrei Nossov <[email protected]>
691
692
693 This library is free software; you can redistribute it and/or modify it under
694 the same terms as Perl itself
695