Package org.apache.poi.ddf

Class EscherRecord

java.lang.Object
org.apache.poi.ddf.EscherRecord
All Implemented Interfaces:
Duplicatable, GenericRecord
Direct Known Subclasses:
AbstractEscherOptRecord, EscherBlipRecord, EscherBSERecord, EscherChildAnchorRecord, EscherClientAnchorRecord, EscherClientDataRecord, EscherContainerRecord, EscherDggRecord, EscherDgRecord, EscherPlaceholder, EscherSpgrRecord, EscherSplitMenuColorsRecord, EscherSpRecord, EscherTextboxRecord, UnknownEscherRecord
public abstract class EscherRecord extends Object implements Duplicatable, GenericRecord
The base abstract record from which all escher records are defined. Subclasses will need to define methods for serialization/deserialization and for determining the record size.

  • Field Details

  • Constructor Details

    • EscherRecord

      public EscherRecord()
      Create a new instance

    • EscherRecord

      protected EscherRecord(EscherRecord other)

  • Method Details

    • fillFields

      protected int fillFields(byte[] data, EscherRecordFactory f)
      Delegates to fillFields(byte[], int, EscherRecordFactory)
      Parameters:
      data - they bytes to serialize from
      f - the escher record factory
      Returns:
      The number of bytes written.
      See Also:

    • fillFields

      public abstract int fillFields(byte[] data, int offset, EscherRecordFactory recordFactory)
      The contract of this method is to deserialize an escher record including its children.
      Parameters:
      data - The byte array containing the serialized escher records.
      offset - The offset into the byte array.
      recordFactory - A factory for creating new escher records.
      Returns:
      The number of bytes written.

    • fillFields

      protected int fillFields(byte[] data, int offset, EscherRecordFactory recordFactory, int nesting)
      Internal method to prevent too deep nesting/using too much memory. This is done by counting the level of "nesting" via the parameter. The default method just forwards to fillFields() so it does not properly handle nesting. Subclasses which do recursive calls need to pass around the nesting-level properly. Usually both fillFields() methods should be overwritten by subclasses, the one without the "nesting"-parameter should routes to this one in classes which overwrite this method and this method should be overwritten with the actual functionality to fill fields.
      Parameters:
      data - The byte array containing the serialized escher records.
      offset - The offset into the byte array.
      recordFactory - A factory for creating new escher records.
      nesting - The current nesting factor, usually increased by one on each recursive call
      Returns:
      The number of bytes written.

    • readHeader

      protected int readHeader(byte[] data, int offset)
      Reads the 8 byte header information and populates the options and recordId records.
      Parameters:
      data - the byte array to read from
      offset - the offset to start reading from
      Returns:
      the number of bytes remaining in this record. This may include the children if this is a container.

    • readInstance

      protected static short readInstance(byte[] data, int offset)
      Read the options field from header and return instance part of it.
      Parameters:
      data - the byte array to read from
      offset - the offset to start reading from
      Returns:
      value of instance part of options field

    • isContainerRecord

      public boolean isContainerRecord()
      Determine whether this is a container record by inspecting the option field.
      Returns:
      true is this is a container field.

    • getOptions

      @Internal public short getOptions()
      Note that options is an internal field. Use setInstance(short) ()} and setVersion(short) ()} to set the actual fields.
      Returns:
      The options field for this record. All records have one.

    • setOptions

      @Internal public void setOptions(short options)
      Set the options this record. Container records should have the last nibble set to 0xF.

      Note that options is an internal field. Use getInstance() and getVersion() to access actual fields.

      Parameters:
      options - the record options

    • serialize

      public byte[] serialize()
      Serializes to a new byte array. This is done by delegating to serialize(int, byte[]);
      Returns:
      the serialized record.
      See Also:

    • serialize

      public int serialize(int offset, byte[] data)
      Serializes to an existing byte array without serialization listener. This is done by delegating to serialize(int, byte[], EscherSerializationListener).
      Parameters:
      offset - the offset within the data byte array.
      data - the data array to serialize to.
      Returns:
      The number of bytes written.
      See Also:

    • serialize

      public abstract int serialize(int offset, byte[] data, EscherSerializationListener listener)
      Serializes the record to an existing byte array.
      Parameters:
      offset - the offset within the byte array
      data - the data array to serialize to
      listener - a listener for begin and end serialization events. This is useful because the serialization is hierarchical/recursive and sometimes you need to be able break into that.
      Returns:
      the number of bytes written.

    • getRecordSize

      public abstract int getRecordSize()
      Subclasses should effeciently return the number of bytes required to serialize the record.
      Returns:
      number of bytes

    • getRecordId

      public short getRecordId()
      Return the current record id.
      Returns:
      The 16 bit record id.

    • setRecordId

      public void setRecordId(short recordId)
      Sets the record id for this record.
      Parameters:
      recordId - the record id

    • getChildRecords

      public List<EscherRecord> getChildRecords()
      Returns:
      Returns the children of this record. By default this will be an empty list. EscherCotainerRecord is the only record that may contain children.
      See Also:

    • setChildRecords

      public void setChildRecords(List<EscherRecord> childRecords)
      Sets the child records for this record. By default this will throw an exception as only EscherContainerRecords may have children.
      Parameters:
      childRecords - Not used in base implementation.

    • getChild

      public EscherRecord getChild(int index)
      Returns the indexed child record.
      Parameters:
      index - the index of the child within the child records
      Returns:
      the indexed child record

    • display

      public void display(PrintWriter w, int indent)
      The display methods allows escher variables to print the record names according to their hierarchy.
      Parameters:
      w - The print writer to output to.
      indent - The current indent level.

    • getRecordName

      public abstract String getRecordName()
      Subclasses should return the short name for this escher record.
      Returns:
      the short name for this escher record

    • getInstance

      public short getInstance()
      Returns the instance part of the option record.
      Returns:
      The instance part of the record

    • setInstance

      public void setInstance(short value)
      Sets the instance part of record
      Parameters:
      value - instance part value

    • getVersion

      public short getVersion()
      Returns the version part of the option record.
      Returns:
      The version part of the option record

    • setVersion

      public void setVersion(short value)
      Sets the version part of record
      Parameters:
      value - version part value

    • toXml

      public String toXml()

    • toXml

      public final String toXml(String tab)
      Parameters:
      tab - - each children must be indented right relative to its parent
      Returns:
      xml representation of this record

    • toString

      public final String toString()
      Overrides:
      toString in class Object

    • getGenericChildren

      public List<? extends GenericRecord> getGenericChildren()
      Specified by:
      getGenericChildren in interface GenericRecord

    • getGenericProperties

      public Map<String,Supplier<?>> getGenericProperties()
      Specified by:
      getGenericProperties in interface GenericRecord

    • copy

      public abstract EscherRecord copy()
      Specified by:
      copy in interface Duplicatable
      Returns:
      a deep copy of the implementing class / instance

    • setMaxNumberOfChildren

      public static void setMaxNumberOfChildren(int length)
      Parameters:
      length - the max number of children allowed for EscherRecords which support nesting

    • getMaxNumberOfChildren

      public static int getMaxNumberOfChildren()
      Returns:
      the max number of children allowed for EscherRecords which support nesting