biz.c24.io.api.presentation
Interface ParseListener


public interface ParseListener

Parse listener interface.

Provides the API between the Source and the application performing batched parsing. The implementation of this interface will be notified of the following events as they occur during the parsing of a batched complex data type:

  • Start of parsing a batch,
  • Successful parsing of a batch entry (i.e. any element directly nested inside of batch),
  • Failure to parse a batch entry (i.e. any element directly nested inside of batch),
  • End of parsing a batch.
  • Batch processing is designed to provide a robbust mechanism to parse each batch entry as an independent entity. This means the parser will not stop parsing when it sees an invalid batch entry. Instead it will notify the registered ParseListener of the failure and then skip to the start of the next batch entry. Thus batch entries have to have recognisable boundaries specified by their initiator or terminators or the containing batches delimiters.

    The onBatchEntryParsed(Object) returns an Object which will be attached to it's parent Complex Data Object (i.e. the batch). In general this returned value will be the argument to the method. Prior to returning from this method, the object argument can be altered or replaced or a null value may be returned which will prevent the Source from adding the value to the batch. When processing large files or long streams it can be useful to return null and instead process the batch entry from within the onBatchEntryParsed(Object) method. This allows for abitrary size files / streams to be read.

    Whenever parsing of any batch entry fails, the client application will have the approximately reconstructed partially parsed Complex Data Object. The reconstruction process attempts to construct the object as close as possible to the expected value. If any part of batch entry couldn't be instantiated then a new element will be constructed with the data that can't be parsed. The name of new element can be specified by client application via the generate name callback.


    Method Summary
     String generateFailedName(String original)
              New element name generator.
     boolean isAdditionalBatch(Element element)
              Returns whether the specified element should be considered a batch during this parse operation.
     void onBatchEntryFailed(Object object, ParserException failure)
              Called on failure to parse a batch entry.
     Object onBatchEntryParsed(Object object)
              Called on successful parsing of a batch entry.
     void onEndBatch(Element element)
              End batch parsing callback.
     void onStartBatch(Element element)
              Start of batch parsing callback.
     

    Method Detail

    onStartBatch

    void onStartBatch(Element element)
                      throws ParserException
    Start of batch parsing callback.

    Called when a new Complex Data Type marked as batch is found in the data stream.

    Parameters:
    element - the element that will be parsed as a batch.
    Throws:
    ParserException - if parsing should be stopped.

    onEndBatch

    void onEndBatch(Element element)
                    throws ParserException
    End batch parsing callback.

    Called after a Complex Data Type marked as batch been found in the data stream.

    Parameters:
    element - the element that was parsed as a batch.
    Throws:
    ParserException - if parsing should be stopped.

    onBatchEntryParsed

    Object onBatchEntryParsed(Object object)
                              throws ParserException
    Called on successful parsing of a batch entry.

    Called each time a batch entry is successfully parsed. Implementation is responsible for returning the object to be attached to the parent. Usually this will just be the object argument but for long streams the object can be processed from this method implementation and a null value can be returned. This will prevent the collection of all data in memory and allow each batch entry to be garbage collected before the return of the Source.readObject(biz.c24.io.api.data.Element) method.

    Parameters:
    object - the batch entry that was parsed.
    Returns:
    the batch entry to be added to parent or null otherwise.
    Throws:
    ParserException - if parsing should be stopped.

    onBatchEntryFailed

    void onBatchEntryFailed(Object object,
                            ParserException failure)
                            throws ParserException
    Called on failure to parse a batch entry.

    Called each time a batch entry was not parsed. The reason(s) of failure is provided as failure parameter.

    Parameters:
    object - the batch entry instance that was reconstructed.
    failure - the parser exception that contains list of all parser error reason that caused that failure.
    Throws:
    ParserException - if parsing should be stopped.

    generateFailedName

    String generateFailedName(String original)
    New element name generator.

    Designed to provide the name of the new element during reconstruction process. The implementation must provide the way to generate the name of the new element for unparsable data.

    Parameters:
    original - the original name of element that was failed to parse.
    Returns:
    the name for new element for unparsable data.

    isAdditionalBatch

    boolean isAdditionalBatch(Element element)
    Returns whether the specified element should be considered a batch during this parse operation.
    Returning true from this method effectively allows runtime configurable, source specific, customization of the "process as batch" flag on any element in the model.
    Most implementations will simply return false and allow the C24 Integration Objects API to defer to the model instead.

    Parameters:
    element - The element in question.
    Returns:
    Whether it should be processed as if it's type was marked as "process as batch".


    C24 Technologies © 2002-2012: All Rights Reserved.