Package loci.poi.hpsf

Class VariantSupport


  • public class VariantSupport
    extends Variant

    Supports reading and writing of variant data.

    FIXME (3): Reading and writing should be made more uniform than it is now. The following items should be resolved:

    • Reading requires a length parameter that is 4 byte greater than the actual data, because the variant type field is included.

    • Reading reads from a byte array while writing writes to an byte array output stream.

    Since:
    2003-08-08
    Version:
    $Id: VariantSupport.java 489730 2006-12-22 19:18:16Z bayard $
    Author:
    Rainer Klute <klute@rainer-klute.de>
    • Field Detail

      • unsupportedMessage

        protected static List unsupportedMessage

        Keeps a list of the variant types an "unsupported" message has already been issued for.

    • Constructor Detail

      • VariantSupport

        public VariantSupport()
    • Method Detail

      • setLogUnsupportedTypes

        public static void setLogUnsupportedTypes​(boolean logUnsupportedTypes)

        Specifies whether warnings about unsupported variant types are to be written to System.err or not.

        Parameters:
        logUnsupportedTypes - If true warnings will be written, if false they won't.
      • isLogUnsupportedTypes

        public static boolean isLogUnsupportedTypes()

        Checks whether logging of unsupported variant types warning is turned on or off.

        Returns:
        true if logging is turned on, else false.
      • writeUnsupportedTypeMessage

        protected static void writeUnsupportedTypeMessage​(UnsupportedVariantTypeException ex)

        Writes a warning to System.err that a variant type is unsupported by HPSF. Such a warning is written only once for each variant type. Log messages can be turned on or off by

        Parameters:
        ex - The exception to log
      • read

        public static Object read​(byte[] src,
                                  int offset,
                                  int length,
                                  long type,
                                  int codepage)
                           throws ReadingNotSupportedException,
                                  UnsupportedEncodingException

        Reads a variant type from a byte array.

        Parameters:
        src - The byte array
        offset - The offset in the byte array where the variant starts
        length - The length of the variant including the variant type field
        type - The variant type to read
        codepage - The codepage to use to write non-wide strings
        Returns:
        A Java object that corresponds best to the variant field. For example, a VT_I4 is returned as a Long, a VT_LPSTR as a String.
        Throws:
        ReadingNotSupportedException - if a property is to be written who's variant type HPSF does not yet support
        UnsupportedEncodingException - if the specified codepage is not supported.
        See Also:
        Variant
      • codepageToEncoding

        public static String codepageToEncoding​(int codepage)
                                         throws UnsupportedEncodingException

        Turns a codepage number into the equivalent character encoding's name.

        Parameters:
        codepage - The codepage number
        Returns:
        The character encoding's name. If the codepage number is 65001, the encoding name is "UTF-8". All other positive numbers are mapped to "cp" followed by the number, e.g. if the codepage number is 1252 the returned character encoding name will be "cp1252".
        Throws:
        UnsupportedEncodingException - if the specified codepage is less than zero.
      • write

        public static int write​(OutputStream out,
                                long type,
                                Object value,
                                int codepage)
                         throws IOException,
                                WritingNotSupportedException

        Writes a variant value to an output stream. This method ensures that always a multiple of 4 bytes is written.

        If the codepage is UTF-16, which is encouraged, strings must always be written as Variant.VT_LPWSTR strings, not as Variant.VT_LPSTR strings. This method ensure this by converting strings appropriately, if needed.

        Parameters:
        out - The stream to write the value to.
        type - The variant's type.
        value - The variant's value.
        codepage - The codepage to use to write non-wide strings
        Returns:
        The number of entities that have been written. In many cases an "entity" is a byte but this is not always the case.
        Throws:
        IOException - if an I/O exceptions occurs
        WritingNotSupportedException - if a property is to be written who's variant type HPSF does not yet support