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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"../dtd/document-v11.dtd">
<!-- $Id$ -->
<document>
<header>
<title>HPSF HOW-TO</title>
<authors>
<person name="Rainer Klute" email="klute@apache.org"/>
</authors>
</header>
<body>
<section title="How To Use the HPSF APIs">
<p>This HOW-TO is organized in three sections. You should read them
sequentially because the later sections build upon the earlier ones.</p>
<ol>
<li>
<p>The <link href="#sec1">first section</link> explains how to read
the most important standard properties of a Microsoft Office
document. Standard properties are things like title, author, creation
date etc. It is quite likely that you will find here what you need and
don't have to read the other sections.</p>
</li>
<li>
<p>The <link href="#sec2">second section</link> goes a small step
further and focusses on reading additional standard properties. It also
talks about exceptions that may be thrown when dealing with HPSF and
shows how you can read properties of embedded objects.</p>
</li>
<li>
<p>The <link href="#sec3">third section</link> tells how to read
non-standard properties. Non-standard properties are application-specific
name/value/type triples. <em>This section is still to be written. Look up
the API documentation for the time being!</em></p>
</li>
</ol>
<anchor id="sec1"/>
<section title="Reading Standard Properties">
<note>This section explains how to read
the most important standard properties of a Microsoft Office
document. Standard properties are things like title, author, creation
date etc. Chances are that you will find here what you need and
don't have to read the other sections.</note>
<p>The first thing you should understand is that properties are stored in
separate documents inside the POI filesystem. (If you don't know what a
POI filesystem is, read the <link href="../poifs/index.html">POIFS
documentation</link>.) A document in a POI filesystem is also called a
<strong>stream</strong>.</p>
<p>The following example shows how to read a POI filesystem's
"title" property. Reading other properties is similar. Consider the API
documentation of <code>org.apache.poi.hpsf.SummaryInformation</code> to
learn which methods are available!</p>
<p>The standard properties this section focusses on can be found in a
document called <em>\005SummaryInformation</em> located in the root of the
POI filesystem. The notation <em>\005</em> in the document's name means
the character with the decimal value of 5. In order to read the title, an
application has to perform the following steps:</p>
<ol>
<li>
<p>Open the document <em>\005SummaryInformation</em> located in the root
of the POI filesystem.</p>
</li>
<li>
<p>Create an instance of the class <code>SummaryInformation</code> from
that document.</p>
</li>
<li>
<p>Call the <code>SummaryInformation</code> instance's
<code>getTitle()</code> method.</p>
</li>
</ol>
<p>Sounds easy, doesn't it? Here are the steps in detail.</p>
<section title="Open the document \005SummaryInformation in the root of the
POI filesystem">
<p>An application that wants to open a document in a POI filesystem
(POIFS) proceeds as shown by the following code fragment. (The full
source code of the sample application is available in the
<em>examples</em> section of the POI source tree as
<em>ReadTitle.java</em>.</p>
<fixme>I just found out that <em>ReadTitle.java</em> is no longer there! I
shall look it up in the CVS and try to restore it.</fixme>
<source>
import java.io.*;
import org.apache.poi.hpsf.*;
import org.apache.poi.poifs.eventfilesystem.*;
// ...
public static void main(String[] args)
throws IOException
{
final String filename = args[0];
POIFSReader r = new POIFSReader();
r.registerListener(new MyPOIFSReaderListener(),
"\005SummaryInformation");
r.read(new FileInputStream(filename));
}</source>
<p>The first interesting statement is</p>
<source>POIFSReader r = new POIFSReader();</source>
<p>It creates a
<code>org.apache.poi.poifs.eventfilesystem.POIFSReader</code> instance
which we shall need to read the POI filesystem. Before the application
actually opens the POI filesystem we have to tell the
<code>POIFSReader</code> which documents we are interested in. In this
case the application should do something with the document
<em>\005SummaryInformation</em>.</p>
<source>
r.registerListener(new MyPOIFSReaderListener(),
"\005SummaryInformation");</source>
<p>This method call registers a
<code>org.apache.poi.poifs.eventfilesystem.POIFSReaderListener</code>
with the <code>POIFSReader</code>. The <code>POIFSReaderListener</code>
interface specifies the method <code>processPOIFSReaderEvent</code>
which processes a document. The class
<code>MyPOIFSReaderListener</code> implements the
<code>POIFSReaderListener</code> and thus the
<code>processPOIFSReaderEvent</code> method. The eventing POI filesystem
calls this method when it finds the <em>\005SummaryInformation</em>
document. In the sample application <code>MyPOIFSReaderListener</code> is
a static class in the <em>ReadTitle.java</em> source file.</p>
<p>Now everything is prepared and reading the POI filesystem can
start:</p>
<source>r.read(new FileInputStream(filename));</source>
<p>The following source code fragment shows the
<code>MyPOIFSReaderListener</code> class and how it retrieves the
title.</p>
<source>
static class MyPOIFSReaderListener implements POIFSReaderListener
{
public void processPOIFSReaderEvent(POIFSReaderEvent event)
{
SummaryInformation si = null;
try
{
si = (SummaryInformation)
PropertySetFactory.create(event.getStream());
}
catch (Exception ex)
{
throw new RuntimeException
("Property set stream \"" +
event.getPath() + event.getName() + "\": " + ex);
}
final String title = si.getTitle();
if (title != null)
System.out.println("Title: \"" + title + "\"");
else
System.out.println("Document has no title.");
}
}
</source>
<p>The line</p>
<source>SummaryInformation si = null;</source>
<p>declares a <code>SummaryInformation</code> variable and initializes it
with <code>null</code>. We need an instance of this class to access the
title. The instance is created in a <code>try</code> block:</p>
<source>si = (SummaryInformation)
PropertySetFactory.create(event.getStream());</source>
<p>The expression <code>event.getStream()</code> returns the input stream
containing the bytes of the property set stream named
<em>\005SummaryInformation</em>. This stream is passed into the
<code>create</code> method of the factory class
<code>org.apache.poi.hpsf.PropertySetFactory</code> which returns
a <code>org.apache.poi.hpsf.PropertySet</code> instance. It is more or
less safe to cast this result to <code>SummaryInformation</code>, a
convenience class with methods like <code>getTitle()</code>,
<code>getAuthor()</code> etc.</p>
<p>The <code>PropertySetFactory.create</code> method may throw all sorts
of exceptions. We'll deal with them in the next sections. For now we just
catch all exceptions and throw a <code>RuntimeException</code>
containing the message text of the origin exception.</p>
<p>If all goes well, the sample application retrieves the title and prints
it to the standard output. As you can see you must be prepared for the
case that the POI filesystem does not have a title.</p>
<source>final String title = si.getTitle();
if (title != null)
System.out.println("Title: \"" + title + "\"");
else
System.out.println("Document has no title.");</source>
<p>Please note that a Microsoft Office document does not necessarily
contain the <em>\005SummaryInformation</em> stream. The documents created
by the Microsoft Office suite have one, as far as I know. However, an
Excel spreadsheet exported from StarOffice 5.2 won't have a
<em>\005SummaryInformation</em> stream. In this case the applications
won't throw an exception but simply does not call the
<code>processPOIFSReaderEvent</code> method. You have been warned!</p>
</section>
</section>
<anchor id="sec2"/>
<section title="Additional Standard Properties, Exceptions And Embedded Objects">
<note>This section focusses on reading additional standard properties. It
also talks about exceptions that may be thrown when dealing with HPSF and
shows how you can read properties of embedded objects.</note>
<p>A couple of <strong>additional standard properties</strong> are not
contained in the <em>\005SummaryInformation</em> stream explained above,
for example a document's category or the number of multimedia clips in a
PowerPoint presentation. Microsoft has invented an additional stream named
<em>\005DocumentSummaryInformation</em> to hold these properties. With two
minor exceptions you can proceed exactly as described above to read the
properties stored in <em>\005DocumentSummaryInformation</em>:</p>
<ul>
<li><p>Instead of <em>\005SummaryInformation</em> use
<em>\005DocumentSummaryInformation</em> as the stream's name.</p></li>
<li><p>Replace all occurrences of the class
<code>SummaryInformation</code> by
<code>DocumentSummaryInformation</code>.</p></li>
</ul>
<p>And of course you cannot call <code>getTitle()</code> because
<code>DocumentSummaryInformation</code> has different query methods. See
the Javadoc API documentation for the details!</p>
<p>In the previous section the application simply caught all
<strong>exceptions</strong> and was in no way interested in any
details. However, a real application will likely want to know what went
wrong and act appropriately. Besides any IO exceptions there are three
HPSF resp. POI specific exceptions you should know about:</p>
<dl>
<dt><code>NoPropertySetStreamException</code>:</dt>
<dd>
<p>This exception is thrown if the application tries to create a
<code>PropertySet</code> instance from a stream that is not a
property set stream. (<code>SummaryInformation</code> and
<code>DocumentSummaryInformation</code> are subclasses of
<code>PropertySet</code>.) A faulty property set stream counts as not
being a property set stream at all. An application should be prepared to
deal with this case even if it opens streams named
<em>\005SummaryInformation</em> or
<em>\005DocumentSummaryInformation</em> only. These are just names. A
stream's name by itself does not ensure that the stream contains the
expected contents and that this contents is correct.</p>
</dd>
<dt><code>UnexpectedPropertySetTypeException</code></dt>
<dd><p>This exception is thrown if a certain type of property set is
expected somewhere (e.g. a <code>SummaryInformation</code> or
<code>DocumentSummaryInformation</code>) but the provided property
set is not of that type.</p></dd>
<dt><code>MarkUnsupportedException</code></dt>
<dd><p>This exception is thrown if an input stream that is to be parsed
into a property set does not support the
<code>InputStream.mark(int)</code> operation. The POI filesystem uses
the <code>DocumentInputStream</code> class which does support this
operation, so you are safe here. However, if you read a property set
stream from another kind of input stream things may be
different.</p></dd>
</dl>
<p>Many Microsoft Office documents contain <strong>embedded
objects</strong>, for example an Excel sheet on a page in a Word
document. Embedded objects may have property sets of their own. An
application can open these property set streams as described above. The
only difference is that they are not located in the POI filesystem's root
but in a <strong>nested directory</strong> instead. Just register a
<code>POIFSReaderListener</code> for the property set streams you are
interested in. For example, the <em>POIBrowser</em> application in the
contrib section tries to open each and every document in a POI filesystem
as a property set stream. If this operation was successful it displays the
properties.</p>
</section>
<anchor id="sec3"/>
<section title="Reading Non-Standard Properties">
<note>This section tells how to read non-standard properties. Non-standard
properties are application-specific name/type/value triples.</note>
<p>Now comes the really hardcode stuff. As mentioned above,
<code>SummaryInformation</code> and
<code>DocumentSummaryInformation</code> are just special cases of the
general concept of a property set. The general concept says that a
property set consists of <strong>properties</strong>. Each property is an
entity that has a <strong>name</strong>, a <strong>type</strong>, and a
<strong>value</strong>.</p>
<p>Okay, that was still rather easy. However, to make things more
complicated Microsoft in its infinite wisdom decided that a property set
shalt be broken into <strong>sections</strong>. Each section holds a bunch
of properties. But since that's still not complicated enough: a section
can optionally have a dictionary that maps property IDs to property
names - we'll explain later what that means.</p>
<note>[To be continued.]</note>
<fixme>Let's consider a Java application that wants to read a stream
containing a general property set. It is modelled by the class
<code>PropertySet</code> in the <code>org.apache.poi.hpsf</code>
package.</fixme>
</section>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
|
