## org.apache.poi.hpsf
Class SpecialPropertySet

    java.lang.Object
      org.apache.poi.hpsf.PropertySet
          org.apache.poi.hpsf.MutablePropertySet
              org.apache.poi.hpsf.SpecialPropertySet

Direct Known Subclasses:
  DocumentSummaryInformation, SummaryInformation

    public abstract class SpecialPropertySet

extends MutablePropertySet

Abstract superclass for the convenience classes `SummaryInformation` and `DocumentSummaryInformation`.

The motivation behind this class is quite nasty if you look behind the scenes, but it serves the application programmer well by providing him with the easy-to-use `SummaryInformation` and `DocumentSummaryInformation` classes. When parsing the data a property set stream consists of (possibly coming from an `InputStream`) we want to read and process each byte only once. Since we don't know in advance which kind of property set we have, we can expect only the most general `PropertySet`. Creating a special subclass should be as easy as calling the special subclass' constructor and pass the general `PropertySet` in. To make things easy internally, the special class just holds a reference to the general `PropertySet` and delegates all method calls to it.

A cleaner implementation would have been like this: The `PropertySetFactory` parses the stream data into some internal object first. Then it finds out whether the stream is a `SummaryInformation`, a `DocumentSummaryInformation` or a general `PropertySet`. However, the current implementation went the other way round historically: the convenience classes came only late to my mind.

Author:
  Rainer Klute <klute@rainer-klute.de>

Field Summary

Fields inherited from class org.apache.poi.hpsf.PropertySet
`byteOrder, classID, format, OS_MACINTOSH, OS_WIN16, OS_WIN32, osVersion, sections`

Constructor Summary
`SpecialPropertySet(MutablePropertySet ps)` Creates a `SpecialPropertySet`.
`SpecialPropertySet(PropertySet ps)` Creates a `SpecialPropertySet`.

Method Summary
`void` `addSection(Section section)` Adds a section to this property set.
`void` `clearSections()` Removes all sections from this property set.
`boolean` `equals(java.lang.Object o)` Returns `true` if the `PropertySet` is equal to the specified parameter, else `false`.
`int` `getByteOrder()` Returns the property set stream's low-level "byte order" field.
`ClassID` `getClassID()` Returns the property set stream's low-level "class ID" field.
`Section` `getFirstSection()` Gets the `PropertySet`'s first section.
`int` `getFormat()` Returns the property set stream's low-level "format" field.
`int` `getOSVersion()` Returns the property set stream's low-level "OS version" field.
`Property[]` `getProperties()` Convenience method returning the `Property` array contained in this property set.
`protected java.lang.Object` `getProperty(int id)` Convenience method returning the value of the property with the specified ID.
`protected boolean` `getPropertyBooleanValue(int id)` Convenience method returning the value of a boolean property with the specified ID.
`protected int` `getPropertyIntValue(int id)` Convenience method returning the value of the numeric property with the specified ID.
`abstract PropertyIDMap` `getPropertySetIDMap()` The id to name mapping of the properties in this set.
`int` `getSectionCount()` Returns the number of `Section`s in the property set.
`java.util.List` `getSections()` Returns the `Section`s in the property set.
`int` `hashCode()`
`boolean` `isDocumentSummaryInformation()` Checks whether this `PropertySet` is a Document Summary Information.
`boolean` `isSummaryInformation()` Checks whether this `PropertySet` represents a Summary Information.
`void` `setByteOrder(int byteOrder)` Sets the "byteOrder" property.
`void` `setClassID(ClassID classID)` Sets the property set stream's low-level "class ID" field.
`void` `setFormat(int format)` Sets the "format" property.
`void` `setOSVersion(int osVersion)` Sets the "osVersion" property.
`java.io.InputStream` `toInputStream()` Returns the contents of this property set stream as an input stream.
`java.lang.String` `toString()`
`boolean` `wasNull()` Checks whether the property which the last call to `PropertySet.getPropertyIntValue(int)` or `PropertySet.getProperty(int)` tried to access was available or not.
`void` `write(DirectoryEntry dir, java.lang.String name)` Writes a property set to a document in a POI filesystem directory.
`void` `write(java.io.OutputStream out)` Writes the property set to an output stream.

Methods inherited from class org.apache.poi.hpsf.PropertySet
`getSingleSection, isPropertySetStream, isPropertySetStream`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Constructor Detail

### SpecialPropertySet

    public SpecialPropertySet(PropertySet ps)

  Creates a `SpecialPropertySet`.

  Parameters:
    `ps` - The property set to be encapsulated by the `SpecialPropertySet`

### SpecialPropertySet

    public SpecialPropertySet(MutablePropertySet ps)

  Creates a `SpecialPropertySet`.

  Parameters:
    `ps` - The mutable property set to be encapsulated by the `SpecialPropertySet`

Method Detail

### getPropertySetIDMap

    public abstract PropertyIDMap getPropertySetIDMap()

  The id to name mapping of the properties in this set.

### getByteOrder

    public int getByteOrder()

  Description copied from class: `PropertySet`

  Returns the property set stream's low-level "byte order" field. It is always `0xFFFE` .

  Overrides:
    `getByteOrder` in class `PropertySet`
  Returns:
    The property set stream's low-level "byte order" field.
  See Also:
    `PropertySet.getByteOrder()`

### getFormat

    public int getFormat()

  Description copied from class: `PropertySet`

  Returns the property set stream's low-level "format" field. It is always `0x0000` .

  Overrides:
    `getFormat` in class `PropertySet`
  Returns:
    The property set stream's low-level "format" field.
  See Also:
    `PropertySet.getFormat()`

### getOSVersion

    public int getOSVersion()

  Description copied from class: `PropertySet`

  Returns the property set stream's low-level "OS version" field.

  Overrides:
    `getOSVersion` in class `PropertySet`
  Returns:
    The property set stream's low-level "OS version" field.
  See Also:
    `PropertySet.getOSVersion()`

### getClassID

    public ClassID getClassID()

  Description copied from class: `PropertySet`

  Returns the property set stream's low-level "class ID" field.

  Overrides:
    `getClassID` in class `PropertySet`
  Returns:
    The property set stream's low-level "class ID" field.
  See Also:
    `PropertySet.getClassID()`

### getSectionCount

    public int getSectionCount()

  Description copied from class: `PropertySet`

  Returns the number of `Section`s in the property set.

  Overrides:
    `getSectionCount` in class `PropertySet`
  Returns:
    The number of `Section`s in the property set.
  See Also:
    `PropertySet.getSectionCount()`

### getSections

    public java.util.List getSections()

  Description copied from class: `PropertySet`

  Returns the `Section`s in the property set.

  Overrides:
    `getSections` in class `PropertySet`
  Returns:
    The `Section`s in the property set.
  See Also:
    `PropertySet.getSections()`

### isSummaryInformation

    public boolean isSummaryInformation()

  Description copied from class: `PropertySet`

  Checks whether this `PropertySet` represents a Summary Information.

  Overrides:
    `isSummaryInformation` in class `PropertySet`
  Returns:
    `true` if this `PropertySet` represents a Summary Information, else `false`.
  See Also:
    `PropertySet.isSummaryInformation()`

### isDocumentSummaryInformation

    public boolean isDocumentSummaryInformation()

  Description copied from class: `PropertySet`

  Checks whether this `PropertySet` is a Document Summary Information.

  Overrides:
    `isDocumentSummaryInformation` in class `PropertySet`
  Returns:
    `true` if this `PropertySet` represents a Document Summary Information, else `false`.
  See Also:
    `PropertySet.isDocumentSummaryInformation()`

### getFirstSection

    public Section getFirstSection()

  Description copied from class: `PropertySet`

  Gets the `PropertySet`'s first section.

  Overrides:
    `getFirstSection` in class `PropertySet`
  Returns:
    The `PropertySet`'s first section.
  See Also:
    `PropertySet.getSingleSection()`

### addSection

    public void addSection(Section section)

  Description copied from class: `MutablePropertySet`

  Adds a section to this property set.

  Overrides:
    `addSection` in class `MutablePropertySet`
  Parameters:
    `section` - The `Section` to add. It will be appended after any sections that are already present in the property set and thus become the last section.
  See Also:
    `MutablePropertySet.addSection(org.apache.poi.hpsf.Section)`

### clearSections

    public void clearSections()

  Description copied from class: `MutablePropertySet`

  Removes all sections from this property set.

  Overrides:
    `clearSections` in class `MutablePropertySet`
  See Also:
    `MutablePropertySet.clearSections()`

### setByteOrder

    public void setByteOrder(int byteOrder)

  Description copied from class: `MutablePropertySet`

  Sets the "byteOrder" property.

  Overrides:
    `setByteOrder` in class `MutablePropertySet`
  Parameters:
    `byteOrder` - the byteOrder value to set
  See Also:
    `MutablePropertySet.setByteOrder(int)`

### setClassID

    public void setClassID(ClassID classID)

  Description copied from class: `MutablePropertySet`

  Sets the property set stream's low-level "class ID" field.

  Overrides:
    `setClassID` in class `MutablePropertySet`
  Parameters:
    `classID` - The property set stream's low-level "class ID" field.
  See Also:
    `MutablePropertySet.setClassID(org.apache.poi.hpsf.ClassID)`

### setFormat

    public void setFormat(int format)

  Description copied from class: `MutablePropertySet`

  Sets the "format" property.

  Overrides:
    `setFormat` in class `MutablePropertySet`
  Parameters:
    `format` - the format value to set
  See Also:
    `MutablePropertySet.setFormat(int)`

### setOSVersion

    public void setOSVersion(int osVersion)

  Description copied from class: `MutablePropertySet`

  Sets the "osVersion" property.

  Overrides:
    `setOSVersion` in class `MutablePropertySet`
  Parameters:
    `osVersion` - the osVersion value to set
  See Also:
    `MutablePropertySet.setOSVersion(int)`

### toInputStream

    public java.io.InputStream toInputStream()
                                      throws java.io.IOException,
                                             WritingNotSupportedException

  Description copied from class: `MutablePropertySet`

  Returns the contents of this property set stream as an input stream. The latter can be used for example to write the property set into a POIFS document. The input stream represents a snapshot of the property set. If the latter is modified while the input stream is still being read, the modifications will not be reflected in the input stream but in the `MutablePropertySet` only.

  Overrides:
    `toInputStream` in class `MutablePropertySet`
  Returns:
    the contents of this property set stream
  Throws:
    `java.io.IOException` - if an I/O exception occurs.
    `WritingNotSupportedException` - if HPSF does not yet support writing of a property's variant type.
  See Also:
    `MutablePropertySet.toInputStream()`

### write

    public void write(DirectoryEntry dir,
                      java.lang.String name)
               throws WritingNotSupportedException,
                      java.io.IOException

  Description copied from class: `MutablePropertySet`

  Writes a property set to a document in a POI filesystem directory.

  Overrides:
    `write` in class `MutablePropertySet`
  Parameters:
    `dir` - The directory in the POI filesystem to write the document to.
    `name` - The document's name. If there is already a document with the same name in the directory the latter will be overwritten.
  Throws:
    `WritingNotSupportedException`
    `java.io.IOException`
  See Also:
    `MutablePropertySet.write(org.apache.poi.poifs.filesystem.DirectoryEntry, java.lang.String)`

### write

    public void write(java.io.OutputStream out)
               throws WritingNotSupportedException,
                      java.io.IOException

  Description copied from class: `MutablePropertySet`

  Writes the property set to an output stream.

  Overrides:
    `write` in class `MutablePropertySet`
  Parameters:
    `out` - the output stream to write the section to
  Throws:
    `WritingNotSupportedException` - if HPSF does not yet support writing a property's variant type.
    `java.io.IOException` - if an error when writing to the output stream occurs
  See Also:
    `MutablePropertySet.write(java.io.OutputStream)`

### equals

    public boolean equals(java.lang.Object o)

  Description copied from class: `PropertySet`

  Returns `true` if the `PropertySet` is equal to the specified parameter, else `false`.

  Overrides:
    `equals` in class `PropertySet`
  Parameters:
    `o` - the object to compare this `PropertySet` with
  Returns:
    `true` if the objects are equal, `false` if not
  See Also:
    `PropertySet.equals(java.lang.Object)`

### getProperties

    public Property[] getProperties()
                             throws NoSingleSectionException

  Description copied from class: `PropertySet`

  Convenience method returning the `Property` array contained in this property set. It is a shortcut for getting the `PropertySet`'s `Section`s list and then getting the `Property` array from the first `Section`.

  Overrides:
    `getProperties` in class `PropertySet`
  Returns:
    The properties of the only `Section` of this `PropertySet`.
  Throws:
    `NoSingleSectionException` - if the `PropertySet` has more or less than one `Section`.
  See Also:
    `PropertySet.getProperties()`

### getProperty

    protected java.lang.Object getProperty(int id)
                                    throws NoSingleSectionException

  Description copied from class: `PropertySet`

  Convenience method returning the value of the property with the specified ID. If the property is not available, `null` is returned and a subsequent call to `PropertySet.wasNull()` will return `true` .

  Overrides:
    `getProperty` in class `PropertySet`
  Parameters:
    `id` - The property ID
  Returns:
    The property value
  Throws:
    `NoSingleSectionException` - if the `PropertySet` has more or less than one `Section`.
  See Also:
    `PropertySet.getProperty(int)`

### getPropertyBooleanValue

    protected boolean getPropertyBooleanValue(int id)
                                       throws NoSingleSectionException

  Description copied from class: `PropertySet`

  Convenience method returning the value of a boolean property with the specified ID. If the property is not available, `false` is returned. A subsequent call to `PropertySet.wasNull()` will return `true` to let the caller distinguish that case from a real property value of `false`.

  Overrides:
    `getPropertyBooleanValue` in class `PropertySet`
  Parameters:
    `id` - The property ID
  Returns:
    The property value
  Throws:
    `NoSingleSectionException` - if the `PropertySet` has more or less than one `Section`.
  See Also:
    `PropertySet.getPropertyBooleanValue(int)`

### getPropertyIntValue

    protected int getPropertyIntValue(int id)
                               throws NoSingleSectionException

  Description copied from class: `PropertySet`

  Convenience method returning the value of the numeric property with the specified ID. If the property is not available, 0 is returned. A subsequent call to `PropertySet.wasNull()` will return `true` to let the caller distinguish that case from a real property value of 0.

  Overrides:
    `getPropertyIntValue` in class `PropertySet`
  Parameters:
    `id` - The property ID
  Returns:
    The propertyIntValue value
  Throws:
    `NoSingleSectionException` - if the `PropertySet` has more or less than one `Section`.
  See Also:
    `PropertySet.getPropertyIntValue(int)`

### hashCode

    public int hashCode()

  Overrides:
    `hashCode` in class `PropertySet`
  See Also:
    `PropertySet.hashCode()`

### toString

    public java.lang.String toString()

  Overrides:
    `toString` in class `PropertySet`
  See Also:
    `PropertySet.toString()`

### wasNull

    public boolean wasNull()
                    throws NoSingleSectionException

  Description copied from class: `PropertySet`

  Checks whether the property which the last call to `PropertySet.getPropertyIntValue(int)` or `PropertySet.getProperty(int)` tried to access was available or not. This information might be important for callers of `PropertySet.getPropertyIntValue(int)` since the latter returns 0 if the property does not exist. Using `PropertySet.wasNull()`, the caller can distiguish this case from a property's real value of 0.

  Overrides:
    `wasNull` in class `PropertySet`
  Returns:
    `true` if the last call to `PropertySet.getPropertyIntValue(int)` or `PropertySet.getProperty(int)` tried to access a property that was not available, else `false`.
  Throws:
    `NoSingleSectionException` - if the `PropertySet` has more than one `Section`.
  See Also:
    `PropertySet.wasNull()`

Copyright 2012 The Apache Software Foundation or its licensors, as applicable.