From: Rainer Klute Date: Tue, 30 Jul 2002 14:56:02 +0000 (+0000) Subject: Javadoc updates: Removed some autogenerated comments and X-Git-Tag: REL_1_10~190 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=f2528d15aa89b37d2619ac6381ce72cb8b02efe5;p=poi.git Javadoc updates: Removed some autogenerated comments and added my own ones. git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352819 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/java/org/apache/poi/hpsf/PropertySet.java b/src/java/org/apache/poi/hpsf/PropertySet.java index 103374cc3c..f98384206f 100644 --- a/src/java/org/apache/poi/hpsf/PropertySet.java +++ b/src/java/org/apache/poi/hpsf/PropertySet.java @@ -56,292 +56,301 @@ package org.apache.poi.hpsf; import java.io.*; import java.util.*; -import org.apache.poi.util.LittleEndian; import org.apache.poi.hpsf.wellknown.*; import org.apache.poi.poifs.filesystem.*; +import org.apache.poi.util.LittleEndian; /** - *

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

+ *

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 {@link - * PropertySetFactory#create} and then retrieve the information its needs by - * calling appropriate methods.

+ *

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 {@link PropertySetFactory#create} and then retrieve + * the information its needs by calling appropriate methods.

* - * {@link PropertySetFactory#create} does its work by calling one of the - * constructors {@link PropertySet#PropertySet(InputStream)} or {@link - * PropertySet#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.

+ *

{@link PropertySetFactory#create} does its work by calling one + * of the constructors {@link PropertySet#PropertySet(InputStream)} or + * {@link PropertySet#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 {@link PropertySet} has a list of {@link Section}s, and each {@link - * Section} has a {@link Property} array. Use {@link #getSections} to retrieve - * the {@link Section}s, then call {@link Section#getProperties} for each - * {@link Section} to get hold of the {@link Property} arrays.

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}). + *

A {@link PropertySet} has a list of {@link Section}s, and each + * {@link Section} has a {@link Property} array. Use {@link + * #getSections} to retrieve the {@link Section}s, then call {@link + * Section#getProperties} for each {@link Section} to get hold of the + * {@link Property} arrays.

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}).

* - *@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 + * @author Rainer Klute (klute@rainer-klute.de) + * @author Drew Varner (Drew.Varner hanginIn sc.edu) + * @version $Id$ + * @since 2002-02-09 */ -public class PropertySet { +public class PropertySet +{ + + /** + *

The "byteOrder" field must equal this value.

+ */ final static byte[] BYTE_ORDER_ASSERTION = - new byte[]{(byte) 0xFE, (byte) 0xFF}; + new byte[]{(byte) 0xFE, (byte) 0xFF}; + + /** + *

The "format" field must equal this value.

+ */ final static byte[] FORMAT_ASSERTION = - new byte[]{(byte) 0x00, (byte) 0x00}; + new byte[]{(byte) 0x00, (byte) 0x00}; + /** + *

Specifies this {@link PropertySet}'s byte order. See the + * HPFS documentation for details!

+ */ private int byteOrder; - - // Must equal BYTE_ORDER_ASSERTION - /** - *

- * - * Returns the property set stream's low-level "byte order" field. It is - * always 0xFFFE .

+ *

Returns the property set stream's low-level "byte order" + * field. It is always 0xFFFE .

* - *@return The byteOrder value + * @return The property set stream's low-level "byte order" field. */ - public int getByteOrder() { + public int getByteOrder() + { return byteOrder; } + /** + *

Specifies this {@link PropertySet}'s format. See the HPFS + * documentation for details!

+ */ private int format; - - // Must equal FORMAT_ASSERTION - /** - *

+ *

Returns the property set stream's low-level "format" + * field. It is always 0x0000 .

* - * Returns the property set stream's low-level "format" field. It is always - * 0x0000 .

- * - *@return The format value + * @return The property set stream's low-level "format" field. */ - public int getFormat() { + public int getFormat() + { return format; } - + + /** + *

Specifies the version of the operating system that created + * this {@link PropertySet}. See the HPFS documentation for + * details!

+ */ private long osVersion; - /** - *

+ *

Returns the property set stream's low-level "OS version" + * field.

* - * Returns the property set stream's low-level "OS version" field.

- * - *@return The oSVersion value + * @return The property set stream's low-level "OS version" field. */ - public long getOSVersion() { + public long getOSVersion() + { return osVersion; } + /** + *

Specifies this {@link PropertySet}'s "classID" field. See + * the HPFS documentation for details!

+ */ private ClassID classID; - /** - *

+ *

Returns the property set stream's low-level "class ID" + * field.

* - * Returns the property set stream's low-level "class ID" field.

- * - *@return The classID value + * @return The property set stream's low-level "class ID" field. */ - public ClassID getClassID() { + public ClassID getClassID() + { return classID; } + /** + *

The number of sections in this {@link PropertySet}.

+ */ private long sectionCount; /** - *

- * - * Returns the number of {@link Section}s in the property set.

+ *

Returns the number of {@link Section}s in the property + * set.

* - *@return The sectionCount value + * @return The number of {@link Section}s in the property set. */ - public long getSectionCount() { + public long getSectionCount() + { return sectionCount; } + /** + *

The sections in this {@link PropertySet}.

+ */ private List sections; /** - *

+ *

Returns the {@link Section}s in the property set.

* - * Returns the {@link Section}s in the property set.

- * - *@return The sections value + * @return The {@link Section}s in the property set. */ - public List getSections() { + public List getSections() + { return sections; } /** - *

- * - * Creates an empty (uninitialized) {@link PropertySet}.

+ *

Creates an empty (uninitialized) {@link PropertySet}.

* - * Please note: For the time being this constructor is - * protected since it is used for internal purposes only, but expect it to - * become public once the property set writing functionality is - * implemented.

+ *

Please note: For the time being this + * constructor is protected since it is used for internal purposes + * only, but expect it to become public once the property set's + * writing functionality is implemented.

*/ - protected PropertySet() { } + protected PropertySet() + {} /** - *

- * - * Creates a {@link PropertySet} instance from an {@link 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.

- * - *@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. + *

Creates a {@link PropertySet} instance from an {@link + * 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.

+ * + * @param stream Holds the data making out the 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) - throws NoPropertySetStreamException, MarkUnsupportedException, - IOException { - if (isPropertySetStream(stream)) { + throws NoPropertySetStreamException, MarkUnsupportedException, + IOException + { + if (isPropertySetStream(stream)) + { final int avail = stream.available(); final byte[] buffer = new byte[avail]; stream.read(buffer, 0, buffer.length); init(buffer, 0, buffer.length); - } else { - throw new NoPropertySetStreamException(); } + else + throw new NoPropertySetStreamException(); } /** - *

- * - * Creates a {@link PropertySet} instance from a byte array that represents - * a stream in the Horrible Property Set Format.

- * - *@param stream The byte array holding the - * stream data. - *@param 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. - *@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. + *

Creates a {@link PropertySet} instance from a byte array + * that represents a stream in the Horrible Property Set + * Format.

+ * + * @param stream The byte array holding the stream data. + * @param 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. + * @param length The length of the stream data. + * @throws NoPropertySetStreamException if the byte array is not a + * property set stream. */ public PropertySet(final byte[] stream, final int offset, final int length) - throws NoPropertySetStreamException { - if (isPropertySetStream(stream, offset, length)) { + throws NoPropertySetStreamException + { + if (isPropertySetStream(stream, offset, length)) init(stream, offset, length); - } else { + else throw new NoPropertySetStreamException(); - } } /** - *

- * - * Creates a {@link PropertySet} instance from a byte array that represents - * a stream in the Horrible Property Set Format.

- * - *@param stream The byte array holding the - * 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. + *

Creates a {@link PropertySet} instance from a byte array + * that represents a stream in the Horrible Property Set + * Format.

+ * + * @param 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. */ - public PropertySet(final byte[] stream) - throws NoPropertySetStreamException { + public PropertySet(final byte[] stream) throws NoPropertySetStreamException + { this(stream, 0, stream.length); } /** - *

- * - * Checks whether an {@link InputStream} is in the Horrible Property Set - * Format.

- * - *@param stream The {@link 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 {@link InputStream} must support the {@link - * InputStream#mark} method. - *@return true if the stream is a - * property set stream, else false. - *@exception IOException Description of the Exception - *@throws MarkUnsupportedException if the {@link InputStream} does not - * support the {@link InputStream#mark} method. + *

Checks whether an {@link InputStream} is in the Horrible + * Property Set Format.

+ * + * @param stream The {@link 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 {@link InputStream} must support the + * {@link InputStream#mark} method. + * @return true if the stream is a property set + * stream, else false. + * @throws MarkUnsupportedException if the {@link InputStream} + * does not support the {@link InputStream#mark} method. */ 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; /* - * Mark the current position in the stream so that we can - * reset to this position if the stream does not contain a - * property set. + * Mark the current position in the stream so that we can + * reset to this position if the stream does not contain a + * property set. */ - if (!stream.markSupported()) { + if (!stream.markSupported()) 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 int bytes = - stream.read(buffer, 0, - Math.min(buffer.length, stream.available())); + stream.read(buffer, 0, + Math.min(buffer.length, stream.available())); final boolean isPropertySetStream = - isPropertySetStream(buffer, 0, bytes); + isPropertySetStream(buffer, 0, bytes); stream.reset(); return isPropertySetStream; } @@ -349,66 +358,63 @@ public class PropertySet { /** - *

- * - * Checks whether a byte array is in the Horrible Property Set Format.

- * - *@param src The byte array to check. - *@param offset The offset in the byte array. - *@param length The significant number of bytes in the byte array. Only - * this number of bytes will be checked. - *@return true if the byte array is a property set - * stream, false if not. + *

Checks whether a byte array is in the Horrible Property Set + * Format.

+ * + * @param src The byte array to check. + * @param offset The offset in the byte array. + * @param length The significant number of bytes in the byte + * array. Only this number of bytes will be checked. + * @return true if the byte array is a property set + * stream, false if not. */ 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 - * there. + * Read the header fields of the stream. They must always be + * there. */ final int byteOrder = LittleEndian.getUShort(src, offset); offset += LittleEndian.SHORT_SIZE; byte[] temp = new byte[LittleEndian.SHORT_SIZE]; LittleEndian.putShort(temp,(short)byteOrder); - if (!Util.equal(temp, BYTE_ORDER_ASSERTION)) { + if (!Util.equal(temp, BYTE_ORDER_ASSERTION)) return false; - } - final int format = LittleEndian.getUShort(src, offset); + final int format = LittleEndian.getUShort(src, offset); offset += LittleEndian.SHORT_SIZE; temp = new byte[LittleEndian.SHORT_SIZE]; LittleEndian.putShort(temp,(short)format); - if (!Util.equal(temp, FORMAT_ASSERTION)) { + if (!Util.equal(temp, FORMAT_ASSERTION)) return false; - } - final long osVersion = LittleEndian.getUInt(src, offset); + final long osVersion = LittleEndian.getUInt(src, offset); offset += LittleEndian.INT_SIZE; final ClassID classID = new ClassID(src, offset); offset += ClassID.LENGTH; final long sectionCount = LittleEndian.getUInt(src, offset); offset += LittleEndian.INT_SIZE; - if (sectionCount < 1) { + if (sectionCount < 1) return false; - } - return true; + return true; } /** - *

- * - * 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.

- * - *@param src Description of the Parameter - *@param offset Description of the Parameter - *@param length Description of the Parameter + *

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.

+ * + * @param src Byte array containing the property set stream + * @param offset The property set stream starts at this offset + * from the beginning of src + * @param length Length of the property set stream. */ - 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); offset += LittleEndian.SHORT_SIZE; @@ -422,25 +428,26 @@ public class PropertySet { offset += LittleEndian.INT_SIZE; /* - * Read the sections, which are following the header. They - * start with an array of section descriptions. Each one - * consists of a format ID telling what the section contains - * and an offset telling how many bytes from the start of the - * stream the section begins. + * Read the sections, which are following the header. They + * start with an array of section descriptions. Each one + * consists of a format ID telling what the section contains + * and an offset telling how many bytes from the start of the + * stream the section begins. */ /* - * Most property sets have only one section. The Document - * Summary Information stream has 2. Everything else is a rare - * exception and is no longer fostered by Microsoft. + * Most property sets have only one section. The Document + * Summary Information stream has 2. Everything else is a rare + * exception and is no longer fostered by Microsoft. */ sections = new ArrayList(2); /* - * Loop over the section descriptor array. Each descriptor - * consists of a ClassID and a DWord, and we have to increment - * "offset" accordingly. + * Loop over the section descriptor array. Each descriptor + * consists of a ClassID and a DWord, and we have to increment + * "offset" accordingly. */ - for (int i = 0; i < sectionCount; i++) { + for (int i = 0; i < sectionCount; i++) + { final Section s = new Section(src, offset); offset += ClassID.LENGTH + LittleEndian.INT_SIZE; sections.add(s); @@ -450,156 +457,152 @@ public class PropertySet { /** - *

+ *

Checks whether this {@link PropertySet} represents a Summary + * Information.

* - * Checks whether this {@link PropertySet} represents a Summary - * Information.

- * - *@return The summaryInformation value + * @return true if this {@link PropertySet} + * represents a Summary Information, else false. */ - public boolean isSummaryInformation() { + public boolean isSummaryInformation() + { return Util.equal(((Section) sections.get(0)).getFormatID().getBytes(), - SectionIDMap.SUMMARY_INFORMATION_ID); + SectionIDMap.SUMMARY_INFORMATION_ID); } /** - *

- * - * Checks whether this {@link PropertySet} is a Document Summary - * Information.

+ *

Checks whether this {@link PropertySet} is a Document + * Summary Information.

* - *@return The documentSummaryInformation value + * @return true if this {@link PropertySet} + * represents a Document Summary Information, else false. */ - public boolean isDocumentSummaryInformation() { + public boolean isDocumentSummaryInformation() + { return Util.equal(((Section) sections.get(0)).getFormatID().getBytes(), - SectionIDMap.DOCUMENT_SUMMARY_INFORMATION_ID); + SectionIDMap.DOCUMENT_SUMMARY_INFORMATION_ID); } /** - *

- * - * 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!

- * - *@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}. + *

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!

+ * + * @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() - throws NoSingleSectionException { + throws NoSingleSectionException + { return getSingleSection().getProperties(); } /** - *

- * - * 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 {@link #wasNull} will return true - * .

- * - *@param id Description of the Parameter - *@return The property value - *@throws NoSingleSectionException if the {@link PropertySet} has more or - * less than one {@link Section}. + *

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 {@link + * #wasNull} will return true .

+ * + * @param id The property ID + * @return The property value + * @throws NoSingleSectionException if the {@link PropertySet} has + * more or less than one {@link Section}. */ - protected Object getProperty(final int id) - throws NoSingleSectionException { + protected Object getProperty(final int id) throws NoSingleSectionException + { return getSingleSection().getProperty(id); } /** - *

- * - * Convenience method returning the value of a boolean property with the - * specified ID. If the property is not available, false is - * returned. A subsequent call to {@link #wasNull} will return true - * to let the caller distinguish that case from a real property value of - * false.

- * - *@param id Description of the Parameter - *@return The propertyBooleanValue value - *@throws NoSingleSectionException if the {@link PropertySet} has more or - * less than one {@link Section}. + *

Convenience method returning the value of a boolean property + * with the specified ID. If the property is not available, + * false is returned. A subsequent call to {@link + * #wasNull} will return true to let the caller + * distinguish that case from a real property value of + * false.

+ * + * @param id The property ID + * @return The property value + * @throws NoSingleSectionException if the {@link PropertySet} has + * more or less than one {@link Section}. */ protected boolean getPropertyBooleanValue(final int id) - throws NoSingleSectionException { + throws NoSingleSectionException + { return getSingleSection().getPropertyBooleanValue(id); } /** - *

- * - * 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 true to let - * the caller distinguish that case from a real property value of 0.

- * - *@param id Description of the Parameter - *@return The propertyIntValue value - *@throws NoSingleSectionException if the {@link PropertySet} has more or - * less than one {@link Section}. + *

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 true to let the caller distinguish + * that case from a real property value of 0.

+ * + * @param id The property ID + * @return The propertyIntValue value + * @throws NoSingleSectionException if the {@link PropertySet} has + * more or less than one {@link Section}. */ protected int getPropertyIntValue(final int id) - throws NoSingleSectionException { + throws NoSingleSectionException + { return getSingleSection().getPropertyIntValue(id); } /** - *

- * - * 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.

- * - *@return true if the last call to - * {@link #getPropertyIntValue} or {@link #getProperty} tried to access - * a property that was not available, else false. - *@throws NoSingleSectionException if the {@link PropertySet} has more - * than one {@link Section}. + *

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.

+ * + * @return true if the last call to {@link + * #getPropertyIntValue} or {@link #getProperty} tried to access a + * property that was not available, else false. + * @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(); } /** - *

+ *

If the {@link PropertySet} has only a single section this + * method returns it.

* - * If the {@link PropertySet} has only a single section this method returns - * it.

- * - *@return The singleSection value - *@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() { - if (sectionCount != 1) { - throw new NoSingleSectionException - ("Property set contains " + sectionCount + " sections."); - } - return ((Section) sections.get(0)); + public Section getSingleSection() + { + if (sectionCount != 1) + throw new NoSingleSectionException + ("Property set contains " + sectionCount + " sections."); + return ((Section) sections.get(0)); } } diff --git a/src/java/org/apache/poi/hpsf/wellknown/PropertyIDMap.java b/src/java/org/apache/poi/hpsf/wellknown/PropertyIDMap.java index 217a635734..dc7f32e6f9 100644 --- a/src/java/org/apache/poi/hpsf/wellknown/PropertyIDMap.java +++ b/src/java/org/apache/poi/hpsf/wellknown/PropertyIDMap.java @@ -57,222 +57,133 @@ package org.apache.poi.hpsf.wellknown; import java.util.*; /** - *

+ *

This is a dictionary which maps property ID values to property + * ID strings.

* - * This is a dictionary mapping property IDs to property ID strings.

+ *

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.

* - * 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.

+ *

FIXME: Make the singletons + * unmodifiable. However, since this requires to use a {@link HashMap} + * delegate instead of extending {@link HashMap} and thus requires a + * lot of stupid typing. I won't do that for the time being.

* - * FIXME: Make the singletons unmodifiable. However, since - * this requires use a {@link HashMap} delegate instead of extending {@link - * HashMap} and would require a lot of stupid typing, I won't do it for the - * time being.

- * - *@author Rainer Klute (klute@rainer-klute.de) - *@created May 10, 2002 - *@version $Id$ - *@since 2002-02-09 + * @author Rainer Klute (klute@rainer-klute.de) + * @version $Id$ + * @since 2002-02-09 */ -public class PropertyIDMap extends HashMap { +public class PropertyIDMap extends HashMap +{ /* - * The following definitions are for the Summary Information. - */ - /** - * Description of the Field + * The following definitions are for the Summary Information. */ public final static int PID_TITLE = 2; - /** - * Description of the Field - */ public final static int PID_SUBJECT = 3; - /** - * Description of the Field - */ public final static int PID_AUTHOR = 4; - /** - * Description of the Field - */ public final static int PID_KEYWORDS = 5; - /** - * Description of the Field - */ public final static int PID_COMMENTS = 6; - /** - * Description of the Field - */ public final static int PID_TEMPLATE = 7; - /** - * Description of the Field - */ public final static int PID_LASTAUTHOR = 8; - /** - * Description of the Field - */ public final static int PID_REVNUMBER = 9; - /** - * Description of the Field - */ public final static int PID_EDITTIME = 10; - /** - * Description of the Field - */ public final static int PID_LASTPRINTED = 11; - /** - * Description of the Field - */ public final static int PID_CREATE_DTM = 12; - /** - * Description of the Field - */ public final static int PID_LASTSAVE_DTM = 13; - /** - * Description of the Field - */ public final static int PID_PAGECOUNT = 14; - /** - * Description of the Field - */ public final static int PID_WORDCOUNT = 15; - /** - * Description of the Field - */ public final static int PID_CHARCOUNT = 16; - /** - * Description of the Field - */ public final static int PID_THUMBNAIL = 17; - /** - * Description of the Field - */ public final static int PID_APPNAME = 18; - /** - * Description of the Field - */ public final static int PID_SECURITY = 19; /* - * The following definitions are for the Document Summary Information. - */ - /** - * Description of the Field + * The following definitions are for the Document Summary Information. */ public final static int PID_CATEGORY = 2; - /** - * Description of the Field - */ public final static int PID_PRESFORMAT = 3; - /** - * Description of the Field - */ public final static int PID_BYTECOUNT = 4; - /** - * Description of the Field - */ public final static int PID_LINECOUNT = 5; - /** - * Description of the Field - */ public final static int PID_PARCOUNT = 6; - /** - * Description of the Field - */ public final static int PID_SLIDECOUNT = 7; - /** - * Description of the Field - */ public final static int PID_NOTECOUNT = 8; - /** - * Description of the Field - */ public final static int PID_HIDDENCOUNT = 9; - /** - * Description of the Field - */ public final static int PID_MMCLIPCOUNT = 10; - /** - * Description of the Field - */ public final static int PID_SCALE = 11; - /** - * Description of the Field - */ public final static int PID_HEADINGPAIR = 12; - /** - * Description of the Field - */ public final static int PID_DOCPARTS = 13; - /** - * Description of the Field - */ public final static int PID_MANAGER = 14; - /** - * Description of the Field - */ public final static int PID_COMPANY = 15; - /** - * Description of the Field - */ public final static int PID_LINKSDIRTY = 16; + /** + *

Contains the summary information property ID values and + * associated strings. See the overall HPSF documentation for + * details!

+ */ private static PropertyIDMap summaryInformationProperties; + + /** + *

Contains the summary information property ID values and + * associated strings. See the overall HPSF documentation for + * details!

+ */ private static PropertyIDMap documentSummaryInformationProperties; /** - * Constructor for the PropertyIDMap object - * - *@param initialCapacity Description of the Parameter - *@param loadFactor Description of the Parameter + *

Creates a {@link PropertyIDMap}.

*/ - public PropertyIDMap(int initialCapacity, float loadFactor) { + public PropertyIDMap(int initialCapacity, float loadFactor) + { super(initialCapacity, loadFactor); } /** - *

+ *

Puts a ID string for an ID into the {@link + * PropertyIDMap}.

* - * Puts a ID string for an ID into the {@link PropertyIDMap}.

- * - *@param id The ID. - *@param idString The ID string. - *@return Description of the Return Value - */ - public Object put(int id, String idString) { + * @param id The ID. + * @param idString The ID string. + * @return As specified by the {@link Map} interface, this method + * returns the previous value associated with the specified + * id, or null if there was no mapping for + * key. + */ + public Object put(int id, String idString) + { return put(new Integer(id), idString); } /** - *

+ *

Gets the ID string for an ID from the {@link + * PropertyIDMap}.

* - * Gets the ID string for an ID from the {@link PropertyIDMap}.

- * - *@param id The ID. - *@return Description of the Return Value + * @param id The ID. + * @return The ID string associated with id. */ - public Object get(int id) { + public Object get(int id) + { return get(new Integer(id)); } /** - *

- * - * Returns the Summary Information properties singleton.

- * - *@return The summaryInformationProperties value + *

Returns the Summary Information properties singleton.

*/ - public static PropertyIDMap getSummaryInformationProperties() { - if (summaryInformationProperties == null) { + public static PropertyIDMap getSummaryInformationProperties() + { + if (summaryInformationProperties == null) + { PropertyIDMap m = new PropertyIDMap(17, (float) 1.0); m.put(PID_TITLE, "PID_TITLE"); m.put(PID_SUBJECT, "PID_SUBJECT"); @@ -300,14 +211,15 @@ public class PropertyIDMap extends HashMap { /** - *

+ *

Returns the Document Summary Information properties + * singleton.

* - * Returns the Summary Information properties singleton.

- * - *@return The documentSummaryInformationProperties value + * @return The Document Summary Information properties singleton. */ - public static PropertyIDMap getDocumentSummaryInformationProperties() { - if (documentSummaryInformationProperties == null) { + public static PropertyIDMap getDocumentSummaryInformationProperties() + { + if (documentSummaryInformationProperties == null) + { PropertyIDMap m = new PropertyIDMap(17, (float) 1.0); m.put(PID_CATEGORY, "PID_CATEGORY"); m.put(PID_PRESFORMAT, "PID_PRESFORMAT"); @@ -332,11 +244,10 @@ public class PropertyIDMap extends HashMap { /** - * Description of the Method - * - *@param args Description of the Parameter + *

For the most basic testing.

*/ - public static void main(String args[]) { + public static void main(String args[]) + { PropertyIDMap s1 = getSummaryInformationProperties(); PropertyIDMap s2 = getDocumentSummaryInformationProperties(); System.out.println("s1: " + s1);