[svn] commit: r3354 - /branches/trac376/src/bin/xfrin/xfrin.py.in

[BIND 10 source code commits]

Author: jelte
Date: Tue Oct 26 08:46:38 2010
New Revision: 3354

Log:
added some comments for understandability

Modified:
    branches/trac376/src/bin/xfrin/xfrin.py.in

Modified: branches/trac376/src/bin/xfrin/xfrin.py.in
==============================================================================
--- branches/trac376/src/bin/xfrin/xfrin.py.in (original)
+++ branches/trac376/src/bin/xfrin/xfrin.py.in Tue Oct 26 08:46:38 2010
@@ -187,7 +187,9 @@
         return XFRIN_OK
 
     def do_xfrin(self, check_soa, ixfr_first = False):
-        '''Do xfr by sending xfr request and parsing response. '''
+        '''Perform xfr by sending an AXFR request and parsing the
+           response. Returns XFRIN_OK on success, XFRIN_FAIL on error.
+        '''
 
         try:
             ret = XFRIN_OK
@@ -199,18 +201,26 @@
             if ret == XFRIN_OK:
                 self.log_msg(logstr + 'started')
                 self._send_query(RRType.AXFR())
-                
+
+                # The transaction and data source are automatically
+                # rolled back/closed by their destructors, so rather
+                # than keeping track of how far we've got we rely
+                # on the destructors to clean up if something goes
+                # wrong.
                 ds = pydatasrc.DataSrc()
                 ds.init("{ \"database_file\": \"" + self._db_file +"\" }")
                 transaction = pydatasrc.DataSrcTransaction(ds, Name(self._zone_name), RRClass.IN())
+
+                # Create a new zone if it doesn't exist (2nd arg)
                 result = ds.start_transaction(transaction, True)
                 if result != ds.SUCCESS:
                     raise XfrinException('Failed to start transaction')
-                
+
+                # AXFR, so replace the whole zone
                 result = ds.replace_zone(transaction, self._handle_xfrin_response)
                 if result != ds.SUCCESS:
                     raise XfrinException('Failed to start transaction')
-                 
+                
                 result = ds.commit_transaction(transaction)
                 if result != ds.SUCCESS:
                     raise XfrinException('Failed to commit transaction')
@@ -225,7 +235,6 @@
             self.log_msg(e)
             self.log_msg(logstr + 'failed')
             ret = XFRIN_FAIL
-            #TODO, recover data source.
         except pydatasrc.DataSrcError as dse:
             self.log_msg(dse)
             self.log_msg(logstr + 'failed')
@@ -270,7 +279,12 @@
             raise XfrinException('query section count greater than 1')
 
     def _handle_xfrin_response(self):
-        '''Return a generator for the response to a zone transfer. '''
+        '''Return a generator for the response to a zone transfer. This
+           method keeps reading packets from the stream until the second
+           SOA record is read. It will yield one RRset at a time.
+           Raises an XfrinException if xfrin is shut down while
+           transfering.
+        '''
         done = False
         soa_seen = False
         while not done: