1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
<!-- vim:tabstop=4:shiftwidth=4:noexpandtab:textwidth=80
-->
<sect1 id="kernel_part_xrefwriter">
<title>XRefWriter</title>
<para>
XRefWriter class inherits from <classname>CXref</classname> and provides
<itemizedlist>
<listitem>
public interface for making changes and storing them to the
stream.
</listitem>
<listitem>
maintains document revisions and current revision (with logic,
what and how it can be do in which revision)
</listitem>
<listitem>
keeps its mode
<itemizedlist>
<listitem><emphasis>paranoid</emphasis> mode forces paranoiCheck method
call in changeObject method. This checks whether given reference
is known and given object is compared with current one by
<classname>CXref::typeSafe</classname> method. If checking doesn't fail, object can be
changed and delegates the rest of the work to the
<classname>CXRef::changeObject</classname> implementation.
</listitem>
<listitem><emphasis>easy</emphasis> mode doesn't do any kind of
checking. This is not very safe, but if class user knows what
he is doing (e. g. to correct destroyed objects).
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</para>
<para>
XRefWriter responsibility is to enable writing changes to the XRef's stream
to make them visible after all required changes are finished. To separate
from concrete implementation of storing, XRefWriter uses
<classname>IPdfWriter</classname>
abstract interface for object writing. Concrete implementation can be
set in runtime and <classname>OldStylePdfWriter</classname> is used by default. XRefWriter
is just responsible to provide with all changed objects which are
retrieved from lower (CXref) layer (mapping is protected).
</para>
<para>
Underlaying stream with data which is stored in <classname>XRef</classname> supertype is typed
as a <classname>Stream</classname> (see <xref linkend="general_xpdf_stream"/>.
<classname>IPdfWriter</classname> requires
<classname>StreamWriter</classname> (see <xref linkend="general_xpdf_changes"/>).
So XRefWriter uses <classname>StreamWriter</classname> implementator in constructor and
<classname>XRef</classname> use this stream when fetching objects and
<classname>IPdfWriter</classname> uses it when
writing content.
</para>
<para>
Finally XRefWriter keeps information needed for revision handling.
<footnote>
<para>
Each cross reference section and associated trailer is considered to
form revision. This means that each document has at least one revision
and all incremental update forms new revisions. The newest revision
is one at the end of the file.
</para>
</footnote>
XRefWriter keeps an array of all available revisions. Index stands
for revision number (0 is the newest one) and value is stream offset
of associated cross reference section start for revision. This is used
to get information about revision - for example to get revision size
(see <classname>XRefWriter::getRevisionSize</classname> method) - and to enable revision
changing. <classname>CXref</classname> implements
<programlisting>
void CXref::reopen(size_t xrefOff);
</programlisting>
method which is responsible for clear XRef state change to forget all
objects from current revision and to start parsing of cross reference
section from given position. This enables to (rather simply) change
current revision and so see documents in those state.
</para>
<para>
PDF format is prepared for such revisions and multi version documents
very well, but doesn't support any kind of branching which means that
changes can be done only for the newest revision. XRefWriter take in mind
also this aspect and so all methods take care of current revision.
This means that anytime current revision is not the newest one, changed
objects are ignored and everything is delegated directly to the lowest
layer. Also all methods producing changes throws
<classname>ReadOnlyDocumentException</classname>.
Even more all methods reimplemented by <classname>CXRef</classname> class, which depedns on
changes, are omited and directly <classname>XRef</classname> implementation is used instead.
</para>
</sect1>
|
