/* ====================================================================   Copyright 2002-2004   Apache Software Foundation   Licensed under the Apache License, Version 2.0 (the "License");   you may not use this file except in compliance with the License.   You may obtain a copy of the License at       http://www.apache.org/licenses/LICENSE-2.0   Unless required by applicable law or agreed to in writing, software   distributed under the License is distributed on an "AS IS" BASIS,   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   See the License for the specific language governing permissions and   limitations under the License.==================================================================== */        package org.apache.poi.hpsf;import java.io.IOException;import java.io.InputStream;import java.io.UnsupportedEncodingException;import java.util.ArrayList;import java.util.List;import org.apache.poi.hpsf.wellknown.SectionIDMap;import org.apache.poi.util.LittleEndian;/** * <p>Represents a property set in the Horrible Property Set Format * (HPSF). These are usually metadata of a Microsoft Office * document.</p> * * <p>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.</p> * * <p>{@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.</p> * * <p>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.</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> * * @author Rainer Klute <a * href="mailto:klute@rainer-klute.de">&lt;klute@rainer-klute.de&gt;</a> * @author Drew Varner (Drew.Varner hanginIn sc.edu) * @version $Id: PropertySet.java,v 1.19 2004/08/31 17:59:49 klute Exp $ * @since 2002-02-09 */public class PropertySet{    /**     * <p>The "byteOrder" field must equal this value.</p>     */    static final byte[] BYTE_ORDER_ASSERTION =        new byte[] {(byte) 0xFE, (byte) 0xFF};    /**     * <p>Specifies this {@link PropertySet}'s byte order. See the     * HPFS documentation for details!</p>     */    protected 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;    }    /**     * <p>The "format" field must equal this value.</p>     */    static final byte[] FORMAT_ASSERTION =        new byte[]{(byte) 0x00, (byte) 0x00};    /**     * <p>Specifies this {@link PropertySet}'s format. See the HPFS     * documentation for details!</p>     */    protected int format;    /**     * <p>Returns the property set stream's low-level "format"     * field. It is always <tt>0x0000</tt> .</p>     *     * @return The property set stream's low-level "format" field.     */    public int getFormat()    {        return format;    }     /**     * <p>Specifies the version of the operating system that created     * this {@link PropertySet}. See the HPFS documentation for     * details!</p>     */    protected int osVersion;    /**     * <p>If the OS version field holds this value the property set stream was     * created on a 16-bit Windows system.</p>     */    public static final int OS_WIN16     = 0x0000;    /**     * <p>If the OS version field holds this value the property set stream was     * created on a Macintosh system.</p>     */    public static final int OS_MACINTOSH = 0x0001;    /**     * <p>If the OS version field holds this value the property set stream was     * created on a 32-bit Windows system.</p>     */    public static final int OS_WIN32     = 0x0002;    /**     * <p>Returns the property set stream's low-level "OS version"     * field.</p>     *     * @return The property set stream's low-level "OS version" field.     */    public int getOSVersion()    {        return osVersion;    }    /**     * <p>Specifies this {@link PropertySet}'s "classID" field. See     * the HPFS documentation for details!</p>     */    protected ClassID classID;    /**     * <p>Returns the property set stream's low-level "class ID"     * field.</p>     *     * @return The property set stream's low-level "class ID" field.     */    public ClassID getClassID()    {        return classID;    }    /**     * <p>Returns the number of {@link Section}s in the property     * set.</p>     *     * @return The number of {@link Section}s in the property set.     */    public int getSectionCount()    {        return sections.size();    }    /**     * <p>The sections in this {@link PropertySet}.</p>     */    protected List sections;    /**     * <p>Returns the {@link Section}s in the property set.</p>     *     * @return The {@link Section}s in the property set.     */    public List getSections()    {        return sections;    }    /**     * <p>Creates an empty (uninitialized) {@link PropertySet}.</p>     *     * <p><strong>Please note:</strong> 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.</p>     */    protected PropertySet()    { }    /**     * <p>Creates a {@link PropertySet} instance from an {@link     * InputStream} in the Horrible Property Set Format.</p>     *     * <p>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.</p>     *     * @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.     * @exception NoPropertySetStreamException if the input stream does not     * contain a property set.     * @exception UnsupportedEncodingException if a character encoding is not     * supported.     */    public PropertySet(final InputStream stream)        throws NoPropertySetStreamException, MarkUnsupportedException,               IOException, UnsupportedEncodingException    {        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();    }    /**     * <p>Creates a {@link PropertySet} instance from a byte array     * that represents a stream in the Horrible Property Set     * Format.</p>     *     * @param stream The byte array holding the stream data.     * @param offset The offset in <var>stream</var> where the stream     * data begin. If the stream data begin with the first byte in the     * array, the <var>offset</var> is 0.     * @param length The length of the stream data.     * @throws NoPropertySetStreamException if the byte array is not a     * property set stream.     *      * @exception UnsupportedEncodingException if the codepage is not supported.     */    public PropertySet(final byte[] stream, final int offset, final int length)        throws NoPropertySetStreamException, UnsupportedEncodingException    {        if (isPropertySetStream(stream, offset, length))            init(stream, offset, length);        else            throw new NoPropertySetStreamException();    }    /**     * <p>Creates a {@link PropertySet} instance from a byte array     * that represents a stream in the Horrible Property Set     * Format.</p>     *     * @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.     *      * @exception UnsupportedEncodingException if the codepage is not supported.     */    public PropertySet(final byte[] stream)    throws NoPropertySetStreamException, UnsupportedEncodingException    {        this(stream, 0, stream.length);    }    /**     * <p>Checks whether an {@link InputStream} is in the Horrible     * Property Set Format.</p>     *     * @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 <code>true</code> if the stream is a property set     * stream, else <code>false</code>.     * @throws MarkUnsupportedException if the {@link InputStream}     * does not support the {@link InputStream#mark} method.     * @exception IOException if an I/O error occurs     */    public static boolean isPropertySetStream(final InputStream stream)        throws MarkUnsupportedException, IOException    {        /*         * 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.         */        if (!stream.markSupported())            throw new MarkUnsupportedException(stream.getClass().getName());        stream.mark(BUFFER_SIZE);        /*         * 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()));        final boolean isPropertySetStream =            isPropertySetStream(buffer, 0, bytes);