|
/export/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/Data-Sync/blib/html/site/lib/Data/Sync.html |
or</PRE> <PRE>
$sync->target($dbhandle,{table=>'targettable',
index=>'NAME'
hashattributes=>["ADDRESS","PHONE"]
});</PRE>
<PRE>
or</PRE> <PRE>
$sync->target($ldaphandle,{hashattributes=>["ADDRESS","PHONE"]}
);</PRE>
<P></P>
<PRE>
Requires a valid, bound (i.e. logged in) DBI or Net::LDAP handle, and a hash of parameters (unless you are loading the config from a file). No parameters are required for LDAP data targets, but a dn must have been either read from the data source or constructed using buildattributes. Valid DBI parameters are</PRE> <PRE> table - the table you wish to write to on the data target index - the attribute you wish to use as an index</PRE> <P>There is no 'pre check' on datatypes or lengths, so if you attempt to write a record with an oversized or mismatched data type, it will fail with an error.</P> <P>Note: if you are writing from DB to LDAP, you must construct all mandatory attributes using buildattributes, or additions will fail.</P> <P>Attribute hashing can be specified with the keys:</P> <PRE> index=>"index/key attribute" hashattributes=>["attrib","attrib","attrib"]</PRE> <P>When running, this will create an MD5 hash of the concatentation of the specified attributes, and store it in a database under the specified index. Next time the job is run, it will hash the value again, and compare it with the last hashed value. If they are the same, the record will not be written to the target. These entries are stored in a SQLite database - if you want to manipulate the database directly, you can do so with a sqlite3 client. The SQLite database takes it's name from the 'jobname' attribute specified in $sync->new. If you didn't specify a jobname, it will default to 'noname' - so if you are running multiple jobs with attribute hashing in the same directory on your disk, it's important to make sure they have names.</P> <P> <H2><A NAME=``mappings''>mappings</A></H2> <PRE> $sync->mappings(FIRSTNAME=>'givenName',SURNAME=>'sn');</PRE> <P>Maps individual field names from the data source, to their corresponding field names in the data target.</P> <P> <H2><A NAME=``buildattributes''>buildattributes</A></H2> <PRE> $sync->buildattributes(dn=>"cn=%NAME%,ou=testcontainer,dc=test,dc=org", objectclass=>"organizationalUnit");</PRE> <P>Builds new target attributes up from existing source attributes. A simple template form is used - the template should be a string variable, containing the source field name between % delimiters. If no % delimiters are found, the string will be written as a literal.</P> <P> <H2><A NAME=``transforms''>transforms</A></H2> <PRE> $sync->transforms( PHONE=>'s/0(\\d{4})/\+44 \(\$1\)/', OFFICE=>"stripspaces", ADDRESS=>sub{my $address=shift; $address=~s/\n/\<BR\>/g; return $address});</PRE> <P>Converts each field in the source data using the parameters passed. Each parameter pair is the <EM>target</EM> field name, along with a regex (in a string), a coderef, or a standard function. The following list of transformation functions are supplied in this version:</P> <PRE> stripspaces stripnewline uppercase lowercase concatenate</PRE> <P>concatenate joins together the values of a multi valued attribute with the content of $sync->{mvseparator} - this defaults to | but can be changed with:</P> <PRE> $sync->mvseparator("<separator>");</PRE> <P>Transformations are recursive, so if you are importing some form of hierarchical data, the transformation will walk the tree until it finds a scalar (or a list, in the case of concatenate) that it can perform the transformation on.</P> <P>Note: If passing a regex in a string, make sure you use single quotes. Double quotes will invite perl to interpolate the contents, with unexpected results.</P> <P> <H2><A NAME=``validation''>validation</A></H2> <PRE> $sync->validation( address=>"/street/i", name=>"/(Dr|Mr|Mrs|Ms|Miss)/" );</PRE> <P>Validation defines pattern matches for attributes. The validation methods are the last to be called before writing. If any of the specified fields fail to match the specified pattern match, the whole validation will fail and the write will not happen. Validation is optional, you don't have to specify a validation set, but it's useful to ensure that the constructed record set is what you were expecting before you write it out. Validation is also recursive, so it will handle multi valued attributes and subtrees in LDAP.</P> <P> <H2><A NAME=``deletes''>deletes</A></H2> <PRE> $sync->deletes("delete");</PRE> <PRE> or </PRE> <PRE>
$sync->delete(attrib=>value,attrib=>value);</PRE> <PRE>
Define the action to be taken against entries that have been deleted. Note that this only works if hashing is defined in 'target'. The parameters can be "delete", in which case the entry is deleted, or attrib=>value pairs, in which case the specified attributes are changed to the string in 'value'. Note that it is impossible to do a 'transform' on the attribute value, as the data is no longer present once a delete has been detected.</PRE> <P> <H2><A NAME=``save''>save</A></H2> <PRE> $sync->save("filename");</PRE> <P>Saves the config to a Data::Dump::Streamer file. Returns 1 on success.</P> <P> <H2><A NAME=``load''>load</A></H2> <PRE> $sync->load("filename");</PRE> <P>Loads the config from a Data::Dump::Streamer file previously created with save. You still need to define the source and target db/ldap handles with source & target, but if you've loaded the config from a file you can omit the hash of options.</P> <P> <H2><A NAME=``run''>run</A></H2> <PRE> $sync->run() or die $sync->error."\n";</PRE> <P>No parameters. Reads the data from the source, converts and renames it as defined in mappings, buildattributes and transforms, and writes it to the target.</P> <P> <H2><A NAME=``error''>error</A></H2> <PRE> print $sync->error;</PRE> <P>Returns the last error encountered by the module. This is set e.g. when a file fails to load correctly, when a sql error is encountered etc. When this occurs, the return value from the called function will be zero, and <CODE>error()</CODE> should be called to identify the problem.</P> <P> <H2><A NAME=``lastruntime''>lastruntime</A></H2> <PRE> print $sync->lastruntime;</PRE> <P>Returns the last time the job was run as YYYYMMDDHHMMSS. This is saved in the config file.</P> <P> <H2><A NAME=``mvseparator''>mvseparator</A></H2> <PRE> $sync->mvseparator("<separator>");</PRE> <PRE> print $sync->mvseparator();</PRE> <P>Sets or returns the multi valued attribute separator. (defaults to |)</P> <P> <H2><A NAME=``commit''>commit</A></H2> <PRE> $sync->commit();</PRE> <P>Calls the write handle commit method, where the write handle is DBI (there's no rollback/commit available in LDAP). This is provided as a convenience, just in case you have autocommit turned off on your db handle.</P> <P> <HR> <H1><A NAME=``see also''>SEE ALSO</A></H1> <P>More detail on extra methods, accessing the internal methods of Data::Sync from your code, and subclassing are detailed in Data::Sync::Advanced</P> <P> <HR> <H1><A NAME=``prereqs''>PREREQ/A</H1> <P>If you want to save and load definition files, you'll need Data::Dump::Streamer</P> <P>If you are using DBI datasources, you will need DBI & the appropriate DBI drivers.</P> <P>If you are using LDAP datasources, you will need Net::LDAP.</P> <P>If you are using attribute hashing, you will also need DBI & DBD::SQLite</P> <P> <HR> <H1><A NAME=``version''>VERSION</A></H1> <P>0.07</P> <P> <HR> <H1><A NAME=``bugs & caveats''>BUGS & CAVEAT/A</H1> <P>Data::Sync handles column/attribute names as case sensitive. Postgresql (at least at time of writing) appears to return column names as lc, whether they're created lc or not. I make no guarantees about this, but using lower case column names in all Data::Sync code seems to work OK. Please ensure that any code you write using this module with postgresql is particularly thoroughly tested.</P> <P> <HR> <H1><A NAME=``todo''>TODO</A></H1> <P>Hashing individual attributes so if one attribute changes, only that attribute is written.</P> <P>UI changes: instead of passing a handle, pass a type=>LDAP/DBI/Psql etc, and the connect parameters. Restructure in subclasses so that DBI is a generic sql, but can be subclassed by specific classes for particular datasources. This is a major change to the UI. write a handle factory to create the db/ldap handle. The AoH for records, and methods for read and write are required. This sits well with the dispatcher class. Retain handle passing UI facility if possible, but deprecate.</P> <P>Implementing Data::Sync::Datasource as a dispatcher class redirecting to ::dbi & ::ldap would fit the UML model better, might make subclassing easier, and would probably be easier to maintain. For other divisions see Classes.dia</P> <P>Validation can be extended for deletes by putting a % comparison of recordset vs delete set in 'run'</P> <P>Multiple sources in a single job? Possibly by naming, and with a default name to support existing syntax.</P> <P>Separate out the table creation methods into a <CODE>subclass(?)</CODE> and use a dispatcher? (table creation WIP)</P> <P>Friendly CSV/TD source/target methods</P> <P>Modular datasource/targets for including non dbi/ldap datasources? </P> <PRE>
Example using AnyData & XMPRE <P>Multiple targets in a single job?</P> <P>Caching?</P> <P>UTF8/ANSI handling.</P> <P>Perltidy the tests (thanks for spotting the mess Gavin)</P> <P> <HR> <H1><A NAME=``changes''>CHANGE/A</H1> <P>v0.08</P> <P>Bugfix, added package statement to Advanced.pm to ensure correct CPAN indexing</P> <P>v0.07</P> <P>Added in 'add if no index' facility on writedbi</P> <P>Generalised delta code</P> <P>Removed 'use DDS' and replaced with 'require' in save and load methods, so dependency is only if using those functions</P> <P>Implemented ::deletes</P> <P>Generalised sourceToAoH & write methods</P> <P>Separated complex uses into Data::Sync::Advanced POD</P> <P>Implemented get & put methods</P> <P>Implemented hashrecord method</P> <P>extended testing</P> <P>v0.06</P> <P>Implemented a commit method for the writehandle.</P> <P>Implemented validate function</P> <P>v0.05</P> <P>Fixed some 0E0 problems with return values from DBI.</P> <P>Added postgresql caveat.</P> <P>Extended developer test suite to include MySQL & Postgresql</P> <P>v0.04</P> <P>Implemented basic attribute hashing</P> <P>Added concatenate function for multivalued ldap attributes</P> <P>v0.03</P> <P>Added uppercase and lowercase transformations</P> <P>Moved read and write subs out of anonymous blocks</P> <P>hid raw regex in #!#<regex>#!# inside coderef for regex transformations (can be parsed out for display/edit in gui)</P> <P>implemented batch updating</P> <P>V0.02</P> <P>Implemented load & save functions.</P> <P>Implemented error function</P> <P>Modified stripnewlines to replace with whitespace.</P> <P> <HR> <H1><A NAME=``copyright''>COPYRIGHT</A></H1> <P>Copyright (c) 2004-2005 Charles Colbourn. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</P> <P> <HR> <H1><A NAME=``author''>AUTHOR</A></H1> <P>Charles Colbourn</P> <P><A HREF=``mailto:charlesc@g0n.net''>charlesc@g0n.net</P> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR=``#cccccc''> <FONT SIZE=+1><STRONG><P CLASS=block> Data::Sync - A simple metadirectory/datapump module</P></STRONG></FONT> </TD></TR> </TABLE>
</BODY>
</HTML>
|
/export/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/Data-Sync/blib/html/site/lib/Data/Sync.html |