Class MarkupParser

  • All Implemented Interfaces:
    IMarkupParser

    public final class MarkupParser
    extends java.lang.Object
    implements IMarkupParser

    Default implementation of the IMarkupParser interface.

    AttoParser markup parsers work as SAX-style parsers that need a markup handler object for handling parsing events. These handlers implement the IMarkupHandler interface, and are normally developed by users in order to perform the operations they require for their applications.

    See the documentation of the IMarkupHandler interface for more information on the event handler methods, and also on the handler implementations AttoParser provides out-of-the-box.

    Also, note there are two different specialized parsers that use MarkupParser underneath, but which are oriented towards allowing an easy use of specific parsing features: IDOMMarkupParser for DOM-oriented parsing and ISimpleMarkupParser for using a simplified version of the handler interface (ISimpleMarkupHandler).

    Sample usage:

    
       // Obtain a java.io.Reader on the document to be parsed
       final Reader documentReader = ...;
    
       // Create the handler instance. Extending the no-op AbstractMarkupHandler is a good start
       final IMarkupHandler handler = new AbstractMarkupHandler() {
           ... // some events implemented
       };
    
       // Create or obtain the parser instance (can be reused). Example uses the default configuration for HTML
       final IMarkupParser parser = new MarkupParser(ParseConfiguration.htmlConfiguration());
    
       // Parse it!
       parser.parse(documentReader, handler);
     

    This parser class is thread-safe. However, take into account that, normally, IMarkupHandler implementations are not. So, even if parsers can be reused, handler objects usually cannot.

    This parser class uses a (configurable) pool of char[] buffers, in order to reduce the amount of memory used for parsing (buffers are large structures). This pool works in a non-blocking mode, so if a new buffer is needed and all are currently allocated, a new (unpooled) char[] object is created and returned without waiting for a pooled buffer to be available.

    (Note that these pooled buffers will not be used when parsing documents specified as char[] objects. In such case, the char[] documents themselves will be used as buffers, avoiding the need to allocate pooled buffers or use any additional amount of memory.)

    Since:
    2.0.0
    • Field Detail

      • DEFAULT_BUFFER_SIZE

        public static final int DEFAULT_BUFFER_SIZE

        Default buffer size to be used (buffer size will grow at runtime if an artifact (structure or text) is bigger than the whole buffer). Value: 4096 chars (= 8192 bytes).

        See Also:
        Constant Field Values
      • DEFAULT_POOL_SIZE

        public static final int DEFAULT_POOL_SIZE

        Default pool size to be used. Buffers will be kept in a pool and reused in order to increase performance. Pool will be non-exclusive so that if pool size = 2 and a 3rd request arrives, it is assigned a new buffer object (not linked to the pool, and therefore GC-ed at the end). Value: 2.

        See Also:
        Constant Field Values
    • Constructor Detail

      • MarkupParser

        public MarkupParser​(ParseConfiguration configuration)

        Creates a new instance of this parser, using the specified configuration and default sizes for pool (DEFAULT_POOL_SIZE) and pooled buffers (DEFAULT_BUFFER_SIZE).

        Parameters:
        configuration - the parsing configuration to be used.
      • MarkupParser

        public MarkupParser​(ParseConfiguration configuration,
                            int poolSize,
                            int bufferSize)

        Creates a new instance of this parser, specifying the pool and buffer size.

        Buffer size (in chars) will be the size of the char[] structures used as buffers for parsing, which might grow if a certain markup structure does not fit inside (e.g. a text). Default size is DEFAULT_BUFFER_SIZE.

        Pool size is the size of the pool of char[] buffers that will be kept in memory in order to allow their reuse. This pool works in a non-exclusive mode, so that if pool size is 3 and a 4th request arrives, it is served a new non-pooled buffer without the need to block waiting for one of the pooled instances. Default size is DEFAULT_POOL_SIZE.

        Note that these pooled buffers will not be used when parsing documents specified as char[] objects. In such case, the char[] documents themselves will be used as buffers, avoiding the need to allocate buffers or use any additional amount of memory.

        Parameters:
        configuration - the parsing configuration to be used.
        poolSize - the size of the pool of buffers to be used.
        bufferSize - the default size of the buffers to be instanced for this parser.