moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

Javadoc updates: Removed some autogenerated comments and

Browse Source 
added my own ones.


git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352819 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Rainer Klute 2002-07-30 14:56:02 +00:00
parent 6304b81aa3
commit fe2a12a53b
2 changed files with 362 additions and 448 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

595
src/java/org/apache/poi/hpsf/PropertySet.java
View File

@ -56,292 +56,301 @@ package org.apache.poi.hpsf;
import java.io.*; import java.io.*;
import java.util.*; import java.util.*;
import org.apache.poi.util.LittleEndian;
import org.apache.poi.hpsf.wellknown.*; import org.apache.poi.hpsf.wellknown.*;
import org.apache.poi.poifs.filesystem.*; import org.apache.poi.poifs.filesystem.*;
import org.apache.poi.util.LittleEndian;
/** /**
* <p> * <p>Represents a property set in the Horrible Property Set Format
* (HPSF). These are usually metadata of a Microsoft Office
* document.</p>
* *
* Represents a property set in the Horrible Property Set Format (HPSF). These * <p>An application that wants to access these metadata should create
* are usually metadata of a Microsoft Office document.</p> <p> * an instance of this class or one of its subclasses by calling the
* factory method {@link PropertySetFactory#create} and then retrieve
* the information its needs by calling appropriate methods.</p>
* *
* An application that wants to access these metadata should create an instance * <p>{@link PropertySetFactory#create} does its work by calling one
* of this class or one of its subclasses by calling the factory method {@link * of the constructors {@link PropertySet#PropertySet(InputStream)} or
* PropertySetFactory#create} and then retrieve the information its needs by * {@link PropertySet#PropertySet(byte[])}. If the constructor's
* calling appropriate methods.</p> <p> * 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.</p>
* *
* {@link PropertySetFactory#create} does its work by calling one of the * <p>A {@link PropertySet} has a list of {@link Section}s, and each
* constructors {@link PropertySet#PropertySet(InputStream)} or {@link * {@link Section} has a {@link Property} array. Use {@link
* PropertySet#PropertySet(byte[])}. If the constructor's argument is not in * #getSections} to retrieve the {@link Section}s, then call {@link
* the Horrible Property Set Format, i.e. not a property set stream, or if any * Section#getProperties} for each {@link Section} to get hold of the
* other error occurs, an appropriate exception is thrown.</p> <p> * {@link Property} arrays.</p> Since the vast majority of {@link
* PropertySet}s contains only a single {@link Section}, the
* convenience method {@link #getProperties} returns the properties of
* a {@link PropertySet}'s {@link Section} (throwing a {@link
* NoSingleSectionException} if the {@link PropertySet} contains more
* (or less) than exactly one {@link Section}).</p>
* *
* A {@link PropertySet} has a list of {@link Section}s, and each {@link * @author Rainer Klute (klute@rainer-klute.de)
* Section} has a {@link Property} array. Use {@link #getSections} to retrieve * @author Drew Varner (Drew.Varner hanginIn sc.edu)
* the {@link Section}s, then call {@link Section#getProperties} for each * @version $Id$
* {@link Section} to get hold of the {@link Property} arrays.</p> Since the * @since 2002-02-09
* vast majority of {@link PropertySet}s contains only a single {@link
* Section}, the convenience method {@link #getProperties} returns the
* properties of a {@link PropertySet}'s {@link Section} (throwing a {@link
* NoSingleSectionException} if the {@link PropertySet} contains more (or less)
* than exactly one {@link Section}).
*
*@author Rainer Klute (klute@rainer-klute.de)
*@author Drew Varner (Drew.Varner hanginIn sc.edu)
*@created May 10, 2002
*@version $Id$
*@since 2002-02-09
*/ */
public class PropertySet { public class PropertySet
final static byte[] BYTE_ORDER_ASSERTION = {
new byte[]{(byte) 0xFE, (byte) 0xFF};
final static byte[] FORMAT_ASSERTION =
new byte[]{(byte) 0x00, (byte) 0x00};
private int byteOrder;
// Must equal BYTE_ORDER_ASSERTION
/** /**
* <p> * <p>The "byteOrder" field must equal this value.</p>
*
* Returns the property set stream's low-level "byte order" field. It is
* always <tt>0xFFFE</tt> .</p>
*
*@return The byteOrder value
*/ */
public int getByteOrder() { final static byte[] BYTE_ORDER_ASSERTION =
new byte[]{(byte) 0xFE, (byte) 0xFF};
/**
* <p>The "format" field must equal this value.</p>
*/
final static byte[] FORMAT_ASSERTION =
new byte[]{(byte) 0x00, (byte) 0x00};
/**
* <p>Specifies this {@link PropertySet}'s byte order. See the
* HPFS documentation for details!</p>
*/
private int byteOrder;
/**
* <p>Returns the property set stream's low-level "byte order"
* field. It is always <tt>0xFFFE</tt> .</p>
*
* @return The property set stream's low-level "byte order" field.
*/
public int getByteOrder()
{
return byteOrder; return byteOrder;
} }
/**
* <p>Specifies this {@link PropertySet}'s format. See the HPFS
* documentation for details!</p>
*/
private int format; private int format;
// Must equal FORMAT_ASSERTION
/** /**
* <p> * <p>Returns the property set stream's low-level "format"
* field. It is always <tt>0x0000</tt> .</p>
* *
* Returns the property set stream's low-level "format" field. It is always * @return The property set stream's low-level "format" field.
* <tt>0x0000</tt> .</p>
*
*@return The format value
*/ */
public int getFormat() { public int getFormat()
{
return format; return format;
} }
/**
* <p>Specifies the version of the operating system that created
* this {@link PropertySet}. See the HPFS documentation for
* details!</p>
*/
private long osVersion; private long osVersion;
/** /**
* <p> * <p>Returns the property set stream's low-level "OS version"
* field.</p>
* *
* Returns the property set stream's low-level "OS version" field.</p> * @return The property set stream's low-level "OS version" field.
*
*@return The oSVersion value
*/ */
public long getOSVersion() { public long getOSVersion()
{
return osVersion; return osVersion;
} }
/**
* <p>Specifies this {@link PropertySet}'s "classID" field. See
* the HPFS documentation for details!</p>
*/
private ClassID classID; private ClassID classID;
/** /**
* <p> * <p>Returns the property set stream's low-level "class ID"
* field.</p>
* *
* Returns the property set stream's low-level "class ID" field.</p> * @return The property set stream's low-level "class ID" field.
*
*@return The classID value
*/ */
public ClassID getClassID() { public ClassID getClassID()
{
return classID; return classID;
} }
/**
* <p>The number of sections in this {@link PropertySet}.</p>
*/
private long sectionCount; private long sectionCount;
/** /**
* <p> * <p>Returns the number of {@link Section}s in the property
* set.</p>
* *
* Returns the number of {@link Section}s in the property set.</p> * @return The number of {@link Section}s in the property set.
*
*@return The sectionCount value
*/ */
public long getSectionCount() { public long getSectionCount()
{
return sectionCount; return sectionCount;
} }
/**
* <p>The sections in this {@link PropertySet}.</p>
*/
private List sections; private List sections;
/** /**
* <p> * <p>Returns the {@link Section}s in the property set.</p>
* *
* Returns the {@link Section}s in the property set.</p> * @return The {@link Section}s in the property set.
*
*@return The sections value
*/ */
public List getSections() { public List getSections()
{
return sections; return sections;
} }
/** /**
* <p> * <p>Creates an empty (uninitialized) {@link PropertySet}.</p>
* *
* Creates an empty (uninitialized) {@link PropertySet}.</p> <p> * <p><strong>Please note:</strong> For the time being this
* * constructor is protected since it is used for internal purposes
* <strong>Please note:</strong> For the time being this constructor is * only, but expect it to become public once the property set's
* protected since it is used for internal purposes only, but expect it to * writing functionality is implemented.</p>
* become public once the property set writing functionality is
* implemented.</p>
*/ */
protected PropertySet() { } protected PropertySet()
{}
/** /**
* <p> * <p>Creates a {@link PropertySet} instance from an {@link
* InputStream} in the Horrible Property Set Format.</p>
* *
* Creates a {@link PropertySet} instance from an {@link InputStream} in * <p>The constructor reads the first few bytes from the stream
* the Horrible Property Set Format.</p> <p> * 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.</p>
* *
* The constructor reads the first few bytes from the stream and determines * @param stream Holds the data making out the property set
* whether it is really a property set stream. If it is, it parses the rest * stream.
* of the stream. If it is not, it resets the stream to its beginning in * @throws MarkUnsupportedException if the stream does not support
* order to let other components mess around with the data and throws an * the {@link InputStream#markSupported} method.
* exception.</p> * @throws IOException if the {@link InputStream} cannot not be
* * accessed as needed.
*@param stream Description of the Parameter
*@exception NoPropertySetStreamException Description of the Exception
*@exception MarkUnsupportedException Description of the Exception
*@exception IOException Description of the Exception
*@throws NoPropertySetStreamException if the stream is not a property
* set stream.
*@throws MarkUnsupportedException if the stream does not support
* the {@link InputStream#markSupported} method.
*@throws IOException if the {@link InputStream}
* cannot not be accessed as needed.
*/ */
public PropertySet(final InputStream stream) public PropertySet(final InputStream stream)
throws NoPropertySetStreamException, MarkUnsupportedException, throws NoPropertySetStreamException, MarkUnsupportedException,
IOException { IOException
if (isPropertySetStream(stream)) { {
if (isPropertySetStream(stream))
{
final int avail = stream.available(); final int avail = stream.available();
final byte[] buffer = new byte[avail]; final byte[] buffer = new byte[avail];
stream.read(buffer, 0, buffer.length); stream.read(buffer, 0, buffer.length);
init(buffer, 0, buffer.length); init(buffer, 0, buffer.length);
} else {
throw new NoPropertySetStreamException();
} }
else
throw new NoPropertySetStreamException();
} }
/** /**
* <p> * <p>Creates a {@link PropertySet} instance from a byte array
* that represents a stream in the Horrible Property Set
* Format.</p>
* *
* Creates a {@link PropertySet} instance from a byte array that represents * @param stream The byte array holding the stream data.
* a stream in the Horrible Property Set Format.</p> * @param offset The offset in <var>stream</var> where the stream
* * data begin. If the stream data begin with the first byte in the
*@param stream The byte array holding the * array, the <var>offset</var> is 0.
* stream data. * @param length The length of the stream data.
*@param offset The offset in <var>stream</var> * @throws NoPropertySetStreamException if the byte array is not a
* where the stream data begin. If the stream data begin with the first * property set stream.
* byte in the array, the <var>offset</var> is 0.
*@param length The length of the stream data.
*@exception NoPropertySetStreamException Description of the Exception
*@throws NoPropertySetStreamException if the byte array is not a
* property set stream.
*/ */
public PropertySet(final byte[] stream, final int offset, final int length) public PropertySet(final byte[] stream, final int offset, final int length)
throws NoPropertySetStreamException { throws NoPropertySetStreamException
if (isPropertySetStream(stream, offset, length)) { {
if (isPropertySetStream(stream, offset, length))
init(stream, offset, length); init(stream, offset, length);
} else { else
throw new NoPropertySetStreamException(); throw new NoPropertySetStreamException();
}
} }
/** /**
* <p> * <p>Creates a {@link PropertySet} instance from a byte array
* that represents a stream in the Horrible Property Set
* Format.</p>
* *
* Creates a {@link PropertySet} instance from a byte array that represents * @param stream The byte array holding the stream data. The
* a stream in the Horrible Property Set Format.</p> * complete byte array contents is the stream data.
* * @throws NoPropertySetStreamException if the byte array is not a
*@param stream The byte array holding the * property set stream.
* stream data. The complete byte array contents is the stream data.
*@exception NoPropertySetStreamException Description of the Exception
*@throws NoPropertySetStreamException if the byte array is not a
* property set stream.
*/ */
public PropertySet(final byte[] stream) public PropertySet(final byte[] stream) throws NoPropertySetStreamException
throws NoPropertySetStreamException { {
this(stream, 0, stream.length); this(stream, 0, stream.length);
} }
/** /**
* <p> * <p>Checks whether an {@link InputStream} is in the Horrible
* Property Set Format.</p>
* *
* Checks whether an {@link InputStream} is in the Horrible Property Set * @param stream The {@link InputStream} to check. In order to
* Format.</p> * perform the check, the method reads the first bytes from the
* * stream. After reading, the stream is reset to the position it
*@param stream The {@link InputStream} to check. In * had before reading. The {@link InputStream} must support the
* order to perform the check, the method reads the first bytes from * {@link InputStream#mark} method.
* the stream. After reading, the stream is reset to the position it * @return <code>true</code> if the stream is a property set
* had before reading. The {@link InputStream} must support the {@link * stream, else <code>false</code>.
* InputStream#mark} method. * @throws MarkUnsupportedException if the {@link InputStream}
*@return <code>true</code> if the stream is a * does not support the {@link InputStream#mark} method.
* property set stream, else <code>false</code>.
*@exception IOException Description of the Exception
*@throws MarkUnsupportedException if the {@link InputStream} does not
* support the {@link InputStream#mark} method.
*/ */
public static boolean isPropertySetStream(final InputStream stream) public static boolean isPropertySetStream(final InputStream stream)
throws MarkUnsupportedException, IOException { throws MarkUnsupportedException, IOException
{
/* /*
* Read at most this many bytes. * Read at most this many bytes.
*/ */
final int BUFFER_SIZE = 50; final int BUFFER_SIZE = 50;
/* /*
* Mark the current position in the stream so that we can * Mark the current position in the stream so that we can
* reset to this position if the stream does not contain a * reset to this position if the stream does not contain a
* property set. * property set.
*/ */
if (!stream.markSupported()) { if (!stream.markSupported())
throw new MarkUnsupportedException(stream.getClass().getName()); throw new MarkUnsupportedException(stream.getClass().getName());
} stream.mark(BUFFER_SIZE);
stream.mark(BUFFER_SIZE);
/* /*
* Read a couple of bytes from the stream. * Read a couple of bytes from the stream.
*/ */
final byte[] buffer = new byte[BUFFER_SIZE]; final byte[] buffer = new byte[BUFFER_SIZE];
final int bytes = final int bytes =
stream.read(buffer, 0, stream.read(buffer, 0,
Math.min(buffer.length, stream.available())); Math.min(buffer.length, stream.available()));
final boolean isPropertySetStream = final boolean isPropertySetStream =
isPropertySetStream(buffer, 0, bytes); isPropertySetStream(buffer, 0, bytes);
stream.reset(); stream.reset();
return isPropertySetStream; return isPropertySetStream;
} }
@ -349,66 +358,63 @@ public class PropertySet {
/** /**
* <p> * <p>Checks whether a byte array is in the Horrible Property Set
* Format.</p>
* *
* Checks whether a byte array is in the Horrible Property Set Format.</p> * @param src The byte array to check.
* * @param offset The offset in the byte array.
*@param src The byte array to check. * @param length The significant number of bytes in the byte
*@param offset The offset in the byte array. * array. Only this number of bytes will be checked.
*@param length The significant number of bytes in the byte array. Only * @return <code>true</code> if the byte array is a property set
* this number of bytes will be checked. * stream, <code>false</code> if not.
*@return <code>true</code> if the byte array is a property set
* stream, <code>false</code> if not.
*/ */
public static boolean isPropertySetStream(final byte[] src, int offset, public static boolean isPropertySetStream(final byte[] src, int offset,
final int length) { final int length)
{
/* /*
* Read the header fields of the stream. They must always be * Read the header fields of the stream. They must always be
* there. * there.
*/ */
final int byteOrder = LittleEndian.getUShort(src, offset); final int byteOrder = LittleEndian.getUShort(src, offset);
offset += LittleEndian.SHORT_SIZE; offset += LittleEndian.SHORT_SIZE;
byte[] temp = new byte[LittleEndian.SHORT_SIZE]; byte[] temp = new byte[LittleEndian.SHORT_SIZE];
LittleEndian.putShort(temp,(short)byteOrder); LittleEndian.putShort(temp,(short)byteOrder);
if (!Util.equal(temp, BYTE_ORDER_ASSERTION)) { if (!Util.equal(temp, BYTE_ORDER_ASSERTION))
return false; return false;
} final int format = LittleEndian.getUShort(src, offset);
final int format = LittleEndian.getUShort(src, offset);
offset += LittleEndian.SHORT_SIZE; offset += LittleEndian.SHORT_SIZE;
temp = new byte[LittleEndian.SHORT_SIZE]; temp = new byte[LittleEndian.SHORT_SIZE];
LittleEndian.putShort(temp,(short)format); LittleEndian.putShort(temp,(short)format);
if (!Util.equal(temp, FORMAT_ASSERTION)) { if (!Util.equal(temp, FORMAT_ASSERTION))
return false; return false;
} final long osVersion = LittleEndian.getUInt(src, offset);
final long osVersion = LittleEndian.getUInt(src, offset);
offset += LittleEndian.INT_SIZE; offset += LittleEndian.INT_SIZE;
final ClassID classID = new ClassID(src, offset); final ClassID classID = new ClassID(src, offset);
offset += ClassID.LENGTH; offset += ClassID.LENGTH;
final long sectionCount = LittleEndian.getUInt(src, offset); final long sectionCount = LittleEndian.getUInt(src, offset);
offset += LittleEndian.INT_SIZE; offset += LittleEndian.INT_SIZE;
if (sectionCount < 1) { if (sectionCount < 1)
return false; return false;
} return true;
return true;
} }
/** /**
* <p> * <p>Initializes this {@link PropertySet} instance from a byte
* array. The method assumes that it has been checked already that
* the byte array indeed represents a property set stream. It does
* no more checks on its own.</p>
* *
* Initializes this {@link PropertySet} instance from a byte array. The * @param src Byte array containing the property set stream
* method assumes that it has been checked already that the byte array * @param offset The property set stream starts at this offset
* indeed represents a property set stream. It does no more checks on its * from the beginning of <var>src</src>
* own.</p> * @param length Length of the property set stream.
*
*@param src Description of the Parameter
*@param offset Description of the Parameter
*@param length Description of the Parameter
*/ */
private void init(final byte[] src, int offset, final int length) { private void init(final byte[] src, int offset, final int length)
{
/* /*
* Read the stream's header fields. * Read the stream's header fields.
*/ */
byteOrder = LittleEndian.getUShort(src, offset); byteOrder = LittleEndian.getUShort(src, offset);
offset += LittleEndian.SHORT_SIZE; offset += LittleEndian.SHORT_SIZE;
@ -422,25 +428,26 @@ public class PropertySet {
offset += LittleEndian.INT_SIZE; offset += LittleEndian.INT_SIZE;
/* /*
* Read the sections, which are following the header. They * Read the sections, which are following the header. They
* start with an array of section descriptions. Each one * start with an array of section descriptions. Each one
* consists of a format ID telling what the section contains * consists of a format ID telling what the section contains
* and an offset telling how many bytes from the start of the * and an offset telling how many bytes from the start of the
* stream the section begins. * stream the section begins.
*/ */
/* /*
* Most property sets have only one section. The Document * Most property sets have only one section. The Document
* Summary Information stream has 2. Everything else is a rare * Summary Information stream has 2. Everything else is a rare
* exception and is no longer fostered by Microsoft. * exception and is no longer fostered by Microsoft.
*/ */
sections = new ArrayList(2); sections = new ArrayList(2);
/* /*
* Loop over the section descriptor array. Each descriptor * Loop over the section descriptor array. Each descriptor
* consists of a ClassID and a DWord, and we have to increment * consists of a ClassID and a DWord, and we have to increment
* "offset" accordingly. * "offset" accordingly.
*/ */
for (int i = 0; i < sectionCount; i++) { for (int i = 0; i < sectionCount; i++)
{
final Section s = new Section(src, offset); final Section s = new Section(src, offset);
offset += ClassID.LENGTH + LittleEndian.INT_SIZE; offset += ClassID.LENGTH + LittleEndian.INT_SIZE;
sections.add(s); sections.add(s);
@ -450,156 +457,152 @@ public class PropertySet {
/** /**
* <p> * <p>Checks whether this {@link PropertySet} represents a Summary
* Information.</p>
* *
* Checks whether this {@link PropertySet} represents a Summary * @return <code>true</code> if this {@link PropertySet}
* Information.</p> * represents a Summary Information, else <code>false</code>.
*
*@return The summaryInformation value
*/ */
public boolean isSummaryInformation() { public boolean isSummaryInformation()
{
return Util.equal(((Section) sections.get(0)).getFormatID().getBytes(), return Util.equal(((Section) sections.get(0)).getFormatID().getBytes(),
SectionIDMap.SUMMARY_INFORMATION_ID); SectionIDMap.SUMMARY_INFORMATION_ID);
} }
/** /**
* <p> * <p>Checks whether this {@link PropertySet} is a Document
* Summary Information.</p>
* *
* Checks whether this {@link PropertySet} is a Document Summary * @return <code>true</code> if this {@link PropertySet}
* Information.</p> * represents a Document Summary Information, else <code>false</code>.
*
*@return The documentSummaryInformation value
*/ */
public boolean isDocumentSummaryInformation() { public boolean isDocumentSummaryInformation()
{
return Util.equal(((Section) sections.get(0)).getFormatID().getBytes(), return Util.equal(((Section) sections.get(0)).getFormatID().getBytes(),
SectionIDMap.DOCUMENT_SUMMARY_INFORMATION_ID); SectionIDMap.DOCUMENT_SUMMARY_INFORMATION_ID);
} }
/** /**
* <p> * <p>Convenience method returning the {@link Property} array
* contained in this property set. It is a shortcut for getting
* the {@link PropertySet}'s {@link Section}s list and then
* getting the {@link Property} array from the first {@link
* Section}. However, it can only be used if the {@link
* PropertySet} contains exactly one {@link Section}, so check
* {@link #getSectionCount} first!</p>
* *
* Convenience method returning the {@link Property} array contained in * @return The properties of the only {@link Section} of this
* this property set. It is a shortcut for getting the {@link * {@link PropertySet}.
* PropertySet}'s {@link Section}s list and then getting the {@link * @throws NoSingleSectionException if the {@link PropertySet} has
* Property} array from the first {@link Section}. However, it can only be * more or less than one {@link Section}.
* used if the {@link PropertySet} contains exactly one {@link Section}, so
* check {@link #getSectionCount} first!</p>
*
*@return The properties of the only {@link
* Section} of this {@link PropertySet}.
*@throws NoSingleSectionException if the {@link PropertySet} has more or
* less than one {@link Section}.
*/ */
public Property[] getProperties() public Property[] getProperties()
throws NoSingleSectionException { throws NoSingleSectionException
{
return getSingleSection().getProperties(); return getSingleSection().getProperties();
} }
/** /**
* <p> * <p>Convenience method returning the value of the property with
* the specified ID. If the property is not available,
* <code>null</code> is returned and a subsequent call to {@link
* #wasNull} will return <code>true</code> .</p>
* *
* Convenience method returning the value of the property with the * @param id The property ID
* specified ID. If the property is not available, <code>null</code> is * @return The property value
* returned and a subsequent call to {@link #wasNull} will return <code>true</code> * @throws NoSingleSectionException if the {@link PropertySet} has
* .</p> * more or less than one {@link Section}.
*
*@param id Description of the Parameter
*@return The property value
*@throws NoSingleSectionException if the {@link PropertySet} has more or
* less than one {@link Section}.
*/ */
protected Object getProperty(final int id) protected Object getProperty(final int id) throws NoSingleSectionException
throws NoSingleSectionException { {
return getSingleSection().getProperty(id); return getSingleSection().getProperty(id);
} }
/** /**
* <p> * <p>Convenience method returning the value of a boolean property
* with the specified ID. If the property is not available,
* <code>false</code> is returned. A subsequent call to {@link
* #wasNull} will return <code>true</code> to let the caller
* distinguish that case from a real property value of
* <code>false</code>.</p>
* *
* Convenience method returning the value of a boolean property with the * @param id The property ID
* specified ID. If the property is not available, <code>false</code> is * @return The property value
* returned. A subsequent call to {@link #wasNull} will return <code>true</code> * @throws NoSingleSectionException if the {@link PropertySet} has
* to let the caller distinguish that case from a real property value of * more or less than one {@link Section}.
* <code>false</code>.</p>
*
*@param id Description of the Parameter
*@return The propertyBooleanValue value
*@throws NoSingleSectionException if the {@link PropertySet} has more or
* less than one {@link Section}.
*/ */
protected boolean getPropertyBooleanValue(final int id) protected boolean getPropertyBooleanValue(final int id)
throws NoSingleSectionException { throws NoSingleSectionException
{
return getSingleSection().getPropertyBooleanValue(id); return getSingleSection().getPropertyBooleanValue(id);
} }
/** /**
* <p> * <p>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 {@link #wasNull}
* will return <code>true</code> to let the caller distinguish
* that case from a real property value of 0.</p>
* *
* Convenience method returning the value of the numeric property with the * @param id The property ID
* specified ID. If the property is not available, 0 is returned. A * @return The propertyIntValue value
* subsequent call to {@link #wasNull} will return <code>true</code> to let * @throws NoSingleSectionException if the {@link PropertySet} has
* the caller distinguish that case from a real property value of 0.</p> * more or less than one {@link Section}.
*
*@param id Description of the Parameter
*@return The propertyIntValue value
*@throws NoSingleSectionException if the {@link PropertySet} has more or
* less than one {@link Section}.
*/ */
protected int getPropertyIntValue(final int id) protected int getPropertyIntValue(final int id)
throws NoSingleSectionException { throws NoSingleSectionException
{
return getSingleSection().getPropertyIntValue(id); return getSingleSection().getPropertyIntValue(id);
} }
/** /**
* <p> * <p>Checks whether the property which the last call to {@link
* #getPropertyIntValue} or {@link #getProperty} tried to access
* was available or not. This information might be important for
* callers of {@link #getPropertyIntValue} since the latter
* returns 0 if the property does not exist. Using {@link
* #wasNull}, the caller can distiguish this case from a
* property's real value of 0.</p>
* *
* Checks whether the property which the last call to {@link * @return <code>true</code> if the last call to {@link
* #getPropertyIntValue} or {@link #getProperty} tried to access was * #getPropertyIntValue} or {@link #getProperty} tried to access a
* available or not. This information might be important for callers of * property that was not available, else <code>false</code>.
* {@link #getPropertyIntValue} since the latter returns 0 if the property * @throws NoSingleSectionException if the {@link PropertySet} has
* does not exist. Using {@link #wasNull}, the caller can distiguish this * more than one {@link Section}.
* case from a property's real value of 0.</p>
*
*@return <code>true</code> if the last call to
* {@link #getPropertyIntValue} or {@link #getProperty} tried to access
* a property that was not available, else <code>false</code>.
*@throws NoSingleSectionException if the {@link PropertySet} has more
* than one {@link Section}.
*/ */
public boolean wasNull() throws NoSingleSectionException { public boolean wasNull() throws NoSingleSectionException
{
return getSingleSection().wasNull(); return getSingleSection().wasNull();
} }
/** /**
* <p> * <p>If the {@link PropertySet} has only a single section this
* method returns it.</p>
* *
* If the {@link PropertySet} has only a single section this method returns *@return The singleSection value
* it.</p> *@throws NoSingleSectionException if the {@link PropertySet} has
* *more or less than exactly one {@link Section}.
*@return The singleSection value
*@throws NoSingleSectionException if the {@link PropertySet} has more or
* less than exactly one {@link Section}.
*/ */
public Section getSingleSection() { public Section getSingleSection()
if (sectionCount != 1) { {
throw new NoSingleSectionException if (sectionCount != 1)
("Property set contains " + sectionCount + " sections."); throw new NoSingleSectionException
} ("Property set contains " + sectionCount + " sections.");
return ((Section) sections.get(0)); return ((Section) sections.get(0));
} }
} }

215
src/java/org/apache/poi/hpsf/wellknown/PropertyIDMap.java
View File

@ -57,222 +57,133 @@ package org.apache.poi.hpsf.wellknown;
import java.util.*; import java.util.*;
/** /**
* <p> * <p>This is a dictionary which maps property ID values to property
* ID strings.</p>
* *
* This is a dictionary mapping property IDs to property ID strings.</p> <p> * <p>The methods {@link #getSummaryInformationProperties} and {@link
* #getDocumentSummaryInformationProperties} return singleton {@link
* PropertyIDMap}s. An application that wants to extend these maps
* should treat them as unmodifiable, copy them and modifiy the
* copies.</p>
* *
* The methods {@link #getSummaryInformationProperties} and {@link * <p><strong>FIXME:</strong> Make the singletons
* #getDocumentSummaryInformationProperties} return singleton {@link * unmodifiable. However, since this requires to use a {@link HashMap}
* PropertyIDMap}s. An application that wants to extend these maps should treat * delegate instead of extending {@link HashMap} and thus requires a
* them as unmodifiable, copy them and modifiy the copies.</p> <p> * lot of stupid typing. I won't do that for the time being.</p>
* *
* <strong>FIXME:</strong> Make the singletons unmodifiable. However, since * @author Rainer Klute (klute@rainer-klute.de)
* this requires use a {@link HashMap} delegate instead of extending {@link * @version $Id$
* HashMap} and would require a lot of stupid typing, I won't do it for the * @since 2002-02-09
* time being.</p>
*
*@author Rainer Klute (klute@rainer-klute.de)
*@created May 10, 2002
*@version $Id$
*@since 2002-02-09
*/ */
public class PropertyIDMap extends HashMap { public class PropertyIDMap extends HashMap
{
/* /*
* The following definitions are for the Summary Information. * The following definitions are for the Summary Information.
*/
/**
* Description of the Field
*/ */
public final static int PID_TITLE = 2; public final static int PID_TITLE = 2;
/**
* Description of the Field
*/
public final static int PID_SUBJECT = 3; public final static int PID_SUBJECT = 3;
/**
* Description of the Field
*/
public final static int PID_AUTHOR = 4; public final static int PID_AUTHOR = 4;
/**
* Description of the Field
*/
public final static int PID_KEYWORDS = 5; public final static int PID_KEYWORDS = 5;
/**
* Description of the Field
*/
public final static int PID_COMMENTS = 6; public final static int PID_COMMENTS = 6;
/**
* Description of the Field
*/
public final static int PID_TEMPLATE = 7; public final static int PID_TEMPLATE = 7;
/**
* Description of the Field
*/
public final static int PID_LASTAUTHOR = 8; public final static int PID_LASTAUTHOR = 8;
/**
* Description of the Field
*/
public final static int PID_REVNUMBER = 9; public final static int PID_REVNUMBER = 9;
/**
* Description of the Field
*/
public final static int PID_EDITTIME = 10; public final static int PID_EDITTIME = 10;
/**
* Description of the Field
*/
public final static int PID_LASTPRINTED = 11; public final static int PID_LASTPRINTED = 11;
/**
* Description of the Field
*/
public final static int PID_CREATE_DTM = 12; public final static int PID_CREATE_DTM = 12;
/**
* Description of the Field
*/
public final static int PID_LASTSAVE_DTM = 13; public final static int PID_LASTSAVE_DTM = 13;
/**
* Description of the Field
*/
public final static int PID_PAGECOUNT = 14; public final static int PID_PAGECOUNT = 14;
/**
* Description of the Field
*/
public final static int PID_WORDCOUNT = 15; public final static int PID_WORDCOUNT = 15;
/**
* Description of the Field
*/
public final static int PID_CHARCOUNT = 16; public final static int PID_CHARCOUNT = 16;
/**
* Description of the Field
*/
public final static int PID_THUMBNAIL = 17; public final static int PID_THUMBNAIL = 17;
/**
* Description of the Field
*/
public final static int PID_APPNAME = 18; public final static int PID_APPNAME = 18;
/**
* Description of the Field
*/
public final static int PID_SECURITY = 19; public final static int PID_SECURITY = 19;
/* /*
* The following definitions are for the Document Summary Information. * The following definitions are for the Document Summary Information.
*/
/**
* Description of the Field
*/ */
public final static int PID_CATEGORY = 2; public final static int PID_CATEGORY = 2;
/**
* Description of the Field
*/
public final static int PID_PRESFORMAT = 3; public final static int PID_PRESFORMAT = 3;
/**
* Description of the Field
*/
public final static int PID_BYTECOUNT = 4; public final static int PID_BYTECOUNT = 4;
/**
* Description of the Field
*/
public final static int PID_LINECOUNT = 5; public final static int PID_LINECOUNT = 5;
/**
* Description of the Field
*/
public final static int PID_PARCOUNT = 6; public final static int PID_PARCOUNT = 6;
/**
* Description of the Field
*/
public final static int PID_SLIDECOUNT = 7; public final static int PID_SLIDECOUNT = 7;
/**
* Description of the Field
*/
public final static int PID_NOTECOUNT = 8; public final static int PID_NOTECOUNT = 8;
/**
* Description of the Field
*/
public final static int PID_HIDDENCOUNT = 9; public final static int PID_HIDDENCOUNT = 9;
/**
* Description of the Field
*/
public final static int PID_MMCLIPCOUNT = 10; public final static int PID_MMCLIPCOUNT = 10;
/**
* Description of the Field
*/
public final static int PID_SCALE = 11; public final static int PID_SCALE = 11;
/**
* Description of the Field
*/
public final static int PID_HEADINGPAIR = 12; public final static int PID_HEADINGPAIR = 12;
/**
* Description of the Field
*/
public final static int PID_DOCPARTS = 13; public final static int PID_DOCPARTS = 13;
/**
* Description of the Field
*/
public final static int PID_MANAGER = 14; public final static int PID_MANAGER = 14;
/**
* Description of the Field
*/
public final static int PID_COMPANY = 15; public final static int PID_COMPANY = 15;
/**
* Description of the Field
*/
public final static int PID_LINKSDIRTY = 16; public final static int PID_LINKSDIRTY = 16;
/**
* <p>Contains the summary information property ID values and
* associated strings. See the overall HPSF documentation for
* details!</p>
*/
private static PropertyIDMap summaryInformationProperties; private static PropertyIDMap summaryInformationProperties;
/**
* <p>Contains the summary information property ID values and
* associated strings. See the overall HPSF documentation for
* details!</p>
*/
private static PropertyIDMap documentSummaryInformationProperties; private static PropertyIDMap documentSummaryInformationProperties;
/** /**
* Constructor for the PropertyIDMap object * <p>Creates a {@link PropertyIDMap}.</p>
*
*@param initialCapacity Description of the Parameter
*@param loadFactor Description of the Parameter
*/ */
public PropertyIDMap(int initialCapacity, float loadFactor) { public PropertyIDMap(int initialCapacity, float loadFactor)
{
super(initialCapacity, loadFactor); super(initialCapacity, loadFactor);
} }
/** /**
* <p> * <p>Puts a ID string for an ID into the {@link
* PropertyIDMap}.</p>
* *
* Puts a ID string for an ID into the {@link PropertyIDMap}.</p> * @param id The ID.
* * @param idString The ID string.
*@param id The ID. * @return As specified by the {@link Map} interface, this method
*@param idString The ID string. * returns the previous value associated with the specified
*@return Description of the Return Value * <var>id</var>, or <code>null</code> if there was no mapping for
* key.
*/ */
public Object put(int id, String idString) { public Object put(int id, String idString)
{
return put(new Integer(id), idString); return put(new Integer(id), idString);
} }
/** /**
* <p> * <p>Gets the ID string for an ID from the {@link
* PropertyIDMap}.</p>
* *
* Gets the ID string for an ID from the {@link PropertyIDMap}.</p> * @param id The ID.
* * @return The ID string associated with <var>id</var>.
*@param id The ID.
*@return Description of the Return Value
*/ */
public Object get(int id) { public Object get(int id)
{
return get(new Integer(id)); return get(new Integer(id));
} }
/** /**
* <p> * <p>Returns the Summary Information properties singleton.</p>
*
* Returns the Summary Information properties singleton.</p>
*
*@return The summaryInformationProperties value
*/ */
public static PropertyIDMap getSummaryInformationProperties() { public static PropertyIDMap getSummaryInformationProperties()
if (summaryInformationProperties == null) { {
if (summaryInformationProperties == null)
{
PropertyIDMap m = new PropertyIDMap(17, (float) 1.0); PropertyIDMap m = new PropertyIDMap(17, (float) 1.0);
m.put(PID_TITLE, "PID_TITLE"); m.put(PID_TITLE, "PID_TITLE");
m.put(PID_SUBJECT, "PID_SUBJECT"); m.put(PID_SUBJECT, "PID_SUBJECT");
@ -300,14 +211,15 @@ public class PropertyIDMap extends HashMap {
/** /**
* <p> * <p>Returns the Document Summary Information properties
* singleton.</p>
* *
* Returns the Summary Information properties singleton.</p> * @return The Document Summary Information properties singleton.
*
*@return The documentSummaryInformationProperties value
*/ */
public static PropertyIDMap getDocumentSummaryInformationProperties() { public static PropertyIDMap getDocumentSummaryInformationProperties()
if (documentSummaryInformationProperties == null) { {
if (documentSummaryInformationProperties == null)
{
PropertyIDMap m = new PropertyIDMap(17, (float) 1.0); PropertyIDMap m = new PropertyIDMap(17, (float) 1.0);
m.put(PID_CATEGORY, "PID_CATEGORY"); m.put(PID_CATEGORY, "PID_CATEGORY");
m.put(PID_PRESFORMAT, "PID_PRESFORMAT"); m.put(PID_PRESFORMAT, "PID_PRESFORMAT");
@ -332,11 +244,10 @@ public class PropertyIDMap extends HashMap {
/** /**
* Description of the Method * <p>For the most basic testing.</p>
*
*@param args Description of the Parameter
*/ */
public static void main(String args[]) { public static void main(String args[])
{
PropertyIDMap s1 = getSummaryInformationProperties(); PropertyIDMap s1 = getSummaryInformationProperties();
PropertyIDMap s2 = getDocumentSummaryInformationProperties(); PropertyIDMap s2 = getDocumentSummaryInformationProperties();
System.out.println("s1: " + s1); System.out.println("s1: " + s1);