--- nfo/perl/libs/Data/Transfer/Sync.pod	2003/01/19 02:03:48	1.1
+++ nfo/perl/libs/Data/Transfer/Sync.pod	2003/02/11 10:20:47	1.4
@@ -3,42 +3,177 @@
 
 =head1 NEWS
 
-=head4 2003-01-18  -  integration with Torus
 
-  please look at http://www.netfrag.org/horde/chora/cvs.php/perl/scripts/outlook2ldap/
+=head4 2003-02-09  -  backward compatibility with custom application
 
+  - Tangram <-> .csv
+  - Tangram <-> mysql
+  - Tangram <-> perl-code
+
+
+=head4 2003-01-18  -  start integration with Torus
+
+  - MAPI <-> LDAP
+  - please visit http://www.netfrag.org/horde/chora/cvs.php/perl/scripts/outlook2ldap/
+
+
+=head4 2002-10-10  -  initial commit
+
+  - Tangram <-> mysql
 
-=head4 2002-10-10  -  initial check-in
 
 
 =head1 DESCRIPTION
 
-Data::Transfer::Sync is a module providing a generic synchronization process
-across arbitrary/multiple storages based on a ident/checksum mechanism.
-It sits on top of Data::Storage.
+  Data::Transfer::Sync is a module providing a generic synchronization process
+  across arbitrary/multiple storages based on a ident/checksum mechanism.
+  It sits on top of Data::Storage.
+
 
 
 =head1 REQUIREMENTS
 
-  For full functionality:
+=head3 dependencies
+
+  from CPAN or (for win32) a ppm-repository:
+    App::Config (CPAN only)
+    Tie::IxHash
+    Log::Dispatch
+    Log::Dispatch::Config
+    mixin
+    Hash::Merge
+    Tie::SecureHash
+    Date::Manip
+    Digest::MD5
+    ... and maybe some more.
+
+  from nfo/perl/libs:
+    Data::Compare
     Data::Storage
     Data::Transform
-    Data::Compare
-    ... and all their dependencies
+    DesignPattern:: (to be renamed into Class::)
+    ... and all their dependencies. (like Data::UUID & Co.)
+
+
+=head3 additional modules required for 'outlook2ldap'
+
+    Win32::OLE
+    Net::LDAP
+
+=head3 additional modules required for 'db2db'
 
+    DBI
+    DBD::mysql
+    DBD::CSV
+    Tangram
 
-=head1 AUTHORS / COPYRIGHT
 
-The Data::Storage module is Copyright (c) 2002 Andreas Motl.
-All rights reserved.
 
-You may distribute it under the terms of either the GNU General Public
-License or the Artistic License, as specified in the Perl README file.
+=head1 AUTHORS / COPYRIGHT / LICENSE
+
+  The Data::Transfer::Sync module is Copyright (c) 2002, 2003 Andreas Motl.
+  All Rights Reserved.
+
+  Code contributions, suggestions, support and ideas by
+  Sebastian Utz <su@tunemedia.de> and Jan Hoffmann <janosch@ultrajan.de>.
+  
+  You may distribute it under the terms of either the GNU General Public
+  License or the Artistic License, as specified in the Perl README file.
+
+
+=head1 COPYRIGHT NOTE
+
+  * CAESAR - Collaborative And Easy System ARchitecture
+  *
+  * Data Synchronization Module
+  *
+  * Permission to use, copy, modify and distribute this software and its
+  * documentation is hereby granted, provided that both the copyright
+  * notice and this permission notice appear in all copies of the
+  * software, derivative works or modified versions, and any portions
+  * thereof, and that both notices appear in supporting documentation.
+  * 
+  * NETFRAG.ORG AND THE AUTHOR ALLOW FREE USE OF THIS SOFTWARE 
+  * IN ITS "AS IS" CONDITION. WE DISCLAIM ANY LIABILITY OF ANY KIND
+  * FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
+ 
 
 
 =head1 SUPPORT / WARRANTY
 
-Data::Storage is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
+  Data::Transfer::Sync is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
+
+  Please feel free to contact me at <andreas.motl@ilo.de>.
+  
+  Any improvements and contributions are greatly appreciated.
+  
+  We have set up a newsgroup. (currently not much traffic)
+  Be welcome to visit news://news.netfrag.org/nfo.caesar or - if your system 
+  lacks a newsreader - try http://news.netfrag.org/nfo.caesar.
+  
+
+
+
+=head1 TODO
+
+=head4 overall
+
+  o try to get this stuff together with SyncML (http://syncml.org/) somehow ...?
+
+
+=head4 this code
+
+  o sub _resolveIdentProvider
+  x wrap _doModifySource and _doTransferTarget around a core function which can change virtually any type of node
+  x split this module up into Sync.pm, Sync/Core.pm, Sync/Compare.pm and Sync/Compare/Checksum.pm
+  o introduce _compareNodes as a core method and wrap it around methods in Sync/Compare/Checksum.pm
+  x introduce Sync/Compare/MyComparisonImplementation.pm
+  o some generic deferring method - e.g. "$self->defer(action)" - to be able to accumulate a bunch of actions for later processing
+     - this implies everything done is _really_ split up into generic actions - how else would we defer them???
+     - example uses:
+        - fetch whole checksum list from node
+        - remember source ident retransmits
+     - remember: this is convenient - and maybe / of course faster - but we'll loose "per-node-atomic" operations
+  o feature: mechanism to implicit inject checksum property to nodes (alter table / modify schema)
+  o expand statistics / keep track of:
+    - touched/untouched nodes
+  o full sync
+    - just do a push and a pull for now but use stats for touched nodes in between to speed up things
+  o introduce some new metadata flags for a descent
+    - isNewNodePropagator
+    x isWriteProtected
+
+
+
+=head1 EXAMPLE OUTPUT CHUNKS
+
+=head2 Synchronizing orm objects against entries in a .csv file - 17 items modified
+
+  notice: PULL INTO backend NODE * TYPE Country SELECT NODE * TYPE [n/a] FROM base USING MODULE MyApp::ResourceMapping;
+  notice: OEF::Script::AbstractFeeder:
+      - Loading data of type [n/a] and
+        filtered by * from the storage named base
+        to the storage named backend - filtered by *.
+      - Will attempt to convert the data to Country.
+  info: Data::Transfer::Sync::API->syncNodes: source=backend/* [Country] <- target=base/* []
+  :c:c:c:c:c:c:c:ctr:c:c:c:c:c:c:c:ctr:c:c:c:c:c:c:ctr:c:ctr:c:c:c:c:c:c:c:c:c:c:c:ctr:c:c:c:ctr:c:c:c:c:c:c:c:ctr:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c
+  :c:c:c:c:c:c:c:c:ctr:c:c:c:c:c:c:c:c:c:c:c:ctr:c:c:c:c:ctr:c:c:c:ctr:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:ctr:ctr:c:c:c:c:ctr:c:c:c:c:c:c:c
+  :c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:ctr:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:ctr:c:c:ctr:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c
+  info: Data::Transfer::Sync::Core->_startsync: statistics: in_sync: 180  /  total: 197  /  attempt_modify: 17  /  ok: 17
+
+=head2 Synchronizing orm objects against entries in a .csv file - in-sync
+  
+  notice: PULL INTO backend NODE * TYPE Country SELECT NODE * TYPE [n/a] FROM base USING MODULE MyApp::ResourceMapping;
+  notice: OEF::Script::AbstractFeeder:
+      - Loading data of type [n/a] and
+        filtered by * from the storage named base
+        to the storage named backend - filtered by *.
+      - Will attempt to convert the data to Country.
+  info: Data::Transfer::Sync::API->syncNodes: source=backend/* [Country] <- target=base/* []
+  :c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c
+  :c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c
+  :c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c:c
+  info: Data::Transfer::Sync::Core->_startsync: statistics: in_sync: 197  /  total: 197
 
 
 
@@ -53,7 +188,7 @@
 =head4 Mapping
 
   - - - - - - - - - - - - - - - - - - - - - - - - - -
-  info: BizWorks::Process::Setup->syncResource( source_node Currency mode PULL erase 0 import 0 )critical: BizWorks::Process::Setup->startSync: Can't access mapping for node "Currency" - please check BizWorks::ResourceMapping.
+  info: MyApp::Process::Setup->syncResource( source_node Currency mode PULL erase 0 import 0 )critical: MyApp::Process::Setup->startSync: Can't access mapping for node "Currency" - please check MyApp::ResourceMapping.
   - - - - - - - - - - - - - - - - - - - - - - - - - -
   You have to create a sub for each node used in synchronization inside named Perl module. The name of this sub _must_ match
   the name of the node you want to sync. This sub holds mapping metadata to give the engine hints about how 
@@ -64,7 +199,7 @@
 =head4 DBD::AutoCSV's rulebase
   
   - - - - - - - - - - - - - - - - - - - - - - - - - -
-  info: BizWorks::Process::Setup->syncResource( source_node Currency mode PULL erase 0 import 0 )
+  info: MyApp::Process::Setup->syncResource( source_node Currency mode PULL erase 0 import 0 )
   info: Data::Transfer::Sync->syncNodes: source=L/Currency <- target=R/currencies.csv
   
   Execution ERROR: Error while scanning: Missing first row or scanrule not applied. at C:/home/amo/develop/netfrag.org/nfo/perl/libs/DBD/CSV.p
@@ -123,27 +258,6 @@
   - - - - - - - - - - - - - - - - - - - - - - - - - -
 
 
-=head1 TODO
-
-  - sub _resolveIdentProvider
-  - wrap _doModifySource and _doTransferTarget around a core function which can change virtually any type of node
-  - split this module up into Sync.pm, Sync/Core.pm, Sync/Compare.pm and Sync/Compare/Checksum.pm
-     - introduce _compareNodes as a core method and wrap it around methods in Sync/Compare/Checksum.pm
-  - introduce Sync/Compare/MyComparisonImplementation.pm
-  - some generic deferring method - e.g. "$self->defer(action)" - to be able to accumulate a bunch of actions for later processing
-     - this implies everything done is _really_ split up into generic actions - how else would we defer them???
-     - example uses:
-        - fetch whole checksum list from node
-        - remember source ident retransmits
-     - remember: this is convenient - and maybe / of course faster - but we'll loose "per-node-atomic" operations
-  - feature: mechanism to implicit inject checksum property to nodes (alter table / modify schema)
-  - expand statistics / keep track of:
-    - touched/untouched nodes
-  - full sync
-    - just do a push and a pull for now but use stats for touched nodes in between to speed up things
-  - introduce some new metadata flags for a synchronization partner which is (e.g.) of "source" or "target":
-    - isNewNodePropagator
-    - isWriteProtected
 
 
 =cut