From 59a0fb6b4e513115c9245b1922055a8fe87b0007 Mon Sep 17 00:00:00 2001 From: Rainer Klute Date: Tue, 16 Sep 2003 15:58:30 +0000 Subject: [PATCH] HPSF writing property sets documentation completed. git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353353 13f79535-47bb-0310-9956-ffa450edef68 --- .../content/xdocs/hpsf/how-to.xml | 126 +++++++++++------- 1 file changed, 75 insertions(+), 51 deletions(-) diff --git a/src/documentation/content/xdocs/hpsf/how-to.xml b/src/documentation/content/xdocs/hpsf/how-to.xml index d2904dfd3..a5cdce232 100644 --- a/src/documentation/content/xdocs/hpsf/how-to.xml +++ b/src/documentation/content/xdocs/hpsf/how-to.xml @@ -903,12 +903,16 @@ No property set stream: "/1Table" 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, is makes the example very simple, and you will get quickly - used to writing properties.

+ 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.

-

Here's the source code of the sample application. You can also find it - in the "examples" section of the POI source code - distribution. Explanations are following below.

+

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".

+ +

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.

package org.apache.poi.hpsf.examples; @@ -972,9 +976,10 @@ public class WriteTitle } -

The application expects the name of the POI file system to be created - on the command line. It checks that there is exactly a single argument - and stores it in the fileName variable:

+

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 + fileName variable. It will be used in the end when the POI + file system is written to a disk file.

if (args.length != 1) { @@ -985,53 +990,67 @@ public class WriteTitle final String fileName = args[0];

Let's create a property set now. We cannot use the - PropertySet class, because it is read-only: It does not have + PropertySet 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. Instead use the class - MutablePropertySet. It is a subclass of - PropertySet, and its no-args constructor established an - empty property set which we will fill later.

+ methods to modify its contents, i.e. to write sections containing + properties into it.

+ +

The class to use is MutablePropertySet. It is a subclass + of PropertySet. The sample application calls its no-args + constructor in order to establish an empty property set:

final MutablePropertySet mps = new MutablePropertySet(); +

As said, we have an empty property set now. Later we will put some + contents into it.

+

By the way, the MutablePropertySet class has another constructor taking a PropertySet as parameter. It creates a - mutable copy of its parameter.

+ mutable deep copy of the property set given to it.

The MutablePropertySet created by the no-args constructor - is not really empty: It contains a single section without any - properties. We can either retrieve that section and fill it with - properties, or we can replace it by another section. Of course we can - also add further sections to the property set. The sample application - decides to retrieve the section being already there:

+ 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:

final MutableSection ms = (MutableSection) mps.getSections().get(0);

The getSections() method returns the property set's sections as a list, i.e. an instance of java.util.List. Calling get(0) returns the - list's first (or zeroth if you prefer) element. It is a - MutableSection: a subclass of Section you can - modify.

+ list's first (or zeroth, if you prefer) element. The Section + returned is a MutableSection: a subclass of + Section you can modify.

-

Presently the MutableSection is still empty: It contains - no properties and does not have a format ID. As you have read in above the format ID of the first section in a - property set determines the property set's type. If our property set - should become a summary information property set we have to set the - format ID of its first (and only) section to - F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9. However, you - won't have to remember that ID if you want to write your own - summary information property sets: HPSF has it defined as the well-known - constant Section.getFormatID(). The sample application - writes it to the section with the setFormatID(byte[]) - method.

+

The alternative to retrieving the MutableSection being + already there would have been to create an new + MutableSection like this:

+ + MutableSection s = new MutableSection(); + +

There is also a constructor which takes a Section as + parameter and creates a mutable deep copy of it.

+ +

The MutableSection the sample application retrieved from + the MutablePropertySet is still empty. It contains no + properties and does not have a format ID. As you have read above 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 + F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9. However, you + won't have to remember that ID: HPSF has it defined as the well-known + constant SectionIDMap.SUMMARY_INFORMATION_ID. The sample + application writes it to the section using the + setFormatID(byte[]) method:

ms.setFormatID(SectionIDMap.SUMMARY_INFORMATION_ID);

Now it is time to create a property. As you might expect there is a subclass of Property called - MutableProperty.

+ MutableProperty with a no-args constructor:

final MutableProperty p = new MutableProperty(); @@ -1043,36 +1062,41 @@ final String fileName = args[0]; p.setType(Variant.VT_LPWSTR); p.setValue("Sample title"); -

Now the sample property set is complete: We have a +

The MutableProperty 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!

+ +

The sample property set is complete now. We have a MutablePropertySet containing a MutableSection containing a MutableProperty. Of course we could have added - more sections and properties but we wanted to keep things simple.

+ more sections to the property set and more properties to the sections but + we wanted to keep things simple.

The property set has to be written to a POI file system. The following statement creates it.

final POIFSFileSystem poiFs = new POIFSFileSystem(); -

In order to write the property set to a POI file system it must be - converted into a sequence of bytes. The MutablePropertySet - class has a method toInputStream(). This method returns an - InputStream containing the bytes making out the property set - stream.

+

Writing the property set includes the step of converting it into a + sequence of bytes. The MutablePropertySet class has the + method toInputStream() for this purpose. It returns the + bytes making out the property set stream as an + InputStream:

final InputStream is = mps.toInputStream(); -

If you'd read from this input stream you'd receive all these - bytes. However, it is very likely that you never do that. Instead you'll - pass the input stream to the createDocument() method of a - POIFSFileSystem instance, like the one we created a few - lines ago. Besides an InputStream the - createDocument() method takes another parameter: the name of - the document to be created. For a summary information property set stream - the default name is available as - SummaryInformation.DEFAULT_STREAM_NAME:

+

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 + POIFSFileSystem.createDocument() method, like this:

poiFs.createDocument(is, SummaryInformation.DEFAULT_STREAM_NAME); +

Besides the InputStream createDocument() + 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 SummaryInformation.DEFAULT_STREAM_NAME.

+

The last step is to write the POI file system to a disk file:

poiFs.writeFilesystem(new FileOutputStream(fileName));