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.40.1                                       2025-11-24                  XML::Filter::Sort::BufferMgr(3pm)