org.apache.poi.hpsf

## Class PropertySet

- java.lang.Object
- - org.apache.poi.hpsf.PropertySet

- Direct Known Subclasses:
    DocumentSummaryInformation, SummaryInformation

      public class PropertySet
      extends java.lang.Object

  Represents a property set in the Horrible Property Set Format (HPSF). These are usually metadata of a Microsoft Office document.

  An application that wants to access these metadata should create an instance of this class or one of its subclasses by calling the factory method `PropertySetFactory.create(org.apache.poi.poifs.filesystem.DirectoryEntry, java.lang.String)` and then retrieve the information its needs by calling appropriate methods.

  `PropertySetFactory.create(org.apache.poi.poifs.filesystem.DirectoryEntry, java.lang.String)` does its work by calling one of the constructors `PropertySet(InputStream)` or `PropertySet(byte[])`. If the constructor's argument is not in the Horrible Property Set Format, i.e. not a property set stream, or if any other error occurs, an appropriate exception is thrown.

  A `PropertySet` has a list of `Section`s, and each `Section` has a `Property` array. Use `getSections()` to retrieve the `Section`s, then call `Section.getProperties()` for each `Section` to get hold of the `Property` arrays.

  Since the vast majority of `PropertySet`s contains only a single `Section`, the convenience method `getProperties()` returns the properties of a `PropertySet`'s `Section` (throwing a `NoSingleSectionException` if the `PropertySet` contains more (or less) than exactly one `Section`).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `OS_MACINTOSH` If the OS version field holds this value the property set stream was created on a Macintosh system.
    `static int` | `OS_WIN16` If the OS version field holds this value the property set stream was created on a 16-bit Windows system.
    `static int` | `OS_WIN32` If the OS version field holds this value the property set stream was created on a 32-bit Windows system.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PropertySet()` Constructs a `PropertySet` instance.
    `PropertySet(byte[] stream)` Creates a `PropertySet` instance from a byte array that represents a stream in the Horrible Property Set Format.
    `PropertySet(byte[] stream, int offset, int length)` Creates a `PropertySet` instance from a byte array that represents a stream in the Horrible Property Set Format.
    `PropertySet(java.io.InputStream stream)` Creates a `PropertySet` instance from an `InputStream` in the Horrible Property Set Format.
    `PropertySet(PropertySet ps)` Constructs a `PropertySet` by doing a deep copy of an existing `PropertySet`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `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()`
    `ClassID` | `getClassID()`
    `Section` | `getFirstSection()` Gets the `PropertySet`'s first section.
    `int` | `getFormat()`
    `int` | `getOSVersion()`
    `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.
    `PropertyIDMap` | `getPropertySetIDMap()` The id to name mapping of the properties in this set.
    `static java.lang.String` | `getPropertyStringValue(java.lang.Object propertyValue)` Return the string representation of a property value
    `int` | `getSectionCount()`
    `java.util.List<Section>` | `getSections()`
    `Section` | `getSingleSection()` Deprecated. superfluous convenience method
    `int` | `hashCode()`
    `boolean` | `isDocumentSummaryInformation()` Checks whether this `PropertySet` is a Document Summary Information.
    `static boolean` | `isPropertySetStream(byte[] src, int offset, int length)` Checks whether a byte array is in the Horrible Property Set Format.
    `static boolean` | `isPropertySetStream(java.io.InputStream stream)` Checks whether an `InputStream` is in the Horrible Property Set Format.
    `boolean` | `isSummaryInformation()` Checks whether this `PropertySet` represents a Summary Information.
    `void` | `setByteOrder(int byteOrder)` Returns the property set stream's low-level "byte order" field.
    `void` | `setClassID(ClassID classID)` Sets the property set stream's low-level "class ID" field.
    `void` | `setFormat(int format)` Sets the property set stream's low-level "format" field.
    `void` | `setOSVersion(int osVersion)` Sets the property set stream's low-level "OS version" field.
    `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 `getPropertyIntValue(int)` or `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 java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### OS_WIN16

          public static final int OS_WIN16

      If the OS version field holds this value the property set stream was created on a 16-bit Windows system.
      See Also:
        Constant Field Values

    - #### OS_MACINTOSH

          public static final int OS_MACINTOSH

      If the OS version field holds this value the property set stream was created on a Macintosh system.
      See Also:
        Constant Field Values

    - #### OS_WIN32

          public static final int OS_WIN32

      If the OS version field holds this value the property set stream was created on a 32-bit Windows system.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PropertySet

          public PropertySet()

      Constructs a `PropertySet` instance. Its primary task is to initialize the field with their proper values. It also sets fields that might change to reasonable defaults.

    - #### PropertySet

          public PropertySet(java.io.InputStream stream)
                      throws NoPropertySetStreamException,
                             java.io.IOException

      Creates a `PropertySet` instance from an `InputStream` in the Horrible Property Set Format.

      The constructor reads the first few bytes from the stream and determines whether it is really a property set stream. If it is, it parses the rest of the stream. If it is not, it resets the stream to its beginning in order to let other components mess around with the data and throws an exception.

      Parameters:
        `stream` - Holds the data making out the property set stream.
      Throws:
        `java.io.IOException` - if the `InputStream` cannot be accessed as needed.
        `NoPropertySetStreamException` - if the input stream does not contain a property set.
        `java.io.UnsupportedEncodingException` - if a character encoding is not supported.

    - #### PropertySet

          public PropertySet(byte[] stream,
                             int offset,
                             int length)
                      throws NoPropertySetStreamException,
                             java.io.UnsupportedEncodingException

      Creates a `PropertySet` instance from a byte array that represents a stream in the Horrible Property Set Format.
      Parameters:
        `stream` - The byte array holding the stream data.
        `offset` - The offset in `stream` where the stream data begin. If the stream data begin with the first byte in the array, the `offset` is 0.
        `length` - The length of the stream data.
      Throws:
        `NoPropertySetStreamException` - if the byte array is not a property set stream.
        `java.io.UnsupportedEncodingException` - if the codepage is not supported.

    - #### PropertySet

          public PropertySet(byte[] stream)
                      throws NoPropertySetStreamException,
                             java.io.UnsupportedEncodingException

      Creates a `PropertySet` instance from a byte array that represents a stream in the Horrible Property Set Format.
      Parameters:
        `stream` - The byte array holding the stream data. The complete byte array contents is the stream data.
      Throws:
        `NoPropertySetStreamException` - if the byte array is not a property set stream.
        `java.io.UnsupportedEncodingException` - if the codepage is not supported.

    - #### PropertySet

          public PropertySet(PropertySet ps)

      Constructs a `PropertySet` by doing a deep copy of an existing `PropertySet`. All nested elements, i.e. `Section`s and `Property` instances, will be their counterparts in the new `PropertySet`.
      Parameters:
        `ps` - The property set to copy

  - ### Method Detail

    - #### getByteOrder

          public int getByteOrder()

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

    - #### setByteOrder

          public void setByteOrder(int byteOrder)

      Returns the property set stream's low-level "byte order" field.
      Parameters:
        `byteOrder` - The property set stream's low-level "byte order" field.

    - #### getFormat

          public int getFormat()

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

    - #### setFormat

          public void setFormat(int format)

      Sets the property set stream's low-level "format" field.
      Parameters:
        `format` - The property set stream's low-level "format" field.

    - #### getOSVersion

          public int getOSVersion()

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

    - #### setOSVersion

          public void setOSVersion(int osVersion)

      Sets the property set stream's low-level "OS version" field.
      Parameters:
        `osVersion` - The property set stream's low-level "OS version" field.

    - #### getClassID

          public ClassID getClassID()

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

    - #### setClassID

          public void setClassID(ClassID classID)

      Sets the property set stream's low-level "class ID" field.
      Parameters:
        `classID` - The property set stream's low-level "class ID" field.

    - #### getSectionCount

          public int getSectionCount()

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

    - #### getSections

          public java.util.List<Section> getSections()

      Returns:
        The unmodifiable list of `Section`s in the property set.

    - #### addSection

          public void addSection(Section section)

      Adds a section to this property set.
      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.

    - #### clearSections

          public void clearSections()

      Removes all sections from this property set.

    - #### getPropertySetIDMap

          public PropertyIDMap getPropertySetIDMap()

      The id to name mapping of the properties in this set.
      Returns:
        the id to name mapping of the properties in this set or `null` if not applicable

    - #### isPropertySetStream

          public static boolean isPropertySetStream(java.io.InputStream stream)
                                             throws java.io.IOException

      Checks whether an `InputStream` is in the Horrible Property Set Format.
      Parameters:
        `stream` - The `InputStream` to check. In order to perform the check, the method reads the first bytes from the stream. After reading, the stream is reset to the position it had before reading. The `InputStream` must support the `InputStream.mark(int)` method.
      Returns:
        `true` if the stream is a property set stream, else `false`.
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### isPropertySetStream

          public static boolean isPropertySetStream(byte[] src,
                                                    int offset,
                                                    int length)

      Checks whether a byte array is in the Horrible Property Set Format.
      Parameters:
        `src` - The byte array to check.
        `offset` - The offset in the byte array.
        `length` - The significant number of bytes in the byte array. Only this number of bytes will be checked.
      Returns:
        `true` if the byte array is a property set stream, `false` if not.

    - #### write

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

      Writes the property set to an output stream.
      Parameters:
        `out` - the output stream to write the section to
      Throws:
        `java.io.IOException` - if an error when writing to the output stream occurs
        `WritingNotSupportedException` - if HPSF does not yet support writing a property's variant type.

    - #### write

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

      Writes a property set to a document in a POI filesystem directory.
      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` - if the filesystem doesn't support writing
        `java.io.IOException` - if the old entry can't be deleted or the new entry be written

    - #### toInputStream

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

      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 `PropertySet` only.
      Returns:
        the contents of this property set stream
      Throws:
        `WritingNotSupportedException` - if HPSF does not yet support writing of a property's variant type.
        `java.io.IOException` - if an I/O exception occurs.

    - #### getPropertyStringValue

          public static java.lang.String getPropertyStringValue(java.lang.Object propertyValue)

      Return the string representation of a property value
      Parameters:
        `propertyValue` - the property value
      Returns:
        The property value as a String, or null if unavailable

    - #### isSummaryInformation

          public boolean isSummaryInformation()

      Checks whether this `PropertySet` represents a Summary Information.
      Returns:
        `true` if this `PropertySet` represents a Summary Information, else `false`.

    - #### isDocumentSummaryInformation

          public boolean isDocumentSummaryInformation()

      Checks whether this `PropertySet` is a Document Summary Information.
      Returns:
        `true` if this `PropertySet` represents a Document Summary Information, else `false`.

    - #### getProperties

          public Property[] getProperties()
                                   throws NoSingleSectionException

      Convenience method returning the `Property` array contained in this property set. It is a shortcut for getting he `PropertySet`'s `Section`s list and then getting the `Property` array from the first `Section`.
      Returns:
        The properties of the only `Section` of this `PropertySet`.
      Throws:
        `NoSingleSectionException` - if the `PropertySet` has more or less than one `Section`.

    - #### getProperty

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

      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 `wasNull()` will return `true`.
      Parameters:
        `id` - The property ID
      Returns:
        The property value
      Throws:
        `NoSingleSectionException` - if the `PropertySet` has more or less than one `Section`.

    - #### wasNull

          public boolean wasNull()
                          throws NoSingleSectionException

      Checks whether the property which the last call to `getPropertyIntValue(int)` or `getProperty(int)` tried to access was available or not. This information might be important for callers of `getPropertyIntValue(int)` since the latter returns 0 if the property does not exist. Using wasNull, the caller can distinguish this case from a property's real value of 0.
      Returns:
        `true` if the last call to `getPropertyIntValue(int)` or `getProperty(int)` tried to access a property that was not available, else `false`.
      Throws:
        `NoSingleSectionException` - if the `PropertySet` has more than one `Section`.

    - #### getFirstSection

          public Section getFirstSection()

      Gets the `PropertySet`'s first section.
      Returns:
        The `PropertySet`'s first section.

    - #### getSingleSection

          @Deprecated
           @Removal(version="5.0.0")
          public Section getSingleSection()

      Deprecated. superfluous convenience method
      If the `PropertySet` has only a single section this method returns it.
      Returns:
        The singleSection value

    - #### equals

          public boolean equals(java.lang.Object o)

      Returns `true` if the `PropertySet` is equal to the specified parameter, else `false`.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `o` - the object to compare this `PropertySet` with
      Returns:
        `true` if the objects are equal, `false` if not

    - #### hashCode

          @NotImplemented
          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`
      See Also:
        `Object.hashCode()`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`
      See Also:
        `Object.toString()`

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