NAME
DBIx::XML::DataLoader
SYNOPSIS
use DBIx::XML::DataLoader;
my $mapper=DBIx::XML::DataLoader->new(map=>"map.xml");
my $response=$mapper->processxml(xml=>"data.xml");
DESCRIPTION
DBIx::XML::DataLoader contains a set of modules that are meant to work together.
DBIx::XML::DataLoader.pm the core for this package
DB.pm which contains the sql specific stuff
MapIt.pm handles parsing the xml mapping file
IsDefined.pm a simple module for making sure empty data sets are defined
dataloader uses a external map(see map instructions below) file written
in xml to find its instructions for handling the data contained in the
xml data files that will be imported.
SIMPLE EXAMPLE
use DBIx::XML::DataLoader;
#Create a new object
my $mapper=DBIx::XML::DataLoader->new(map=>"map.xml");
my $response=$mapper->processxml(xml=>"data.xml");
#$response will contain a hash referance with the information outputted by the module.
$response->{mesage}; # The message generated by module
$response->{dbmessage}; # the message generated by DBIx::XML::DataLoader::DB.pm
$response->{suberrors}; # errors generated by the subroutines
$response->{dberrors}; # errors generated by DBIx::XML::DataLoader::DB.pm
$responce->{sqlload}; # data formatted to be suitable for inserting using sqllaoder
# requires you set the dbmode to sqlloader
OPTIONAL USAGE
new() can be passed serveral other options besides "map"
Required
map: The map file to be used. This can be a xml fragment
a xml file on the local machine or a url to a xml map file.
Optional
dbmode: this can be set to insert, update, insertupdate, or
sqlloader
insert: will have db.pm only do inserts
update: will have db.pm only do updates
insert/update: the default setting will attempt to insert data
and then it will try to do a update.
sqlloader: will generate data formatted in a way so it can be
written to a DAT file for sqlloader(Oracle). This data will be
returned in $response->{sqlload}.
dbprint: this is used to control whether we actually do the database
work or simulate it by printing the statements to $response->{dbmessage}.
This can be set to db, print, or dbprint.
db: will tell DBIx::XML::DataLoader::DB.pm to just do the assinged dbmode
print: will tell DBIx::XML::DataLoader::DB.pm to simulate the dbmode and return in
dbmessage the sql statement that would have been created.
dbprint: will cause the db.pm module to do both the actual
assigned dbmode and the printed output.
processxml() Needs to have a xml file containing the data.
xml: This can be a xml fragment of xml, a xml file on the server,
or a url to a xml file.
EXAMPLE SIMPLE MAPFILE
<XMLtoDB>
<dbinfo dbuser="db_user_login" dbpass="db_pass_login"
dbsource="data_source" name="a_identifier"/>
<RootElement name="name_of_xml_doc_root"/>
<Table name="db_table_name" db_name="a valid dbinfo name attribute value"
xpath="./xpath_of_tables_root_node">
<KeyColumn name="a db query
key" order="The more common a key values should be given a higher number"/>
<Element xpath="./xpath_to_node" toColumn="sql db column name"/>
</Table>
</XMLtoDB>
MAP FILE RULES
dbinfo
Tag containing attributes with the database user name, password,
data source, and name.
1) Attribute name for database user is dbuser
2) Attribute name for database password is dbpass
3) Attribute name for database source is dbsource
4) Attribute name for database name is name
Sub
This tag is for listing subroutines you would like called prior
to doing the main database insertion/update.
1) Required attributes for this tag are name and rank.
2) Modules containing the subroutines should be kept in @INC
3) The name attribute needs to have the package name and the
subroutine name that will be called. It needs to written as
package->subroutine
4) The when attribute is used to tell the program when to run the subroutine.
The options would be prexml, predb, postdb, and postxml.
5) The rank attribute need to be set to a number. Rank starts at 1
and goes up from there. Subs with he lowest rank will be ran first.
Consecutive numbers must be used for setting rank.
6) A optional attribute of args can be used to pass arguments to the
subroutine being called.
DocKeyColumn
This is a Key db column that is common to multiple tables in the
xml document.
1) the attribute for this tag is name. This attribute should be set
to the db column name that is common.
RootElement
The base element for the document
1) tag has a attributes of name. The name should be set to the documents root
element name
Table
The area containing table data inforamtion. Tag attributes are name and dbname
1) name should be set to a db table name
2) dbname should be set to a valid dbinfo name attribute value
3) xpath shoud be set to the base xpath of the table
Handler
This tag is for passing subroutines durring processing of tables or data
contained in a Element. When Handler is outside a Element then it will be
considered belonging to the Table. Table level handlers have three attributes.
They are name, when, and rank. Only rank is optional. Element level handlers
require only the name attribute but can also have a rank attribute if more than
handler will be called on this data value.
1) The attribute name should be set to a subroutine in @INC or code containing
the actual subroutine. If passing code lable it sub and wrap the code in
brackets (ie. sub{$ _[0]="hello";} would change the value comming
in to "hello")
2) The value for when should be predb or postdb (table level handlers only)
3) The value for rank should be set based on what order you want handlers with
the same parents should be called. The lower the number the earlier it will
be called.
KeyColumn
This is one of the key in the database for the table. The attributes for this
tag are name and order.
1) the attribute name should be set to the name of the column in the table.
2) the attribute order should be set based on the previlance of the column
value in the database(ie. driveletter might be common but computername
in the same row may be more unique. So the order value for computername
would be give a lower number and driveletter a highter value for order).
Element
A Element is how we identify xml nodes containing our data. The attributes
that are required are xpath, toColumn.
1) The attribute xpath should be set to the xpath of the node relative to
the xpath of Table.
2) The attribute toColumn should be set to the column name in the db.
Also see man page for
DBIx::XML::DataLoader::XMLWriter,
DBIx::XML::DataLoader::MapIt, DBIx::XML::DataLoader::DB,
DBIx::XML::DataLoader::IsDefined, and DBIx::XML::DataLoader::Date