Class PropertySet
- Direct Known Subclasses:
DocumentSummaryInformation,SummaryInformation
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 Sections, and each
Section has a Property array. Use getSections() to retrieve the Sections, then call Section.getProperties() for each Section to get hold of the
Property arrays.
Since the vast majority of PropertySets 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
FieldsModifier and TypeFieldDescriptionstatic final intIf the OS version field holds this value the property set stream was created on a Macintosh system.static final intIf the OS version field holds this value the property set stream was created on a 16-bit Windows system.static final intIf the OS version field holds this value the property set stream was created on a 32-bit Windows system. -
Constructor Summary
ConstructorsConstructorDescriptionConstructs aPropertySetinstance.PropertySet(byte[] stream) Creates aPropertySetinstance from a byte array that represents a stream in the Horrible Property Set Format.PropertySet(byte[] stream, int offset, int length) Creates aPropertySetinstance from a byte array that represents a stream in the Horrible Property Set Format.PropertySet(InputStream stream) Creates aPropertySetinstance from anInputStreamin the Horrible Property Set Format.Constructs aPropertySetby doing a deep copy of an existingPropertySet. -
Method Summary
Modifier and TypeMethodDescriptionvoidaddSection(Section section) Adds a section to this property set.voidRemoves all sections from this property set.booleanReturnstrueif thePropertySetis equal to the specified parameter, elsefalse.intGets thePropertySet's first section.intintProperty[]Convenience method returning thePropertyarray contained in this property set.protected ObjectgetProperty(int id) Convenience method returning the value of the property with the specified ID.The id to name mapping of the properties in this set.static StringgetPropertyStringValue(Object propertyValue) Return the string representation of a property valueintDeprecated.superfluous convenience methodinthashCode()booleanChecks whether thisPropertySetis a Document Summary Information.static booleanisPropertySetStream(byte[] src, int offset, int length) Checks whether a byte array is in the Horrible Property Set Format.static booleanisPropertySetStream(InputStream stream) Checks whether anInputStreamis in the Horrible Property Set Format.booleanChecks whether thisPropertySetrepresents a Summary Information.voidsetByteOrder(int byteOrder) Returns the property set stream's low-level "byte order" field.voidsetClassID(ClassID classID) Sets the property set stream's low-level "class ID" field.voidsetFormat(int format) Sets the property set stream's low-level "format" field.voidsetOSVersion(int osVersion) Sets the property set stream's low-level "OS version" field.Returns the contents of this property set stream as an input stream.toString()booleanwasNull()Checks whether the property which the last call togetPropertyIntValue(int)orgetProperty(int)tried to access was available or not.voidwrite(OutputStream out) Writes the property set to an output stream.voidwrite(DirectoryEntry dir, String name) Writes a property set to a document in a POI filesystem directory.
-
Field Details
-
OS_WIN16
public static final int OS_WIN16If the OS version field holds this value the property set stream was created on a 16-bit Windows system.- See Also:
-
OS_MACINTOSH
public static final int OS_MACINTOSHIf the OS version field holds this value the property set stream was created on a Macintosh system.- See Also:
-
OS_WIN32
public static final int OS_WIN32If the OS version field holds this value the property set stream was created on a 32-bit Windows system.- See Also:
-
-
Constructor Details
-
PropertySet
public PropertySet()Constructs aPropertySetinstance. Its primary task is to initialize the field with their proper values. It also sets fields that might change to reasonable defaults. -
PropertySet
Creates aPropertySetinstance from anInputStreamin 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:
IOException- if theInputStreamcannot be accessed as needed.NoPropertySetStreamException- if the input stream does not contain a property set.UnsupportedEncodingException- if a character encoding is not supported.
-
PropertySet
public PropertySet(byte[] stream, int offset, int length) throws NoPropertySetStreamException, UnsupportedEncodingException Creates aPropertySetinstance 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 instreamwhere the stream data begin. If the stream data begin with the first byte in the array, theoffsetis 0.length- The length of the stream data.- Throws:
NoPropertySetStreamException- if the byte array is not a property set stream.UnsupportedEncodingException- if the codepage is not supported.
-
PropertySet
Creates aPropertySetinstance 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.UnsupportedEncodingException- if the codepage is not supported.
-
PropertySet
Constructs aPropertySetby doing a deep copy of an existingPropertySet. All nested elements, i.e.Sections andPropertyinstances, will be their counterparts in the newPropertySet.- Parameters:
ps- The property set to copy
-
-
Method Details
-
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
- Returns:
- The property set stream's low-level "class ID" field.
-
setClassID
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
Sections in the property set.
-
getSections
- Returns:
- The unmodifiable list of
Sections in the property set.
-
addSection
Adds a section to this property set.- Parameters:
section- TheSectionto 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
The id to name mapping of the properties in this set.- Returns:
- the id to name mapping of the properties in this set or
nullif not applicable
-
isPropertySetStream
Checks whether anInputStreamis in the Horrible Property Set Format.- Parameters:
stream- TheInputStreamto 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. TheInputStreammust support theInputStream.mark(int)method.- Returns:
trueif the stream is a property set stream, elsefalse.- Throws:
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:
trueif the byte array is a property set stream,falseif not.
-
write
Writes the property set to an output stream.- Parameters:
out- the output stream to write the section to- Throws:
IOException- if an error when writing to the output stream occursWritingNotSupportedException- if HPSF does not yet support writing a property's variant type.
-
write
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 writingIOException- if the old entry can't be deleted or the new entry be written
-
toInputStream
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 thePropertySetonly.- Returns:
- the contents of this property set stream
- Throws:
WritingNotSupportedException- if HPSF does not yet support writing of a property's variant type.IOException- if an I/O exception occurs.
-
getPropertyStringValue
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 thisPropertySetrepresents a Summary Information.- Returns:
trueif thisPropertySetrepresents a Summary Information, elsefalse.
-
isDocumentSummaryInformation
public boolean isDocumentSummaryInformation()Checks whether thisPropertySetis a Document Summary Information.- Returns:
trueif thisPropertySetrepresents a Document Summary Information, elsefalse.
-
getProperties
Convenience method returning thePropertyarray contained in this property set. It is a shortcut for getting hePropertySet'sSections list and then getting thePropertyarray from the firstSection.- Returns:
- The properties of the only
Sectionof thisPropertySet. - Throws:
NoSingleSectionException- if thePropertySethas more or less than oneSection.
-
getProperty
Convenience method returning the value of the property with the specified ID. If the property is not available,nullis returned and a subsequent call towasNull()will returntrue.- Parameters:
id- The property ID- Returns:
- The property value
- Throws:
NoSingleSectionException- if thePropertySethas more or less than oneSection.
-
wasNull
Checks whether the property which the last call togetPropertyIntValue(int)orgetProperty(int)tried to access was available or not. This information might be important for callers ofgetPropertyIntValue(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:
trueif the last call togetPropertyIntValue(int)orgetProperty(int)tried to access a property that was not available, elsefalse.- Throws:
NoSingleSectionException- if thePropertySethas more than oneSection.
-
getFirstSection
Gets thePropertySet's first section.- Returns:
- The
PropertySet's first section.
-
getSingleSection
Deprecated.superfluous convenience methodIf thePropertySethas only a single section this method returns it.- Returns:
- The singleSection value
-
equals
Returnstrueif thePropertySetis equal to the specified parameter, elsefalse. -
hashCode
-
toString
-