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 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
FieldsModifier and TypeFieldDescriptionstatic final int
If the OS version field holds this value the property set stream was created on a Macintosh system.static final int
If the OS version field holds this value the property set stream was created on a 16-bit Windows system.static final int
If the OS version field holds this value the property set stream was created on a 32-bit Windows system. -
Constructor Summary
ConstructorsConstructorDescriptionConstructs aPropertySet
instance.PropertySet
(byte[] stream) Creates aPropertySet
instance from a byte array that represents a stream in the Horrible Property Set Format.PropertySet
(byte[] stream, int offset, int length) Creates aPropertySet
instance from a byte array that represents a stream in the Horrible Property Set Format.PropertySet
(InputStream stream) Creates aPropertySet
instance from anInputStream
in the Horrible Property Set Format.Constructs aPropertySet
by doing a deep copy of an existingPropertySet
. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addSection
(Section section) Adds a section to this property set.void
Removes all sections from this property set.boolean
Returnstrue
if thePropertySet
is equal to the specified parameter, elsefalse
.int
Gets thePropertySet
's first section.int
int
Property[]
Convenience method returning theProperty
array contained in this property set.protected Object
getProperty
(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 String
getPropertyStringValue
(Object propertyValue) Return the string representation of a property valueint
Deprecated.superfluous convenience methodint
hashCode()
boolean
Checks whether thisPropertySet
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
(InputStream stream) Checks whether anInputStream
is in the Horrible Property Set Format.boolean
Checks whether thisPropertySet
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.Returns the contents of this property set stream as an input stream.toString()
boolean
wasNull()
Checks whether the property which the last call togetPropertyIntValue(int)
orgetProperty(int)
tried to access was available or not.void
write
(OutputStream out) Writes the property set to an output stream.void
write
(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 aPropertySet
instance. Its primary task is to initialize the field with their proper values. It also sets fields that might change to reasonable defaults. -
PropertySet
Creates aPropertySet
instance from anInputStream
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:
IOException
- if theInputStream
cannot 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 aPropertySet
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 instream
where the stream data begin. If the stream data begin with the first byte in the array, theoffset
is 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 aPropertySet
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.UnsupportedEncodingException
- if the codepage is not supported.
-
PropertySet
Constructs aPropertySet
by doing a deep copy of an existingPropertySet
. All nested elements, i.e.Section
s andProperty
instances, 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
Section
s in the property set.
-
getSections
- Returns:
- The unmodifiable list of
Section
s in the property set.
-
addSection
Adds a section to this property set.- Parameters:
section
- TheSection
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
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
Checks whether anInputStream
is in the Horrible Property Set Format.- Parameters:
stream
- TheInputStream
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. TheInputStream
must support theInputStream.mark(int)
method.- Returns:
true
if 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:
true
if the byte array is a property set stream,false
if 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 thePropertySet
only.- 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 thisPropertySet
represents a Summary Information.- Returns:
true
if thisPropertySet
represents a Summary Information, elsefalse
.
-
isDocumentSummaryInformation
public boolean isDocumentSummaryInformation()Checks whether thisPropertySet
is a Document Summary Information.- Returns:
true
if thisPropertySet
represents a Document Summary Information, elsefalse
.
-
getProperties
Convenience method returning theProperty
array contained in this property set. It is a shortcut for getting hePropertySet
'sSection
s list and then getting theProperty
array from the firstSection
.- Returns:
- The properties of the only
Section
of thisPropertySet
. - Throws:
NoSingleSectionException
- if thePropertySet
has more or less than oneSection
.
-
getProperty
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 towasNull()
will returntrue
.- Parameters:
id
- The property ID- Returns:
- The property value
- Throws:
NoSingleSectionException
- if thePropertySet
has 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:
true
if the last call togetPropertyIntValue(int)
orgetProperty(int)
tried to access a property that was not available, elsefalse
.- Throws:
NoSingleSectionException
- if thePropertySet
has more than oneSection
.
-
getFirstSection
Gets thePropertySet
's first section.- Returns:
- The
PropertySet
's first section.
-
getSingleSection
Deprecated.superfluous convenience methodIf thePropertySet
has only a single section this method returns it.- Returns:
- The singleSection value
-
equals
Returnstrue
if thePropertySet
is equal to the specified parameter, elsefalse
. -
hashCode
-
toString
-