Package org.apache.poi.hpsf

Class Section

  • public class Section
extends java.lang.Object
    Represents a section in a PropertySet.

    • Constructor Summary

      Constructors 
      Constructor Description
      Section()
      Creates an empty Section.
      Section​(byte[] src, int offset)
      Creates a Section instance from a byte array.
      Section​(Section s)
      Constructs a Section by doing a deep copy of an existing Section.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clear()
      Removes all properties from the section including 0 (dictionary) and 1 (codepage).
      boolean equals​(java.lang.Object o)
      Checks whether this section is equal to another object.
      int getCodepage()
      Gets the section's codepage, if any.
      java.util.Map<java.lang.Long,​java.lang.String> getDictionary()
      Gets the section's dictionary.
      ClassID getFormatID()
      Returns the format ID.
      long getOffset()
      Returns the offset of the section in the stream.
      java.lang.String getPIDString​(long pid)
      Returns the PID string associated with a property ID.
      Property[] getProperties()
      Returns this section's properties.
      java.lang.Object getProperty​(long id)
      Returns the value of the property with the specified ID.
      int getPropertyCount()
      Returns the number of properties in this section.
      int getSize()  
      int hashCode()  
      void removeProperty​(long id)
      Removes a property.
      void setCodepage​(int codepage)
      Sets the codepage.
      void setDictionary​(java.util.Map<java.lang.Long,​java.lang.String> dictionary)
      Sets the section's dictionary.
      void setFormatID​(byte[] formatID)
      Sets the section's format ID.
      void setFormatID​(ClassID formatID)
      Sets the section's format ID.
      void setProperties​(Property[] properties)
      Sets this section's properties.
      void setProperty​(int id, boolean value)
      Sets the boolean value of the property with the specified ID.
      void setProperty​(int id, int value)
      Sets the int value of the property with the specified ID.
      void setProperty​(int id, long value)
      Sets the long value of the property with the specified ID.
      void setProperty​(int id, long variantType, java.lang.Object value)
      Sets the value and the variant type of the property with the specified ID.
      void setProperty​(int id, java.lang.Object value)
      Sets a property.
      void setProperty​(int id, java.lang.String value)
      Sets the string value of the property with the specified ID.
      void setProperty​(Property p)
      Sets a property.
      java.lang.String toString()  
      java.lang.String toString​(PropertyIDMap idMap)  
      boolean wasNull()
      Checks whether the property which the last call to getPropertyIntValue(long) or getProperty(long) tried to access was available or not.
      int write​(java.io.OutputStream out)
      Writes this section into an output stream.

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • Section

        public Section()
        Creates an empty Section.

      • Section

        public Section​(Section s)
        Constructs a Section by doing a deep copy of an existing Section. All nested Property instances, will be their mutable counterparts in the new MutableSection.
        Parameters:
        s - The section set to copy

      • Section

        public Section​(byte[] src,
               int offset)
        throws java.io.UnsupportedEncodingException
        Creates a Section instance from a byte array.
        Parameters:
        src - Contains the complete property set stream.
        offset - The position in the stream that points to the section's format ID.
        Throws:
        java.io.UnsupportedEncodingException - if the section's codepage is not supported.

    • Method Detail

      • getFormatID

        public ClassID getFormatID()
        Returns the format ID. The format ID is the "type" of the section. For example, if the format ID of the first Section contains the bytes specified by org.apache.poi.hpsf.wellknown.SectionIDMap.SUMMARY_INFORMATION_ID the section (and thus the property set) is a SummaryInformation.
        Returns:
        The format ID

      • setFormatID

        public void setFormatID​(ClassID formatID)
        Sets the section's format ID.
        Parameters:
        formatID - The section's format ID

      • setFormatID

        public void setFormatID​(byte[] formatID)
        Sets the section's format ID.
        Parameters:
        formatID - The section's format ID as a byte array. It components are in big-endian format.

      • getOffset

        public long getOffset()
        Returns the offset of the section in the stream.
        Returns:
        The offset of the section in the stream.

      • getPropertyCount

        public int getPropertyCount()
        Returns the number of properties in this section.
        Returns:
        The number of properties in this section.

      • getProperties

        public Property[] getProperties()
        Returns this section's properties.
        Returns:
        This section's properties.

      • setProperties

        public void setProperties​(Property[] properties)
        Sets this section's properties. Any former values are overwritten.
        Parameters:
        properties - This section's new properties.

      • getProperty

        public java.lang.Object getProperty​(long id)
        Returns 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's ID
        Returns:
        The property's value

      • setProperty

        public void setProperty​(int id,
                        java.lang.String value)
        Sets the string value of the property with the specified ID.
        Parameters:
        id - The property's ID
        value - The property's value.

      • setProperty

        public void setProperty​(int id,
                        int value)
        Sets the int value of the property with the specified ID.
        Parameters:
        id - The property's ID
        value - The property's value.
        See Also:
        setProperty(int, long, Object), getProperty(long)

      • setProperty

        public void setProperty​(int id,
                        long value)
        Sets the long value of the property with the specified ID.
        Parameters:
        id - The property's ID
        value - The property's value.
        See Also:
        setProperty(int, long, Object), getProperty(long)

      • setProperty

        public void setProperty​(int id,
                        boolean value)
        Sets the boolean value of the property with the specified ID.
        Parameters:
        id - The property's ID
        value - The property's value.
        See Also:
        setProperty(int, long, Object), getProperty(long)

      • setProperty

        public void setProperty​(int id,
                        long variantType,
                        java.lang.Object value)
        Sets the value and the variant type of the property with the specified ID. If a property with this ID is not yet present in the section, it will be added. An already present property with the specified ID will be overwritten. A default mapping will be used to choose the property's type.
        Parameters:
        id - The property's ID.
        variantType - The property's variant type.
        value - The property's value.
        See Also:
        setProperty(int, String), getProperty(long), Variant

      • setProperty

        public void setProperty​(int id,
                        java.lang.Object value)
        Sets a property.
        Parameters:
        id - The property ID.
        value - The property's value. The value's class must be one of those supported by HPSF.

      • getSize

        public int getSize()
        Returns:
        the section's size in bytes.

      • getPIDString

        public java.lang.String getPIDString​(long pid)
        Returns the PID string associated with a property ID. The ID is first looked up in the Sections private dictionary. If it is not found there, the property PID string is taken from sections format IDs namespace. If the PID is also undefined there, i.e. it is not well-known, "[undefined]" is returned.
        Parameters:
        pid - The property ID
        Returns:
        The well-known property ID string associated with the property ID pid

      • clear

        public void clear()
        Removes all properties from the section including 0 (dictionary) and 1 (codepage).

      • equals

        public boolean equals​(java.lang.Object o)
        Checks whether this section is equal to another object. The result is false if one of the the following conditions holds:
        • The other object is not a Section.
        • The format IDs of the two sections are not equal.
        • The sections have a different number of properties. However, properties with ID 1 (codepage) are not counted.
        • The other object is not a Section.
        • The properties have different values. The order of the properties is irrelevant.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - The object to compare this section with
        Returns:
        true if the objects are equal, false if not

      • removeProperty

        public void removeProperty​(long id)
        Removes a property.
        Parameters:
        id - The ID of the property to be removed

      • write

        public int write​(java.io.OutputStream out)
          throws WritingNotSupportedException,
                 java.io.IOException
        Writes this section into an output stream.

        Internally this is done by writing into three byte array output streams: one for the properties, one for the property list and one for the section as such. The two former are appended to the latter when they have received all their data.

        Parameters:
        out - The stream to write into.
        Returns:
        The number of bytes written, i.e. the section's size.
        Throws:
        java.io.IOException - if an I/O error occurs
        WritingNotSupportedException - if HPSF does not yet support writing a property's variant type.

      • setDictionary

        public void setDictionary​(java.util.Map<java.lang.Long,​java.lang.String> dictionary)
                   throws IllegalPropertySetDataException
        Sets the section's dictionary. All keys in the dictionary must be Long instances, all values must be Strings. This method overwrites the properties with IDs 0 and 1 since they are reserved for the dictionary and the dictionary's codepage. Setting these properties explicitly might have surprising effects. An application should never do this but always use this method.
        Parameters:
        dictionary - The dictionary
        Throws:
        IllegalPropertySetDataException - if the dictionary's key and value types are not correct.
        See Also:
        getDictionary()

      • hashCode

        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()

      • toString

        public java.lang.String toString​(PropertyIDMap idMap)

      • getDictionary

        public java.util.Map<java.lang.Long,​java.lang.String> getDictionary()
        Gets the section's dictionary. A dictionary allows an application to use human-readable property names instead of numeric property IDs. It contains mappings from property IDs to their associated string values. The dictionary is stored as the property with ID 0. The codepage for the strings in the dictionary is defined by property with ID 1.
        Returns:
        the dictionary or null if the section does not have a dictionary.

      • getCodepage

        public int getCodepage()
        Gets the section's codepage, if any.
        Returns:
        The section's codepage if one is defined, else -1.

      • setCodepage

        public void setCodepage​(int codepage)
        Sets the codepage.
        Parameters:
        codepage - the codepage