net.sf.okapi.common.filters

## Class EventBuilder

- java.lang.Object
- - net.sf.okapi.common.filters.EventBuilder

-     public class EventBuilder
      extends java.lang.Object

  EventBuilder provides a simplified API for filter writers that hides the low level resource API.

  EventBuilder allows filter writers to think in terms of start and end calls. For example, to produce a non-translatable `Event` you would use startDocumentPart() and endDocumentPart(). For a text-based `Event` you would use startTextUnit() and endTextUnit().

  More complex cases such as tags with embedded translatable text can also be handled. See the AbstractMarkupFilter, HtmlFilter and OpenXmlFilter for examples of using EventBuilder.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `EventBuilder()` Instantiates a new EventBuilder.
    `EventBuilder(java.lang.String rootId, IFilter filter)` Instantiates a new EventBuilder with a root ID.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `DocumentPart` | `addDocumentPart(java.lang.String part)` Create a single `DocumentPart` and add a `DocumentPart` `Event` to the queue.
    `void` | `addFilterEvent(Event event)` Add an `Event` at the end of the current `Event` queue.
    `void` | `addFilterEvents(java.util.List<Event> events)`
    `void` | `addTextUnit(java.lang.String text)` Start and end a `TextUnit`.
    `void` | `addToDocumentPart(java.lang.String part)` Add to the current `DocumentPart`.
    `void` | `addToTextUnit(Code code)` Add a `Code` to the current `TextUnit`.
    `void` | `addToTextUnit(Code code, boolean endCodeNow)` Add a `Code` to the current `TextUnit`.
    `void` | `addToTextUnit(Code code, boolean endCodeNow, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` Add a `Code` to the current `TextUnit`.
    `void` | `addToTextUnit(Code code, boolean endCodeNow, LocaleId locale, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` Add a `Code` to the current `TextUnit`.
    `void` | `addToTextUnit(ITextUnit textUnit)` Adds a child TextUnit to the current (parent) `TextUnit`
    `void` | `addToTextUnit(java.lang.String text)` Adds text to the current `TextUnit`
    `void` | `appendCodeData(java.lang.String data)` append to the current `Code`'s data
    `void` | `appendCodeOuterData(java.lang.String outerData)` append to the current `Code`'s outerData
    `void` | `appendToFirstSkeletonPart(java.lang.String text)` Appends text to the first data part of the skeleton.
    `void` | `cancel()` Cancel current processing and add the CANCELED `Event` to the event queue.
    `boolean` | `canStartNewTextUnit()` Can we start new `TextUnit`? A new `TextUnit` can only be started if the current one has been ended with endTextUnit.
    `void` | `convertTempTextUnitToDocumentPart()` Convert the skeleton attached to an in-progress `TextUnit` into a `DocumentPart`.
    `void` | `endCode()`
    `void` | `endCode(java.lang.String tag)`
    `void` | `endDocumentPart()` End the `DocumentPart` and finalize the `Event`.
    `void` | `endDocumentPart(java.lang.String part)` End the current `DocumentPart` and finalize the `Event`.
    `Ending` | `endGroup(GenericSkeleton endMarker)` Create a `Ending` `Event` of type END_GROUP and add it to the event queue.
    `Ending` | `endGroup(GenericSkeleton endMarker, LocaleId locale, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` Create a `Ending` `Event` of type END_GROUP and add it to the event queue.
    `void` | `endSubDocument()` Add the END_SUBDOCUMENT `Event` to the event queue.
    `ITextUnit` | `endTextUnit()` End the current `TextUnit` and place the `Event` on the event queue.
    `ITextUnit` | `endTextUnit(GenericSkeleton endMarker)` End the current `TextUnit` and place the `Event` on the event queue.
    `ITextUnit` | `endTextUnit(GenericSkeleton endMarker, LocaleId locale, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` End the current `TextUnit` and place the `Event` on the event queue.
    `java.lang.String` | `findMostRecentParentId()`
    `java.lang.String` | `findMostRecentParentName()`
    `java.lang.String` | `findMostRecentTextUnitName()` Find in our buffered queue the most recent TextUnit that has an assigned name
    `void` | `flushRemainingTempEvents()` Flush all remaining events from the `Event` queues
    `Code` | `getCurrentCode()` Get the current `Code`.
    `long` | `getDocumentPartId()` Gets the current custom `DocumentPart` id.
    `IdGenerator` | `getGroupId()` Get the `IdGenerator` for Groups
    `long` | `getGroupIdSequence()`
    `java.lang.String` | `getRootId()` Get the current root id
    `IdGenerator` | `getSubDocumentId()` Get the `IdGenerator` for SubDocuments
    `LocaleId` | `getTargetLocale()` Get the current target locale.
    `long` | `getTextUnitId()` Gets the custom textUnitId set by the caller.
    `boolean` | `hasNext()` Are we finished parsing the input document?
    `boolean` | `hasParentTextUnit()` Does the current `TextUnit` have a parent?
    `boolean` | `hasQueuedEvents()` Are there any queued events? We queue events in the correct order as expected by the Okapi filter writers (IWriter).
    `boolean` | `hasUnfinishedSkeleton()` Is there an unfinished `DocumentPart` (aka skeleton)?
    `boolean` | `isCurrentComplexTextUnit()` Is the current buffered `Event` a complex `TextUnit`? A complex TextUnit is one which carries along with it it's surrounding formatting or skeleton such <p> text </p> or <title> text </title>
    `boolean` | `isCurrentGroup()` Is the current buffered `Event` a `StartGroup`?
    `boolean` | `isCurrentSubfilter()` Is the current buffered `Event` a `StartSubfilter`?
    `boolean` | `isCurrentTextUnit()` Is the current buffered `Event` a `TextUnit`?
    `boolean` | `isInsideTextRun()` Is the filter is inside text run?
    `boolean` | `isPreserveWhitespace()` What is the current preserve whitespace state?
    `boolean` | `isTextUnitWithSameType(java.lang.String type)` Is the current TextUnit of the specified type?
    `Event` | `next()` Return the next filter event waiting in the event queue.
    `Code` | `peekMostRecentCode()` Peek at the most recently created `StartGroup`.
    `StartGroup` | `peekMostRecentGroup()` Peek at the most recently created `StartGroup` or `StartSubfilter`.
    `StartSubDocument` | `peekMostRecentSubDocument()` Peek at the most recently created `StartSubDocument`
    `ITextUnit` | `peekMostRecentTextUnit()` Peek At the most recently created `TextUnit`.
    `Event` | `peekTempEvent()`
    `Event` | `popTempEvent()`
    `protected ITextUnit` | `postProcessTextUnit(ITextUnit textUnit)` Do any required post-processing on the TextUnit after endTextUnit is called.
    `void` | `reset(java.lang.String rootId, IFilter filter)`
    `void` | `setDocumentPartId(long id)` Set the current custom `DocumentPart` id.
    `void` | `setGroupIdSequence(long id)`
    `void` | `setMimeType(java.lang.String mimeType)` Sets the input document mime type.
    `void` | `setPreserveWhitespace(boolean preserveWhitespace)` Tell the `IFilter` what to do with whitespace.
    `void` | `setTargetLocale(LocaleId targetLocale)` Set the target locale.
    `void` | `setTextUnitId(long id)` Set the current textUnitId.
    `void` | `setTextUnitMimeType(java.lang.String mimeType)` Set the mime type on the current `TextUnit`
    `void` | `setTextUnitName(java.lang.String name)` Set the current `TextUnit` name.
    `void` | `setTextUnitPreserveWhitespace(boolean preserveWhitespace)` Set preserve whitespace flag on current `TextUnit`
    `void` | `setTextUnitTranslatable(boolean translatable)` Set the current `TextUnit` translatable flag.
    `void` | `setTextUnitType(java.lang.String type)` Set the current `TextUnit` type.
    `void` | `startCode(Code code)`
    `DocumentPart` | `startDocumentPart(java.lang.String part)` Create a `DocumentPart` and store it for later processing.
    `void` | `startDocumentPart(java.lang.String part, java.lang.String name, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` Create a `DocumentPart` that references actionable (i.e., translatable, localizable) properties and store it for later processing.
    `void` | `startDocumentPart(java.lang.String part, java.lang.String name, LocaleId locale, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` Create a `DocumentPart` that references actionable (i.e., translatable, localizable) properties and store it for later processing.
    `StartGroup` | `startGroup(GenericSkeleton startMarker, java.lang.String commonTagType)` Create a `StartGroup` `Event` and add it to the event queue.
    `StartGroup` | `startGroup(GenericSkeleton startMarker, java.lang.String commonTagType, LocaleId locale, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` Create a `StartGroup` `Event` and add it to the event queue.
    `StartSubDocument` | `startSubDocument()` Add the START_SUBDOCUMENT `Event` to the event queue.
    `void` | `startTextUnit()` Start a `TextUnit`.
    `void` | `startTextUnit(GenericSkeleton startMarker)` Start a complex `TextUnit`.
    `void` | `startTextUnit(GenericSkeleton startMarker, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` Start a complex `TextUnit` with actionable (translatable, writable or read-only) attributes.
    `void` | `startTextUnit(java.lang.String text)` Start a `TextUnit`.
    `void` | `startTextUnit(java.lang.String text, GenericSkeleton startMarker, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` Start a complex `TextUnit` with actionable (translatable, writable or read-only) attributes.
    `void` | `startTextUnit(java.lang.String text, GenericSkeleton startMarker, LocaleId locale, java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)` Start a complex `TextUnit` with actionable (translatable, writable or read-only) attributes.

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

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

- - ### Constructor Detail

    - #### EventBuilder

          public EventBuilder()

      Instantiates a new EventBuilder.

    - #### EventBuilder

          public EventBuilder(java.lang.String rootId,
                      IFilter filter)

      Instantiates a new EventBuilder with a root ID.
      Parameters:
        `rootId` - new root id (can be null or empty)
        `filter` - subfilter to use (can be null)

  - ### Method Detail

    - #### hasNext

          public boolean hasNext()

      Are we finished parsing the input document?
      Returns:
        true of the END_DOCUMENT event was received.

    - #### next

          public Event next()

      Return the next filter event waiting in the event queue.
      Returns:
        the current `Event`

    - #### addFilterEvent

          public void addFilterEvent(Event event)

      Add an `Event` at the end of the current `Event` queue.
      Parameters:
        `event` - The `Event` to be added

    - #### addFilterEvents

          public void addFilterEvents(java.util.List<Event> events)

    - #### cancel

          public void cancel()

      Cancel current processing and add the CANCELED `Event` to the event queue.

    - #### peekTempEvent

          public Event peekTempEvent()

    - #### popTempEvent

          public Event popTempEvent()

    - #### flushRemainingTempEvents

          public void flushRemainingTempEvents()

      Flush all remaining events from the `Event` queues

    - #### isCurrentTextUnit

          public boolean isCurrentTextUnit()

      Is the current buffered `Event` a `TextUnit`?
      Returns:
        true if TextUnit, false otherwise.

    - #### isCurrentComplexTextUnit

          public boolean isCurrentComplexTextUnit()

      Is the current buffered `Event` a complex `TextUnit`? A complex TextUnit is one which carries along with it it's surrounding formatting or skeleton such <p> text </p> or <title> text </title>
      Returns:
        true, if current `Event` is a complex text unit, false otherwise.

    - #### isCurrentGroup

          public boolean isCurrentGroup()

      Is the current buffered `Event` a `StartGroup`?
      Returns:
        true, if current `Event` is a `StartGroup`

    - #### isCurrentSubfilter

          public boolean isCurrentSubfilter()

      Is the current buffered `Event` a `StartSubfilter`?
      Returns:
        true, if current `Event` is a `StartSubfilter`

    - #### isInsideTextRun

          public boolean isInsideTextRun()

      Is the filter is inside text run?
      Returns:
        true, if is inside text run

    - #### canStartNewTextUnit

          public boolean canStartNewTextUnit()

      Can we start new `TextUnit`? A new `TextUnit` can only be started if the current one has been ended with endTextUnit. Or no `TextUnit` has been created yet.
      Returns:
        true, if can start a new `TextUnit`

    - #### hasQueuedEvents

          public boolean hasQueuedEvents()

      Are there any queued events? We queue events in the correct order as expected by the Okapi filter writers (IWriter).
      Returns:
        true, if successful

    - #### findMostRecentParentId

          public java.lang.String findMostRecentParentId()

    - #### findMostRecentParentName

          public java.lang.String findMostRecentParentName()

    - #### findMostRecentTextUnitName

          public java.lang.String findMostRecentTextUnitName()

      Find in our buffered queue the most recent TextUnit that has an assigned name
      Returns:
        - the TextUnit name, null if not found

    - #### peekMostRecentGroup

          public StartGroup peekMostRecentGroup()

      Peek at the most recently created `StartGroup` or `StartSubfilter`.
      Returns:
        the filter event

    - #### peekMostRecentSubDocument

          public StartSubDocument peekMostRecentSubDocument()

      Peek at the most recently created `StartSubDocument`
      Returns:
        the filter event

    - #### peekMostRecentTextUnit

          public ITextUnit peekMostRecentTextUnit()

      Peek At the most recently created `TextUnit`.
      Returns:
        the filter event

    - #### peekMostRecentCode

          public Code peekMostRecentCode()

      Peek at the most recently created `StartGroup`.
      Returns:
        the filter event

    - #### hasUnfinishedSkeleton

          public boolean hasUnfinishedSkeleton()

      Is there an unfinished `DocumentPart` (aka skeleton)?
      Returns:
        true, if successful

    - #### hasParentTextUnit

          public boolean hasParentTextUnit()

      Does the current `TextUnit` have a parent?
      Returns:
        true, if successful

    - #### reset

          public void reset(java.lang.String rootId,
                   IFilter filter)

      Parameters:
        `rootId` - new root id (can be null or empty)
        `filter` - subfilter to use (can be null) Reset `IFilter` for a new input. Callers should reset the EventBuilder for each input.

    - #### startSubDocument

          public StartSubDocument startSubDocument()

      Add the START_SUBDOCUMENT `Event` to the event queue.
      Returns:
        the `StartSubDocument` created and added, or null if there is no `subFilter`

    - #### endSubDocument

          public void endSubDocument()

      Add the END_SUBDOCUMENT `Event` to the event queue.

    - #### addTextUnit

          public void addTextUnit(java.lang.String text)

      Start and end a `TextUnit`. Also create a TextUnit `Event` and add it to the event queue.
      Parameters:
        `text` - the text used to prime the `TextUnit`

    - #### startTextUnit

          public void startTextUnit(java.lang.String text)

      Start a `TextUnit`. Also create a TextUnit `Event` and add it to the event queue.
      Parameters:
        `text` - the text used to prime the `TextUnit`

    - #### startTextUnit

          public void startTextUnit()

      Start a `TextUnit`. Also create a TextUnit `Event` and add it to the event queue.

    - #### startTextUnit

          public void startTextUnit(GenericSkeleton startMarker)

      Start a complex `TextUnit`. Also create a TextUnit `Event` and add it to the event queue.
      Parameters:
        `startMarker` - the tag that begins the complex `TextUnit`

    - #### startTextUnit

          public void startTextUnit(GenericSkeleton startMarker,
                           java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      Start a complex `TextUnit` with actionable (translatable, writable or read-only) attributes. Also create a TextUnit `Event` and add it to the event queue.
      Parameters:
        `startMarker` - the tag that begins the complex `TextUnit`
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.

    - #### startTextUnit

          public void startTextUnit(java.lang.String text,
                           GenericSkeleton startMarker,
                           java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      Start a complex `TextUnit` with actionable (translatable, writable or read-only) attributes. Also create a TextUnit `Event` and add it to the event queue.
      Parameters:
        `startMarker` - the tag that begins the complex `TextUnit`
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.
        `text` - the text used to prime the `TextUnit`

    - #### startTextUnit

          public void startTextUnit(java.lang.String text,
                           GenericSkeleton startMarker,
                           LocaleId locale,
                           java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      Start a complex `TextUnit` with actionable (translatable, writable or read-only) attributes. Also create a TextUnit `Event` and add it to the event queue.
      Parameters:
        `startMarker` - the tag that begins the complex `TextUnit`
        `text` - the text used to prime the `TextUnit`
        `locale` - the locale of the text
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.

    - #### convertTempTextUnitToDocumentPart

          public void convertTempTextUnitToDocumentPart()

      Convert the skeleton attached to an in-progress `TextUnit` into a `DocumentPart`. This is used when a TextUnit has been started but then is immediately ended without any content. The final skeleton part in the TU is always a self-reference, which is stripped during the conversion.

    - #### endTextUnit

          public ITextUnit endTextUnit()

      End the current `TextUnit` and place the `Event` on the event queue.
      Returns:
        the ended `TextUnit`

    - #### endTextUnit

          public ITextUnit endTextUnit(GenericSkeleton endMarker)

      End the current `TextUnit` and place the `Event` on the event queue.
      Parameters:
        `endMarker` - the tag that ends the complex `TextUnit`
      Returns:
        the ended `TextUnit`

    - #### endTextUnit

          public ITextUnit endTextUnit(GenericSkeleton endMarker,
                              LocaleId locale,
                              java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      End the current `TextUnit` and place the `Event` on the event queue.
      Parameters:
        `endMarker` - the tag that ends the complex `TextUnit`
        `locale` - the locale of the text
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.
      Returns:
        the ended `TextUnit`
      Throws:
        `OkapiIllegalFilterOperationException` - if we try to perform an invalid operation.

    - #### addToTextUnit

          public void addToTextUnit(java.lang.String text)

      Adds text to the current `TextUnit`
      Parameters:
        `text` - the text
      Throws:
        `OkapiIllegalFilterOperationException` - if we try to perform an invalid operation.

    - #### addToTextUnit

          public void addToTextUnit(ITextUnit textUnit)

      Adds a child TextUnit to the current (parent) `TextUnit`
      Parameters:
        `textUnit` - the `ITextUnit` to add
      Throws:
        `OkapiIllegalFilterOperationException` - if we try to perform an invalid operation.

    - #### addToTextUnit

          public void addToTextUnit(Code code)

      Add a `Code` to the current `TextUnit`. Nothing is actionable within the tag (i.e., no properties or translatable, localizable text)
      Parameters:
        `code` - the code type
      Throws:
        `OkapiIllegalFilterOperationException` - if we try to perform an invalid operation.

    - #### addToTextUnit

          public void addToTextUnit(Code code,
                           boolean endCodeNow)

      Add a `Code` to the current `TextUnit`. Nothing is actionable within the tag (i.e., no properties or translatable, localizable text)
      Parameters:
        `code` - the code type
        `endCodeNow` - do we end the code now or delay?
      Throws:
        `OkapiIllegalFilterOperationException` - if we try to perform an invalid operation.

    - #### addToTextUnit

          public void addToTextUnit(Code code,
                           boolean endCodeNow,
                           java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      Add a `Code` to the current `TextUnit`. The Code contains actionable (i.e., translatable, localizable) attributes.
      Parameters:
        `code` - the code
        `endCodeNow` - do we end the code now or delay?
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.

    - #### addToTextUnit

          public void addToTextUnit(Code code,
                           boolean endCodeNow,
                           LocaleId locale,
                           java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      Add a `Code` to the current `TextUnit`. The Code contains actionable (i.e., translatable, localizable) attributes.
      Parameters:
        `code` - the code
        `endCodeNow` - do we end the code now or delay?
        `locale` - the language of the text
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.
      Throws:
        `OkapiIllegalFilterOperationException` - if we try to perform an invalid operation.

    - #### appendToFirstSkeletonPart

          public void appendToFirstSkeletonPart(java.lang.String text)

      Appends text to the first data part of the skeleton.
      Parameters:
        `text` - the text to happend.
      Throws:
        `OkapiIllegalFilterOperationException` - if we try to perform an invalid operation.

    - #### startGroup

          public StartGroup startGroup(GenericSkeleton startMarker,
                              java.lang.String commonTagType)

      Create a `StartGroup` `Event` and add it to the event queue.
      Parameters:
        `startMarker` - the tag which starts the group
        `commonTagType` - the tag name or abstract type for this group.
      Returns:
        the newly created StartGroup

    - #### startGroup

          public StartGroup startGroup(GenericSkeleton startMarker,
                              java.lang.String commonTagType,
                              LocaleId locale,
                              java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      Create a `StartGroup` `Event` and add it to the event queue.
      Parameters:
        `startMarker` - the tag which starts the group.
        `commonTagType` - the tag name or abstract type for this group.
        `locale` - the language of any actionable items
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.
      Returns:
        the newly created StartGroup

    - #### endGroup

          public Ending endGroup(GenericSkeleton endMarker)

      Create a `Ending` `Event` of type END_GROUP and add it to the event queue.
      Parameters:
        `endMarker` - the tags that ends the group.
      Returns:
        the newly created Ending

    - #### endGroup

          public Ending endGroup(GenericSkeleton endMarker,
                        LocaleId locale,
                        java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      Create a `Ending` `Event` of type END_GROUP and add it to the event queue.
      Parameters:
        `endMarker` - the tags that ends the group.
        `locale` - the language of any actionable items
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.
      Returns:
        the newly created Ending
      Throws:
        `OkapiIllegalFilterOperationException` - if we try to perform an invalid operation.

    - #### startCode

          public void startCode(Code code)

    - #### endCode

          public void endCode()

    - #### endCode

          public void endCode(java.lang.String tag)

    - #### appendCodeOuterData

          public void appendCodeOuterData(java.lang.String outerData)

      append to the current `Code`'s outerData
      Parameters:
        `outerData` - the outerData to append

    - #### appendCodeData

          public void appendCodeData(java.lang.String data)

      append to the current `Code`'s data
      Parameters:
        `data` - the data to append

    - #### addDocumentPart

          public DocumentPart addDocumentPart(java.lang.String part)

      Create a single `DocumentPart` and add a `DocumentPart` `Event` to the queue.
      Parameters:
        `part` - the `DocumentPart` (aka skeleton)
      Returns:
        the newly created DocumentPart

    - #### startDocumentPart

          public DocumentPart startDocumentPart(java.lang.String part)

      Create a `DocumentPart` and store it for later processing.
      Parameters:
        `part` - the `DocumentPart` (aka skeleton)
      Returns:
        the newly created DocumentPart

    - #### startDocumentPart

          public void startDocumentPart(java.lang.String part,
                               java.lang.String name,
                               java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      Create a `DocumentPart` that references actionable (i.e., translatable, localizable) properties and store it for later processing.
      Parameters:
        `part` - the `DocumentPart` (aka skeleton)
        `name` - the name
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.

    - #### startDocumentPart

          public void startDocumentPart(java.lang.String part,
                               java.lang.String name,
                               LocaleId locale,
                               java.util.List<PropertyTextUnitPlaceholder> propertyTextUnitPlaceholders)

      Create a `DocumentPart` that references actionable (i.e., translatable, localizable) properties and store it for later processing.
      Parameters:
        `part` - the `DocumentPart` (aka skeleton)
        `name` - the name
        `locale` - the language of any actionable items
        `propertyTextUnitPlaceholders` - the list of actionable `TextUnit` or `Properties` with offset information into the tag.

    - #### endDocumentPart

          public void endDocumentPart(java.lang.String part)

      End the current `DocumentPart` and finalize the `Event`. Place the `Event` on the event queue.
      Parameters:
        `part` - the `DocumentPart` (aka skeleton)

    - #### endDocumentPart

          public void endDocumentPart()

      End the `DocumentPart` and finalize the `Event`. Place the `Event` on the event queue.

    - #### addToDocumentPart

          public void addToDocumentPart(java.lang.String part)

      Add to the current `DocumentPart`.
      Parameters:
        `part` - the `DocumentPart` as a String.

    - #### setMimeType

          public void setMimeType(java.lang.String mimeType)

      Sets the input document mime type.
      Parameters:
        `mimeType` - the new mime type

    - #### setTextUnitMimeType

          public void setTextUnitMimeType(java.lang.String mimeType)

      Set the mime type on the current `TextUnit`
      Parameters:
        `mimeType` - - mime type

    - #### setPreserveWhitespace

          public void setPreserveWhitespace(boolean preserveWhitespace)

      Tell the `IFilter` what to do with whitespace.
      Parameters:
        `preserveWhitespace` - the preserveWhitespace as boolean.

    - #### setTextUnitPreserveWhitespace

          public void setTextUnitPreserveWhitespace(boolean preserveWhitespace)

      Set preserve whitespace flag on current `TextUnit`
      Parameters:
        `preserveWhitespace` - the preserveWhitespace as boolean.

    - #### isPreserveWhitespace

          public boolean isPreserveWhitespace()

      What is the current preserve whitespace state?
      Returns:
        true if whitespace is to be preserved, false otherwise

    - #### getTextUnitId

          public long getTextUnitId()

      Gets the custom textUnitId set by the caller.
      Returns:
        the textUnitId

    - #### getCurrentCode

          public Code getCurrentCode()

      Get the current `Code`. COuld be null.
      Returns:
        the `Code`

    - #### setTextUnitId

          public void setTextUnitId(long id)

      Set the current textUnitId. Note that using this method overrides the built-in id creation algorithm. Useful for some callers that wish to create custom ids.
      Parameters:
        `id` - the initial value for the textUnitId

    - #### setTextUnitName

          public void setTextUnitName(java.lang.String name)

      Set the current `TextUnit` name.
      Parameters:
        `name` - the name (resname in XLIFF) of the `TextUnit`
      Throws:
        `java.lang.NullPointerException` - if there is no current `TextUnit`

    - #### setTextUnitType

          public void setTextUnitType(java.lang.String type)

      Set the current `TextUnit` type. If there is no defined type the type is the element name.
      Parameters:
        `type` - - the TextUnit type.

    - #### setTextUnitTranslatable

          public void setTextUnitTranslatable(boolean translatable)

      Set the current `TextUnit` translatable flag.
      Parameters:
        `translatable` - - the TextUnit translatable flag.

    - #### getDocumentPartId

          public long getDocumentPartId()

      Gets the current custom `DocumentPart` id.
      Returns:
        the id

    - #### setDocumentPartId

          public void setDocumentPartId(long id)

      Set the current custom `DocumentPart` id. Note that using this method overrides the built-in id creation algorithm. Useful for some callers that wish to create custom ids.
      Parameters:
        `id` - the initial value for the textUnitId

    - #### getRootId

          public java.lang.String getRootId()

      Get the current root id
      Returns:
        the rootId

    - #### postProcessTextUnit

          protected ITextUnit postProcessTextUnit(ITextUnit textUnit)

      Do any required post-processing on the TextUnit after endTextUnit is called. Default implementation leaves TextUnit unchanged. Override this method if you need to do format specific handing such as collapsing whitespace.
      Parameters:
        `textUnit` - the `ITextUnit` to post-process.
      Returns:
        the post-processed `ITextUnit`.

    - #### isTextUnitWithSameType

          public boolean isTextUnitWithSameType(java.lang.String type)

      Is the current TextUnit of the specified type?
      Parameters:
        `type` - a `TextUnit` type.
      Returns:
        true if the current `TextUnit` type is the same as the parameter type.

    - #### getGroupId

          public IdGenerator getGroupId()

      Get the `IdGenerator` for Groups
      Returns:
        the `IdGenerator`

    - #### getGroupIdSequence

          public long getGroupIdSequence()

    - #### setGroupIdSequence

          public void setGroupIdSequence(long id)

    - #### getSubDocumentId

          public IdGenerator getSubDocumentId()

      Get the `IdGenerator` for SubDocuments
      Returns:
        the `IdGenerator`

    - #### setTargetLocale

          public void setTargetLocale(LocaleId targetLocale)

      Set the target locale. Implies we are now processing a target, not source
      Parameters:
        `targetLocale` - - the target `LocaleId`

    - #### getTargetLocale

          public LocaleId getTargetLocale()

      Get the current target locale. If not null implies we are processing a target
      Returns:
        target locale or null if we are processing the source.