Package net.sf.okapi.common.filters

Class EventBuilder

  • All Implemented Interfaces:
    Iterator<Event>
    Direct Known Subclasses:
    AbstractMarkupEventBuilder, JsonEventBuilder, MarkdownEventBuilder, WhitespaceAdjustingEventBuilder, YamlEventBuilder
    public class EventBuilder
extends Object
implements Iterator<Event>
    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 Detail

      • EventBuilder

        public EventBuilder()
        Instantiates a new EventBuilder.

      • EventBuilder

        public EventBuilder​(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?
        Specified by:
        hasNext in interface Iterator<Event>
        Returns:
        true of the END_DOCUMENT event was received.

      • next

        public Event next()
        Return the next filter event waiting in the event queue.
        Specified by:
        next in interface Iterator<Event>
        Returns:
        the current Event

      • addFilterEvent

        public void addFilterEvent​(Event event)
        Add a single Event at the end of the current Event queue. Assume all child events have already been added in case of an IReferenceable Event as all children events must come before their parent reference.
        Parameters:
        event - The Event to be added

      • addFilterEvents

        public void addFilterEvents​(List<Event> events)
        Add an list of Event at the end of the current Event queue. Assume all child events have already been added in case of an IReferenceable Event as all children events must come before their parent reference.
        Parameters:
        events - The list of Event to be added

      • 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 temp queue

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

      • 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 String findMostRecentParentId()

      • findMostRecentParentName

        public String findMostRecentParentName()

      • findMostRecentTextUnitName

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

      • 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​(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​(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​(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,
                          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​(String text,
                          GenericSkeleton startMarker,
                          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​(String text,
                          GenericSkeleton startMarker,
                          LocaleId locale,
                          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.

      • 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,
                          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,
                          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​(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.

      • appendToSkeleton

        public void appendToSkeleton​(GenericSkeleton part)
        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,
                             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,
                             String commonTagType,
                             LocaleId locale,
                             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

      • startCode

        public void startCode​(Code code)

      • endCode

        public void endCode()

      • endCode

        public void endCode​(String tag)

      • appendCodeOuterData

        public void appendCodeOuterData​(String outerData)
        append to the current Code's outerData
        Parameters:
        outerData - the outerData to append

      • appendCodeInlineExcludedData

        public void appendCodeInlineExcludedData​(String data)
        append to the current Code's data
        Parameters:
        data - the data to append

      • startDocumentPart

        public DocumentPart startDocumentPart​(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​(String part,
                              String name,
                              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​(String part,
                              String name,
                              LocaleId locale,
                              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​(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​(String part)
        Add to the current DocumentPart.
        Parameters:
        part - the DocumentPart as a String.

      • setMimeType

        public void setMimeType​(String mimeType)
        Sets the input document mime type.
        Parameters:
        mimeType - the new mime type

      • setTextUnitMimeType

        public void setTextUnitMimeType​(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

      • setTextUnitType

        public void setTextUnitType​(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 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​(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.

      • getGroupIdSequence

        public long getGroupIdSequence()

      • setGroupIdSequence

        public void setGroupIdSequence​(long id)