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 java.lang.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.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `EscherRecord()` Create a new instance
    `protected` | `EscherRecord(EscherRecord other)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `EscherRecord` | `clone()` Deprecated. use `copy()`
    `abstract EscherRecord` | `copy()`
    `void` | `display(java.io.PrintWriter w, int indent)` The display methods allows escher variables to print the record names according to their hierarchy.
    `protected int` | `fillFields(byte[] data, EscherRecordFactory f)` Delegates to fillFields(byte[], int, EscherRecordFactory)
    `abstract int` | `fillFields(byte[] data, int offset, EscherRecordFactory recordFactory)` The contract of this method is to deserialize an escher record including it's children.
    `EscherRecord` | `getChild(int index)` Returns the indexed child record.
    `java.util.List<EscherRecord>` | `getChildRecords()`
    `java.util.List<? extends GenericRecord>` | `getGenericChildren()`
    `java.util.Map<java.lang.String,java.util.function.Supplier<?>>` | `getGenericProperties()`
    `short` | `getInstance()` Returns the instance part of the option record.
    `short` | `getOptions()` Note that `options` is an internal field.
    `short` | `getRecordId()` Return the current record id.
    `abstract java.lang.String` | `getRecordName()` Subclasses should return the short name for this escher record.
    `abstract int` | `getRecordSize()` Subclasses should effeciently return the number of bytes required to serialize the record.
    `short` | `getVersion()` Returns the version part of the option record.
    `boolean` | `isContainerRecord()` Determine whether this is a container record by inspecting the option field.
    `protected int` | `readHeader(byte[] data, int offset)` Reads the 8 byte header information and populates the `options` and `recordId` records.
    `protected static short` | `readInstance(byte[] data, int offset)` Read the options field from header and return instance part of it.
    `byte[]` | `serialize()` Serializes to a new byte array.
    `int` | `serialize(int offset, byte[] data)` Serializes to an existing byte array without serialization listener.
    `abstract int` | `serialize(int offset, byte[] data, EscherSerializationListener listener)` Serializes the record to an existing byte array.
    `void` | `setChildRecords(java.util.List<EscherRecord> childRecords)` Sets the child records for this record.
    `void` | `setInstance(short value)` Sets the instance part of record
    `void` | `setOptions(short options)` Set the options this this record.
    `void` | `setRecordId(short recordId)` Sets the record id for this record.
    `void` | `setVersion(short value)` Sets the version part of record
    `java.lang.String` | `toString()`
    `java.lang.String` | `toXml()`
    `java.lang.String` | `toXml(java.lang.String tab)`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.apache.poi.common.usermodel.GenericRecord

      `getGenericRecordType`

- - ### Constructor Detail

    - #### EscherRecord

          public EscherRecord()

      Create a new instance

    - #### EscherRecord

          protected EscherRecord(EscherRecord other)

  - ### Method Detail

    - #### 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(byte[], int, org.apache.poi.ddf.EscherRecordFactory)`

    - #### fillFields

          public abstract int fillFields(byte[] data,
                                         int offset,
                                         EscherRecordFactory recordFactory)

      The contract of this method is to deserialize an escher record including it's 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.

    - #### 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 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(int, byte[])`

    - #### 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(int, byte[], org.apache.poi.ddf.EscherSerializationListener)`

    - #### 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 java.util.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:
        `EscherContainerRecord`

    - #### setChildRecords

          public void setChildRecords(java.util.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.

    - #### clone

          @Deprecated
           @Removal(version="5.0.0")
          public final EscherRecord clone()

      Deprecated. use `copy()`
      Escher records may need to be clonable in the future.
      Overrides:
        `clone` in class `java.lang.Object`
      Returns:
        the cloned object

    - #### 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(java.io.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 java.lang.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 java.lang.String toXml()

    - #### toXml

          public final java.lang.String toXml(java.lang.String tab)

      Parameters:
        `tab` - - each children must be indented right relative to its parent
      Returns:
        xml representation of this record

    - #### toString

          public final java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getGenericChildren

          public java.util.List<? extends GenericRecord> getGenericChildren()

      Specified by:
        `getGenericChildren` in interface `GenericRecord`

    - #### getGenericProperties

          public java.util.Map<java.lang.String,java.util.function.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

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.