NAME

       XML::Filter::Sort::BufferMgr - Implementation class used by XML::Filter::Sort

DESCRIPTION

       The documentation is targetted at developers wishing to extend or replace this class.  For user
       documentation, see XML::Filter::Sort.

       Two classes are used to implement buffering records and spooling them back out in sorted order as SAX
       events.  One instance of the XML::Filter::Sort::Buffer class is used to buffer each record and one or
       more instances of the XML::Filter::Sort::BufferMgr class are used to manage the buffers.

API METHODS

       The API of this module as used by XML::Filter::Sort::Buffer consists of the following sequence of method
       calls:

       1.  When   the   first   'record'   in   a   sequence   is   encountered,   XML::Filter::Sort  creates  a
           XML::Filter::Sort::BufferMgr object using the "new()" method.

       2.  XML::Filter::Sort calls the buffer manager's "new_buffer()" method to get a XML::Filter::Sort::Buffer
           object and all SAX events are directed to this object until the end of  the  record  is  encountered.
           The following events are supported by the current buffer implementation:

             start_element()
             characters()
             comment()
             processing_instruction()
             end_element()

       3.  When the end of the record is detected, XML::Filter::Sort calls the buffer manager's "close_buffer()"
           method,  which  in  turn calls the buffer's "close()" method.  The "close()" method returns a list of
           values for the sort keys and the buffer manager uses these to store  the  buffer  for  later  recall.
           Subsequent records are handled as per step 2.

       4.  When  the  last  record  has  been  buffered, XML::Filter::Sort calls the buffer manager's "to_sax()"
           method.  The buffer manager retrieves each of the buffers in sorted  order  and  calls  the  buffer's
           "to_sax()" method.

       Each buffer attempts to match the sort key paths as SAX events are received.  Once a value has been found
       for  a  given  key, that same path match is not attempted against subsequent events.  For efficiency, the
       code to match each key is compiled into a closure.  For even more efficiency, this  compilation  is  done
       once  when the XML::Filter::Sort object is created.  The "compile_matches()" method in the buffer manager
       class calls the "compile_matches()" method in the buffer class to achieve this.

DATA STRUCTURES

       In the current implementation, the XML::Filter::Sort::BufferMgr class simply uses a  hash  to  store  the
       buffer  objects.   If  only  one sort key was defined, only a single hash is required.  The values in the
       hash are arrayrefs containing the list of buffers for records with identical keys.

       If two or more sort keys are defined, the hash values will be XML::Filter::Sort::BufferMgr objects  which
       in  turn  will  contain  the buffers.  The following illustration may clarify the relationship (BM=buffer
       manager, B=buffer):

                                        BM
                        +----------------+---------------+
                        |                                |
                       BM                               BM
                  +-----+--------+                 +-----+----------+
                  |              |                 |                |
                 BM             BM                BM               BM
            +-----+----+    +----+------+     +----+----+    +------+------+
            |     |    |    |    |      |     |    |    |    |      |      |
         [B,B,B] [B] [B,B] [B] [B,B] [B,B,B] [B] [B,B] [B] [B,B] [B,B,B] [B,B]

       This layered storage structure is transparent to the  XML::Filter::Sort  object  which  instantiates  and
       interacts with only one buffer manager (the one at the top of the tree).

COPYRIGHT

       Copyright 2002 Grant McLean <grantm@cpan.org>

       This  library  is  free  software;  you can redistribute it and/or modify it under the same terms as Perl
       itself.

perl v5.26.1                                       2018-03-30                  XML::Filter::Sort::BufferMgr(3pm)