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.