Package loci.poi.hpsf

Class VariantSupport

java.lang.Object
loci.poi.hpsf.Variant
loci.poi.hpsf.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 Details

    • unsupportedMessage

      protected static List unsupportedMessage

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

  • Constructor Details

    • VariantSupport

      public VariantSupport()
  • Method Details

    • 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:
    • 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