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
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (C) 2004 The Apache Software Foundation. All rights reserved. -->
<!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 API</title>
<p>This HOW-TO is organized in four sections. You should read them
sequentially because the later sections build upon the earlier ones.</p>
<ol>
<li>
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.
</li>
<li>
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.
</li>
<li>
The <link href="#sec3">third section</link> tells how to read
non-standard properties. Non-standard properties are application-specific
triples consisting of an ID, a type, and a value.
</li>
<li>
The <link href="#sec4">fourth section</link> tells you how to write
property set streams. Writing is still rudimentary in HPSF. You have to
understand the <link href="#sec3">third section</link> before you should
think about writing properties. Check the Javadoc API documentation to
find out about the details!
</li>
</ol>
<anchor id="sec1"/>
<section><title>Reading Standard Properties</title>
<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>
Open the document <em>\005SummaryInformation</em> located in the root
of the POI filesystem.
</li>
<li>
Create an instance of the class <code>SummaryInformation</code> from
that document.
</li>
<li>
Call the <code>SummaryInformation</code> instance's
<code>getTitle()</code> method.
</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</title>
<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>
<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</title>
<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>Instead of <em>\005SummaryInformation</em> use
<em>\005DocumentSummaryInformation</em> as the stream's name.</li>
<li>Replace all occurrences of the class
<code>SummaryInformation</code> by
<code>DocumentSummaryInformation</code>.</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>
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.
</dd>
<dt><code>UnexpectedPropertySetTypeException</code></dt>
<dd>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.</dd>
<dt><code>MarkUnsupportedException</code></dt>
<dd>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.</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</title>
<note>This section tells how to read non-standard properties. Non-standard
properties are application-specific ID/type/value triples.</note>
<section><title>Overview</title>
<p>Now comes the real hardcode stuff. As mentioned above,
<code>SummaryInformation</code> and
<code>DocumentSummaryInformation</code> are just special cases of the
general concept of a property set. This concept says that a
<strong>property set</strong> consists of properties and that each
<strong>property</strong> is an entity with an <strong>ID</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 one or more <strong>sections</strong>. Each section
holds a bunch of properties. But since that's still not complicated
enough, a section may have an optional <strong>dictionary</strong> that
maps property IDs to <strong>property names</strong> - we'll explain
later what that means.</p>
<p>The procedure to get to the properties is the following:</p>
<ol>
<li>Use the <strong><code>PropertySetFactory</code></strong> class to
create a <code>PropertySet</code> object from a property set stream. If
you don't know whether an input stream is a property set stream, just
try to call <code>PropertySetFactory.create(java.io.InputStream)</code>:
You'll either get a <code>PropertySet</code> instance returned or an
exception is thrown.</li>
<li>Call the <code>PropertySet</code>'s method <code>getSections()</code>
to get the sections contained in the property set. Each section is
an instance of the <code>Section</code> class.</li>
<li>Each section has a format ID. The format ID of the first section in a
property set determines the property set's type. For example, the first
(and only) section of the summary information property set has a format
ID of <code>F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9</code>. You can
get the format ID with <code>Section.getFormatID()</code>.</li>
<li>The properties contained in a <code>Section</code> can be retrieved
with <code>Section.getProperties()</code>. The result is an array of
<code>Property</code> instances.</li>
<li>A property has a name, a type, and a value. The <code>Property</code>
class has methods to retrieve them.</li>
</ol>
</section>
<section><title>A Sample Application</title>
<p>Let's have a look at a sample Java application that dumps all property
set streams contained in a POI file system. The full source code of this
program can be found as <em>ReadCustomPropertySets.java</em> in the
<em>examples</em> area of the POI source code tree. Here are the key
sections:</p>
<source>import java.io.*;
import java.util.*;
import org.apache.poi.hpsf.*;
import org.apache.poi.poifs.eventfilesystem.*;
import org.apache.poi.util.HexDump;</source>
<p>The most important package the application needs is
<code>org.apache.poi.hpsf.*</code>. This package contains the HPSF
classes. Most classes named below are from the HPSF package. Of course we
also need the POIFS event file system's classes and <code>java.io.*</code>
since we are dealing with POI I/O. From the <code>java.util</code> package
we use the <code>List</code> and <code>Iterator</code> class. The class
<code>org.apache.poi.util.HexDump</code> provides a methods to dump byte
arrays as nicely formatted strings.</p>
<source>public static void main(String[] args)
throws IOException
{
final String filename = args[0];
POIFSReader r = new POIFSReader();
/* Register a listener for *all* documents. */
r.registerListener(new MyPOIFSReaderListener());
r.read(new FileInputStream(filename));
}</source>
<p>The <code>POIFSReader</code> is set up in a way that the listener
<code>MyPOIFSReaderListener</code> is called on every file in the POI file
system.</p>
</section>
<section><title>The Property Set</title>
<p>The listener class tries to create a <code>PropertySet</code> from each
stream using the <code>PropertySetFactory.create()</code> method:</p>
<source>static class MyPOIFSReaderListener implements POIFSReaderListener
{
public void processPOIFSReaderEvent(POIFSReaderEvent event)
{
PropertySet ps = null;
try
{
ps = PropertySetFactory.create(event.getStream());
}
catch (NoPropertySetStreamException ex)
{
out("No property set stream: \"" + event.getPath() +
event.getName() + "\"");
return;
}
catch (Exception ex)
{
throw new RuntimeException
("Property set stream \"" +
event.getPath() + event.getName() + "\": " + ex);
}
/* Print the name of the property set stream: */
out("Property set stream \"" + event.getPath() +
event.getName() + "\":");</source>
<p>Creating the <code>PropertySet</code> is done in a <code>try</code>
block, because not each stream in the POI file system contains a property
set. If it is some other file, the
<code>PropertySetFactory.create()</code> throws a
<code>NoPropertySetStreamException</code>, which is caught and
logged. Then the program continues with the next stream. However, all
other types of exceptions cause the program to terminate by throwing a
runtime exception. If all went well, we can print the name of the property
set stream.</p>
</section>
<section><title>The Sections</title>
<p>The next step is to print the number of sections followed by the
sections themselves:</p>
<source>/* Print the number of sections: */
final long sectionCount = ps.getSectionCount();
out(" No. of sections: " + sectionCount);
/* Print the list of sections: */
List sections = ps.getSections();
int nr = 0;
for (Iterator i = sections.iterator(); i.hasNext();)
{
/* Print a single section: */
Section sec = (Section) i.next();
// See below for the complete loop body.
}</source>
<p>The <code>PropertySet</code>'s method <code>getSectionCount()</code>
returns the number of sections.</p>
<p>To retrieve the sections, use the <code>getSections()</code>
method. This method returns a <code>java.util.List</code> containing
instances of the <code>Section</code> class in their proper order.</p>
<p>The sample code shows a loop that retrieves the <code>Section</code>
objects one by one and prints some information about each one. Here is
the complete body of the loop:</p>
<source>/* Print a single section: */
Section sec = (Section) i.next();
out(" Section " + nr++ + ":");
String s = hex(sec.getFormatID().getBytes());
s = s.substring(0, s.length() - 1);
out(" Format ID: " + s);
/* Print the number of properties in this section. */
int propertyCount = sec.getPropertyCount();
out(" No. of properties: " + propertyCount);
/* Print the properties: */
Property[] properties = sec.getProperties();
for (int i2 = 0; i2 < properties.length; i2++)
{
/* Print a single property: */
Property p = properties[i2];
int id = p.getID();
long type = p.getType();
Object value = p.getValue();
out(" Property ID: " + id + ", type: " + type +
", value: " + value);
}</source>
</section>
<section><title>The Section's Format ID</title>
<p>The first method called on the <code>Section</code> instance is
<code>getFormatID()</code>. As explained above, the format ID of the
first section in a property set determines the type of the property
set. Its type is <code>ClassID</code> which is essentially a sequence of
16 bytes. A real application using its own type of a custom property set
should have defined a unique format ID and, when reading a property set
stream, should check the format ID is equal to that unique format ID. The
sample program just prints the format ID it finds in a section:</p>
<source>String s = hex(sec.getFormatID().getBytes());
s = s.substring(0, s.length() - 1);
out(" Format ID: " + s);</source>
<p>As you can see, the <code>getFormatID()</code> method returns a
<code>ClassID</code> object. An array containing the bytes can be
retrieved with <code>ClassID.getBytes()</code>. In order to get a nicely
formatted printout, the sample program uses the <code>hex()</code> helper
method which in turn uses the POI utility class <code>HexDump</code> in
the <code>org.apache.poi.util</code> package. Another helper method is
<code>out()</code> which just saves typing
<code>System.out.println()</code>.</p>
</section>
<section><title>The Properties</title>
<p>Before getting the properties, it is possible to find out how many
properties are available in the section via the
<code>Section.getPropertyCount()</code>. The sample application uses this
method to print the number of properties to the standard output:</p>
<source>int propertyCount = sec.getPropertyCount();
out(" No. of properties: " + propertyCount);</source>
<p>Now its time to get to the properties themselves. You can retrieve a
section's properties with the method
<code>Section.getProperties()</code>:</p>
<source>Property[] properties = sec.getProperties();</source>
<p>As you can see the result is an array of <code>Property</code>
objects. This class has three methods to retrieve a property's ID, its
type, and its value. The following code snippet shows how to call
them:</p>
<source>for (int i2 = 0; i2 < properties.length; i2++)
{
/* Print a single property: */
Property p = properties[i2];
int id = p.getID();
long type = p.getType();
Object value = p.getValue();
out(" Property ID: " + id + ", type: " + type +
", value: " + value);
}</source>
</section>
<section><title>Sample Output</title>
<p>The output of the sample program might look like the following. It
shows the summary information and the document summary information
property sets of a Microsoft Word document. However, unlike the first and
second section of this HOW-TO the application does not have any code
which is specific to the <code>SummaryInformation</code> and
<code>DocumentSummaryInformation</code> classes.</p>
<source>Property set stream "/SummaryInformation":
No. of sections: 1
Section 0:
Format ID: 00000000 F2 9F 85 E0 4F F9 10 68 AB 91 08 00 2B 27 B3 D9 ....O..h....+'..
No. of properties: 17
Property ID: 1, type: 2, value: 1252
Property ID: 2, type: 30, value: Titel
Property ID: 3, type: 30, value: Thema
Property ID: 4, type: 30, value: Rainer Klute (Autor)
Property ID: 5, type: 30, value: Test (Stichw�rter)
Property ID: 6, type: 30, value: This is a document for testing HPSF
Property ID: 7, type: 30, value: Normal.dot
Property ID: 8, type: 30, value: Unknown User
Property ID: 9, type: 30, value: 3
Property ID: 18, type: 30, value: Microsoft Word 9.0
Property ID: 12, type: 64, value: Mon Jan 01 00:59:25 CET 1601
Property ID: 13, type: 64, value: Thu Jul 18 16:22:00 CEST 2002
Property ID: 14, type: 3, value: 1
Property ID: 15, type: 3, value: 20
Property ID: 16, type: 3, value: 93
Property ID: 19, type: 3, value: 0
Property ID: 17, type: 71, value: [B@13582d
Property set stream "/DocumentSummaryInformation":
No. of sections: 2
Section 0:
Format ID: 00000000 D5 CD D5 02 2E 9C 10 1B 93 97 08 00 2B 2C F9 AE ............+,..
No. of properties: 14
Property ID: 1, type: 2, value: 1252
Property ID: 2, type: 30, value: Test
Property ID: 14, type: 30, value: Rainer Klute (Manager)
Property ID: 15, type: 30, value: Rainer Klute IT-Consulting GmbH
Property ID: 5, type: 3, value: 3
Property ID: 6, type: 3, value: 2
Property ID: 17, type: 3, value: 111
Property ID: 23, type: 3, value: 592636
Property ID: 11, type: 11, value: false
Property ID: 16, type: 11, value: false
Property ID: 19, type: 11, value: false
Property ID: 22, type: 11, value: false
Property ID: 13, type: 4126, value: [B@56a499
Property ID: 12, type: 4108, value: [B@506411
Section 1:
Format ID: 00000000 D5 CD D5 05 2E 9C 10 1B 93 97 08 00 2B 2C F9 AE ............+,..
No. of properties: 7
Property ID: 0, type: 0, value: {6=Test-JaNein, 5=Test-Zahl, 4=Test-Datum, 3=Test-Text, 2=_PID_LINKBASE}
Property ID: 1, type: 2, value: 1252
Property ID: 2, type: 65, value: [B@c9ba38
Property ID: 3, type: 30, value: This is some text.
Property ID: 4, type: 64, value: Wed Jul 17 00:00:00 CEST 2002
Property ID: 5, type: 3, value: 27
Property ID: 6, type: 11, value: true
No property set stream: "/WordDocument"
No property set stream: "/CompObj"
No property set stream: "/1Table"</source>
<p>There are some interesting items to note:</p>
<ul>
<li>The first property set (summary information) consists of a single
section, the second property set (document summary information) consists
of two sections.</li>
<li>Each section type (identified by its format ID) has its own domain of
property ID. For example, in the second property set the properties with
ID 2 have different meanings in the two section. By the way, the format
IDs of these sections are <strong>not</strong> equal, but you have to
look hard to find the difference.</li>
<li>The properties are not in any particular order in the section,
although they slightly tend to be sorted by their IDs.</li>
</ul>
</section>
<section><title>Property IDs</title>
<p>Properties in the same section are distinguished by their IDs. This is
similar to variables in a programming language like Java, which are
distinguished by their names. But unlike variable names, property IDs are
simple integral numbers. There is another similarity, however. Just like
a Java variable has a certain scope (e.g. a member variables in a class),
a property ID also has its scope of validity: the section.</p>
<p>Two property IDs in sections with different section format IDs
don't have the same meaning even though their IDs might be equal. For
example, ID 4 in the first (and only) section of a summary
information property set denotes the document's author, while ID 4 in the
first section of the document summary information property set means the
document's byte count. The sample output above does not show a property
with an ID of 4 in the first section of the document summary information
property set. That means that the document does not have a byte
count. However, there is a property with an ID of 4 in the
<em>second</em> section: This is a user-defined property ID - we'll get
to that topic in a minute.</p>
<p>So, how can you find out what the meaning of a certain property ID in
the summary information and the document summary information property set
is? The standard property sets as such don't have any hints about the
<strong>meanings of their property IDs</strong>. For example, the summary
information property set does not tell you that the property ID 4 stands
for the document's author. This is external knowledge. Microsoft defined
standard meanings for some of the property IDs in the summary information
and the document summary information property sets. As a help to the Java
and POI programmer, the class <code>PropertyIDMap</code> in the
<code>org.apache.poi.hpsf.wellknown</code> package defines constants
for the "well-known" property IDs. For example, there is the
definition</p>
<source>public final static int PID_AUTHOR = 4;</source>
<p>These definitions allow you to use symbolic names instead of
numbers.</p>
<p>In order to provide support for the other way, too, - i.e. to map
property IDs to property names - the class <code>PropertyIDMap</code>
defines two static methods:
<code>getSummaryInformationProperties()</code> and
<code>getDocumentSummaryInformationProperties()</code>. Both return
<code>java.util.Map</code> objects which map property IDs to
strings. Such a string gives a hint about the property's meaning. For
example,
<code>PropertyIDMap.getSummaryInformationProperties().get(4)</code>
returns the string "PID_AUTHOR". An application could use this string as
a key to a localized string which is displayed to the user, e.g. "Author"
in English or "Verfasser" in German. HPSF might provide such
language-dependend ("localized") mappings in a later release.</p>
<p>Usually you won't have to deal with those two maps. Instead you should
call the <code>Section.getPIDString(int)</code> method. It returns the
string associated with the specified property ID in the context of the
<code>Section</code> object.</p>
<p>Above you learned that property IDs have a meaning in the scope of a
section only. However, there are two exceptions to the rule: The property
IDs 0 and 1 have a fixed meaning in <strong>all</strong> sections:</p>
<table>
<tr>
<th>Property ID</th>
<th>Meaning</th>
</tr>
<tr>
<td>0</td>
<td>The property's value is a <strong>dictionary</strong>, i.e. a
mapping from property IDs to strings.</td>
</tr>
<tr>
<td>1</td>
<td>The property's value is the number of a <strong>codepage</strong>,
i.e. a mapping from character codes to characters. All strings in the
section containing this property must be interpreted using this
codepage. Typical property values are 1252 (8-bit "western" characters,
ISO-8859-1), 1200 (16-bit Unicode characters, UFT-16), or 65001 (8-bit
Unicode characters, UFT-8).</td>
</tr>
</table>
</section>
<section><title>Property types</title>
<p>A property is nothing without its value. It is stored in a property set
stream as a sequence of bytes. You must know the property's
<strong>type</strong> in order to properly interpret those bytes and
reasonably handle the value. A property's type is one of the so-called
Microsoft-defined <strong>"variant types"</strong>. When you call
<code>Property.getType()</code> you'll get a <code>long</code> value
which denoting the property's variant type. The class
<code>Variant</code> in the <code>org.apache.poi.hpsf</code> package
holds most of those <code>long</code> values as named constants. For
example, the constant <code>VT_I4 = 3</code> means a signed integer value
of four bytes. Examples of other types are <code>VT_LPSTR = 30</code>
meaning a null-terminated string of 8-bit characters, <code>VT_LPWSTR =
31</code> which means a null-terminated Unicode string, or <code>VT_BOOL
= 11</code> denoting a boolean value.</p>
<p>In most cases you won't need a property's type because HPSF does all
the work for you.</p>
</section>
<section><title>Property values</title>
<p>When an application wants to retrieve a property's value and calls
<code>Property.getValue()</code>, HPSF has to interpret the bytes making
out the value according to the property's type. The type determines how
many bytes the value consists of and what
to do with them. For example, if the type is <code>VT_I4</code>, HPSF
knows that the value is four bytes long and that these bytes
comprise a signed integer value in the little-endian format. This is
quite different from e.g. a type of <code>VT_LPWSTR</code>. In this case
HPSF has to scan the value bytes for a Unicode null character and collect
everything from the beginning to that null character as a Unicode
string.</p>
<p>The good new is that HPSF does another job for you, too: It maps the
variant type to an adequate Java type.</p>
<table>
<tr>
<th>Variant type:</th>
<th>Java type:</th>
</tr>
<tr>
<td>VT_I2</td>
<td>java.lang.Integer</td>
</tr>
<tr>
<td>VT_I4</td>
<td>java.lang.Long</td>
</tr>
<tr>
<td>VT_FILETIME</td>
<td>java.util.Date</td>
</tr>
<tr>
<td>VT_LPSTR</td>
<td>java.lang.String</td>
</tr>
<tr>
<td>VT_LPWSTR</td>
<td>java.lang.String</td>
</tr>
<tr>
<td>VT_CF</td>
<td>byte[]</td>
</tr>
<tr>
<td>VT_BOOL</td>
<td>java.lang.Boolean</td>
</tr>
</table>
<p>The bad news is that there are still a couple of variant types HPSF
does not yet support. If it encounters one of these types it
returns the property's value as a byte array and leaves it to be
interpreted by the application.</p>
<p>An application retrieves a property's value by calling the
<code>Property.getValue()</code> method. This method's return type is the
abstract <code>Object</code> class. The <code>getValue()</code> method
looks up the property's variant type, reads the property's value bytes,
creates an instance of an adequate Java type, assigns it the property's
value and returns it. Primitive types like <code>int</code> or
<code>long</code> will be returned as the corresponding class,
e.g. <code>Integer</code> or <code>Long</code>.</p>
</section>
<section><title>Dictionaries</title>
<p>The property with ID 0 has a very special meaning: It is a
<strong>dictionary</strong> mapping property IDs to property names. We
have seen already that the meanings of standard properties in the
summary information and the document summary information property sets
have been defined by Microsoft. The advantage is that the labels of
properties like "Author" or "Title" don't have to be stored in the
property set. However, a user can define custom fields in, say, Microsoft
Word. For each field the user has to specify a name, a type, and a
value.</p>
<p>The names of the custom-defined fields (i.e. the property names) are
stored in the document summary information second section's
<strong>dictionary</strong>. The dictionary is a map which associates
property IDs with property names.</p>
<p>The method <code>Section.getPIDString(int)</code> not only returns with
the well-known property names of the summary information and document
summary information property sets, but with self-defined properties,
too. It should also work with self-defined properties in self-defined
sections.</p>
</section>
<section><title>Codepage support</title>
<p>The property with ID 1 holds the number of the codepage which was used
to encode the strings in this section. If this property is not available
in a section, the platform's default character encoding will be
used. This works fine as long as the document being read has been written
on a platform with the same default character encoding. However, if you
receive a document from another region of the world and the codepage is
undefined, you are in trouble.</p>
<p>HPSF's codepage support is as good as the character encoding support of
the Java Virtual Machine (JVM) the application runs on. If HPSF
encounters a codepage number it assumes that the JVM has a character
encoding with a corresponding name. For example, if the codepage is 1252,
HPSF uses the character encoding "cp1252" to read or write strings. If
the JVM does not have that character encoding installed or if the
codepage number is illegal, an UnsupportedEncodingException will be
thrown.</p>
<p>There are two exceptions to the rule that a character encoding's name
is derived from the codepage number by prepending the string "cp" to
it:</p>
<dl>
<dt>Codepage 1200</dt>
<dd>is mapped to the character encoding "UTF-16".</dd>
<dt>Codepage 65001</dt>
<dd>is mapped to the character encoding "UTF-8".</dd>
</dl>
</section>
</section>
<anchor id="sec4"/>
<section><title>Writing Properties</title>
<note>This section describes how to write properties.</note>
<section><title>Overview of Writing Properties</title>
<p>Writing properties is possible at a low level only at the moment. You
have to deal with property IDs and variant types to write
properties. There are no convenience classes or convenience methods for
dealing with summary information and document summary information streams
yet. Therefore you should have read <link href="#sec3">section 3</link>
to understand what follows in this section.</p>
<p>HPSF's writing capabilities come with the classes
<code>MutablePropertySet</code>, <code>MutableSection</code>,
<code>MutableProperty</code>, and some helper classes. The "mutable"
classes extend their respective superclasses <code>PropertySet</code>,
<code>Section</code>, and <code>Property</code> and provide "set" and
"write" methods.</p>
<p>When you are going to write a property set stream your application has
to perform the following steps:</p>
<ol>
<li>Create a <code>MutablePropertySet</code> instance.</li>
<li>Get hold of a <code>MutableSection</code>. You can either retrieve
the one that is always present in a new <code>MutablePropertySet</code>,
or you have to create a new <code>MutableSection</code> and add it to
the <code>MutablePropertySet</code>.
</li>
<li>Set any <code>Section</code> fields as you like.</li>
<li>Create as many <code>MutableProperty</code> objects as you need. Set
each property's ID, type, and value. Add the
<code>MutableProperty</code> objects to the
<code>MutableSection</code>.
</li>
<li>Create further <code>MutableSection</code>s if you need them.</li>
<li>Eventually retrieve the property set as a byte stream using
<code>MutablePropertySet.toInputStream()</code> and write it to a POIFS
document.</li>
</ol>
</section>
<section><title>Low-level Writing Functions In Details</title>
<p>Writing properties is introduced by an artificial but simple example: a
program creating a new document (aka POI file system) which contains only
a single document: a summary information property set stream. The latter
will hold the document's title only. This is artificial in that it does
not contain any Word, Excel or other kind of useful application document
data. A document containing just a property set is without any practical
use. However, it is perfectly fine for an example because it make it very
simple and easy to understand, and you will get used to writing
properties in real applications quickly.</p>
<p>The application expects the name of the POI file system to be written
on the command line. The title property it writes is "Sample title".</p>
<p>Here's the application's source code. You can also find it in the
"examples" section of the POI source code distribution. Explanations are
following below.</p>
<source>package org.apache.poi.hpsf.examples;
import java.io.*;
import org.apache.poi.hpsf.*;
import org.apache.poi.hpsf.wellknown.*;
import org.apache.poi.poifs.filesystem.*;
public class WriteTitle
{
public static void main(final String[] args)
throws WritingNotSupportedException, IOException
{
/* Check whether we have exactly one command-line argument. */
if (args.length != 1)
{
System.err.println("Usage: " + WriteTitle.class.getName() +
"destinationPOIFS");
System.exit(1);
}
final String fileName = args[0];
final POIFSFileSystem poiFs = new POIFSFileSystem();
/* Create a mutable property set. Initially it contains a single section
* with no properties. */
final MutablePropertySet mps = new MutablePropertySet();
/* Retrieve the section the property set already contains. */
final MutableSection ms = (MutableSection) mps.getSections().get(0);
/* Turn the property set into a summary information property. This is
* done by setting the format ID of its first section to
* SectionIDMap.SUMMARY_INFORMATION_ID. */
ms.setFormatID(SectionIDMap.SUMMARY_INFORMATION_ID);
/* Create an empty property. */
final MutableProperty p = new MutableProperty();
/* Fill the property with appropriate settings so that it specifies the
* document's title. */
p.setID(PropertyIDMap.PID_TITLE);
p.setType(Variant.VT_LPWSTR);
p.setValue("Sample title");
/* For writing the property set into a POI file system it has to be
* handed over to the POIFS.createDocument() method as an input stream
* which produces the bytes making out the property set stream. */
final InputStream is = mps.toInputStream();
/* Create the summary information property set in the POI file
* system. It is given the default name most (if not all) summary
* information property sets have. */
poiFs.createDocument(is, SummaryInformation.DEFAULT_STREAM_NAME);
/* Write the whole POI file system to a disk file. */
poiFs.writeFilesystem(new FileOutputStream(fileName));
}
}</source>
<p>The applications first checks that there is exactly a single argument
on the command line. If this is true, the application stores it in the
<code>fileName</code> variable. It will be used in the end when the POI
file system is written to a disk file.</p>
<source>if (args.length != 1)
{
System.err.println("Usage: " + WriteTitle.class.getName() +
"destinationPOIFS");
System.exit(1);
}
final String fileName = args[0];</source>
<p>Let's create a property set now. We cannot use the
<code>PropertySet</code> class, because it is read-only. It does not have
a constructor creating an empty property set, and it does not have any
methods to modify its contents, i.e. to write sections containing
properties into it.</p>
<p>The class to use is <code>MutablePropertySet</code>. It is a subclass
of <code>PropertySet</code>. The sample application calls its no-args
constructor in order to establish an empty property set:</p>
<source>final MutablePropertySet mps = new MutablePropertySet();</source>
<p>As said, we have an empty property set now. Later we will put some
contents into it.</p>
<p>By the way, the <code>MutablePropertySet</code> class has another
constructor taking a <code>PropertySet</code> as parameter. It creates a
mutable deep copy of the property set given to it.</p>
<p>The <code>MutablePropertySet</code> created by the no-args constructor
is not really empty: It contains a single section without properties. We
can either retrieve that section and fill it with properties or we can
replace it by another section. We can also add further sections to the
property set. The sample application decides to retrieve the section
being already there:</p>
<source>final MutableSection ms = (MutableSection) mps.getSections().get(0);</source>
<p>The <code>getSections()</code> method returns the property set's
sections as a list, i.e. an instance of
<code>java.util.List</code>. Calling <code>get(0)</code> returns the
list's first (or zeroth, if you prefer) element. The <code>Section</code>
returned is a <code>MutableSection</code>: a subclass of
<code>Section</code> you can modify.</p>
<p>The alternative to retrieving the <code>MutableSection</code> being
already there would have been to create an new
<code>MutableSection</code> like this:</p>
<source>MutableSection s = new MutableSection();</source>
<p>There is also a constructor which takes a <code>Section</code> as
parameter and creates a mutable deep copy of it.</p>
<p>The <code>MutableSection</code> the sample application retrieved from
the <code>MutablePropertySet</code> is still empty. It contains no
properties and does not have a format ID. As you have read <link
href="#sec3">above</link> the format ID of the first section in a
property set determines the property set's type. Since our property set
should become a SummaryInformation property set we have to set the format
ID of its first (and only) section to
<code>F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9</code>. However, you
won't have to remember that ID: HPSF has it defined as the well-known
constant <code>SectionIDMap.SUMMARY_INFORMATION_ID</code>. The sample
application writes it to the section using the
<code>setFormatID(byte[])</code> method:</p>
<source>ms.setFormatID(SectionIDMap.SUMMARY_INFORMATION_ID);</source>
<p>Now it is time to create a property. As you might expect there is a
subclass of <code>Property</code> called
<code>MutableProperty</code> with a no-args constructor:</p>
<source>final MutableProperty p = new MutableProperty();</source>
<p>A <code>MutableProperty</code> object must have an ID, a type, and a
value (see <link href="#sec3">above</link> for details). The class
provides methods to set these attributes:</p>
<source>p.setID(PropertyIDMap.PID_TITLE);
p.setType(Variant.VT_LPWSTR);
p.setValue("Sample title");</source>
<p>The <code>MutableProperty</code> class has a constructor which you can
use to pass in all three attributes in a single call. See the Javadoc API
documentation for details!</p>
<p>The sample property set is complete now. We have a
<code>MutablePropertySet</code> containing a <code>MutableSection</code>
containing a <code>MutableProperty</code>. Of course we could have added
more sections to the property set and more properties to the sections but
we wanted to keep things simple.</p>
<p>The property set has to be written to a POI file system. The following
statement creates it.</p>
<source>final POIFSFileSystem poiFs = new POIFSFileSystem();</source>
<p>Writing the property set includes the step of converting it into a
sequence of bytes. The <code>MutablePropertySet</code> class has the
method <code>toInputStream()</code> for this purpose. It returns the
bytes making out the property set stream as an
<code>InputStream</code>:</p>
<source>final InputStream is = mps.toInputStream();</source>
<p>If you'd read from this input stream you'd receive all the property
set's bytes. However, it is very likely that you'll never do
that. Instead you'll pass the input stream to the
<code>POIFSFileSystem.createDocument()</code> method, like this:</p>
<source>poiFs.createDocument(is, SummaryInformation.DEFAULT_STREAM_NAME);</source>
<p>Besides the <code>InputStream</code> <code>createDocument()</code>
takes a second parameter: the name of the document to be created. For a
SummaryInformation property set stream the default name is available as
the constant <code>SummaryInformation.DEFAULT_STREAM_NAME</code>.</p>
<p>The last step is to write the POI file system to a disk file:</p>
<source>poiFs.writeFilesystem(new FileOutputStream(fileName));</source>
</section>
</section>
<section><title>Further Reading</title>
<p>There are still some aspects of HSPF left which are not covered by this
HOW-TO. You should dig into the Javadoc API documentation to learn
further details. Since you've struggled through this document up to this
point, you are well prepared.</p>
</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:
-->
|
