net.sf.mmm.content.parser.base

Class AbstractContentParser

java.lang.Object

net.sf.mmm.util.component.base.AbstractComponent

net.sf.mmm.util.component.base.AbstractLoggableComponent

net.sf.mmm.content.parser.base.AbstractContentParser

All Implemented Interfaces:

ContentParser

Direct Known Subclasses:

AbstractContentParserGeneric, AbstractContentParserOoxml, AbstractContentParserOpenDoc, AbstractContentParserPoi, AbstractContentParserText, ContentParserPdf, ContentParserXml

public abstract class AbstractContentParser
extends AbstractLoggableComponent
implements ContentParser

This is the abstract base implementation of a ContentParser. It handles the delegation methods, the creation of the MutableGenericContext and the safe closing of the InputStream.

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
private GenericContextFactory	genericContextFactory
private Set<String>	primaryKeys
private Set<String>	secondaryKeys

Fields inherited from interface net.sf.mmm.content.parser.api.ContentParser

VARIABLE_NAME_CREATOR, VARIABLE_NAME_KEYWORDS, VARIABLE_NAME_LANGUAGE, VARIABLE_NAME_TEXT, VARIABLE_NAME_TITLE

Constructor Summary

Constructors

Constructor and Description
AbstractContentParser() The constructor.

Method Summary

Modifier and Type	Method and Description
protected void	doInitialize() This method performs the actual initialization.
String[]	getAlternativeKeyArray() This method gets the alternative primary keys in addition to extension and mimetype.
Set<String>	getPrimaryKeys() This method gets the primary keys used to register this ContentParser.
String[]	getSecondaryKeyArray() This method gets the secondary keys as array.
Set<String>	getSecondaryKeys() This method gets the secondary keys used to register this ContentParser.
GenericContext	parse(InputStream inputStream, long filesize) This method parses the document given as inputStream and extracts text and metadata returned as GenericContext.
GenericContext	parse(InputStream inputStream, long filesize, ContentParserOptions options) This method parses the document given as inputStream and extracts text and metadata returned as GenericContext.
protected abstract void	parse(InputStream inputStream, long filesize, ContentParserOptions options, MutableGenericContext context)
void	setGenericContextFactory(GenericContextFactory genericContextFactory)

Methods inherited from class net.sf.mmm.util.component.base.AbstractLoggableComponent

createLogger, getLogger

Methods inherited from class net.sf.mmm.util.component.base.AbstractComponent

doInitialized, getInitializationState, initialize

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.mmm.content.parser.api.ContentParser

getExtension, getMimetype

Field Detail

genericContextFactory

private GenericContextFactory genericContextFactory

See Also:

setGenericContextFactory(GenericContextFactory)

primaryKeys

private final Set<String> primaryKeys

See Also:

getPrimaryKeys()

secondaryKeys

private final Set<String> secondaryKeys

See Also:

getSecondaryKeys()

Constructor Detail

AbstractContentParser

public AbstractContentParser()

The constructor.

Method Detail

setGenericContextFactory

@Inject
public void setGenericContextFactory(GenericContextFactory genericContextFactory)

Parameters:

genericContextFactory - is the genericContextFactory to set

doInitialize

protected void doInitialize()

This method performs the actual initialization. It is called when AbstractComponent.initialize() is invoked for the first time.
ATTENTION:
When you override this method from a sub-class you need to do a super.AbstractComponent.doInitialize().

Overrides:

doInitialize in class AbstractLoggableComponent

getPrimaryKeys

public final Set<String> getPrimaryKeys()

This method gets the primary keys used to register this ContentParser. This set contains extension and mimetype and maybe other alternatives.
Examples:

• An HTML-parser will return "html" for ContentParser.getExtension() but can also include "htm" as primary key.
• A text-parser with extension "tar.gz" may also include "tgz" as primary key.
• An XML-parser with mimetype "text/xml" may also include "application/xml" as primary key.

Specified by:

getPrimaryKeys in interface ContentParser

Returns:

the alias keys (extensions and mimetypes) of this ContentParser.

See Also:

ContentParserService.getParser(String), ContentParser.getSecondaryKeys(), Collections.emptySet()

getAlternativeKeyArray

public String[] getAlternativeKeyArray()

This method gets the alternative primary keys in addition to extension and mimetype.

Returns:

an array with the alternative keys.

See Also:

getPrimaryKeys()

getSecondaryKeyArray

public String[] getSecondaryKeyArray()

This method gets the secondary keys as array. This is just a convenience to make it easier for the implementors of individual parsers not to deal with creating a Set and make it unmodifiable.

Returns:

an array with the alternative keys.

See Also:

getPrimaryKeys()

getSecondaryKeys

public final Set<String> getSecondaryKeys()

This method gets the secondary keys used to register this ContentParser. If an other (more specific) ContentParser defines such key as primary key, that ContentParser is chosen first. Otherwise this implementation will be used.
Examples:

• An HTML-parser will return "html" for ContentParser.getExtension() but can define "xhtml" and "application/xhtml+xml" as secondary key.
• A text-parser with extension "txt" may return "java", "php", "c", "cpp", etc. as secondary keys.

Specified by:

getSecondaryKeys in interface ContentParser

Returns:

the alias keys (extensions and mimetypes) of this ContentParser.

See Also:

ContentParserService.getParser(String), ContentParser.getPrimaryKeys(), Collections.emptySet()

parse

public final GenericContext parse(InputStream inputStream,
                                  long filesize)
                           throws Exception

This method parses the document given as inputStream and extracts text and metadata returned as GenericContext.

Specified by:

parse in interface ContentParser

Parameters:

inputStream - is the fresh input stream of the content to parse. It will be closed by this method (on success and in exceptional state).

filesize - is the size (content-length) of the content to parse in bytes or 0 if NOT available (unknown). If available, the parser may use this value for optimized allocations.

Returns:

the GenericContext containing the extracted metadata from the parsed inputStream. See the VARIABLE_NAME_* constants (e.g. ContentParser.VARIABLE_NAME_TEXT) for the default keys. Please note that an implementation may use individual names for additional variables.

Throws:

Exception - if the parsing failed for a technical reason. There can be arbitrary implementations for this interface that can throw any Exception from this method. Declaring a specific ParseException here would cause the overhead of additional encapsulation of exceptions without any advantage. The user of this interface has to catch for Exception what includes RuntimeExceptions and excludes Errors. He has to handle the problem anyways (also for RuntimeExceptions) and has all contextual information required to enhance the exception message. This is NOT a matter of bad design.

parse

public GenericContext parse(InputStream inputStream,
                            long filesize,
                            ContentParserOptions options)
                     throws Exception

This method parses the document given as inputStream and extracts text and metadata returned as GenericContext.

Specified by:

parse in interface ContentParser

Parameters:

inputStream - is the fresh input stream of the content to parse. It will be closed by this method (on success and in exceptional state).

filesize - is the size (content-length) of the content to parse in bytes or 0 if NOT available (unknown). If available, the parser may use this value for optimized allocations.

options - are the ContentParserOptions.

Returns:

the GenericContext containing the extracted metadata from the parsed inputStream. See the VARIABLE_NAME_* constants (e.g. ContentParser.VARIABLE_NAME_TEXT) for the default keys. Please note that an implementation may use individual names for additional variables.

Throws:

Exception - if the parsing failed for a technical reason. There can be arbitrary implementations for this interface that can throw any Exception from this method. Declaring a specific ParseException here would cause the overhead of additional encapsulation of exceptions without any advantage. The user of this interface has to catch for Exception what includes RuntimeExceptions and excludes Errors. He has to handle the problem anyways (also for RuntimeExceptions) and has all contextual information required to enhance the exception message. This is NOT a matter of bad design.

parse

protected abstract void parse(InputStream inputStream,
                              long filesize,
                              ContentParserOptions options,
                              MutableGenericContext context)
                       throws Exception

Parameters:

inputStream - is the fresh input stream of the content to parse.

filesize - is the size (content-length) of the content to parse in bytes or 0 if NOT available (unknown). If available, the parser may use this value for optimized allocations.

options - are the ContentParserOptions.

context - is the MutableGenericContext where the extracted metadata from the parsed inputStream will be added to.

Throws:

Exception - if the operation fails for arbitrary reasons.

See Also:

ContentParser.parse(InputStream, long)