net.sf.mmm.content.parser.api

Interface ContentParser

All Known Implementing Classes:

AbstractContentParser, AbstractContentParserGeneric, AbstractContentParserOoxml, AbstractContentParserOpenDoc, AbstractContentParserPoi, AbstractContentParserText, AbstractContentParserTextMarkupAware, ContentParserDoc, ContentParserDocx, ContentParserGeneric, ContentParserHtml, ContentParserJava, ContentParserOdb, ContentParserOdc, ContentParserOdf, ContentParserOdg, ContentParserOdi, ContentParserOdm, ContentParserOdp, ContentParserOds, ContentParserOdt, ContentParserOth, ContentParserPdf, ContentParserPpt, ContentParserPptx, ContentParserText, ContentParserTextMarkupAware, ContentParserXls, ContentParserXlsx, ContentParserXml

@ComponentSpecification(plugin=true)
public interface ContentParser

This is the interface for a parser that extracts (meta-)data from the content of an InputStream.
ATTENTION:
The implementation should allocate expensive resources (e.g. byte-arrays) only temporary while parsing. See also ContentParserOptions.getMaximumBufferSize().

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
static String	VARIABLE_NAME_CREATOR This is the name of the variable with the creator (also called author, artist, composer, etc.) of the content from the parsed GenericContext.
static String	VARIABLE_NAME_KEYWORDS This is the name of the variable with the keywords (also called tags) of the content from the parsed GenericContext.
static String	VARIABLE_NAME_LANGUAGE This is the name of the variable with the language of the content from the parsed GenericContext.
static String	VARIABLE_NAME_TEXT This is the name of the variable with the plain text of the content from the parsed GenericContext.
static String	VARIABLE_NAME_TITLE This is the name of the variable with the title of the content from the parsed GenericContext.

Method Summary

Modifier and Type	Method and Description
String	getExtension() This method gets the default filename extension excluding the dot (e.g.
String	getMimetype() This method gets the default mimetype (e.g.
Set<String>	getPrimaryKeys() This method gets the primary keys used to register this ContentParser.
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.

Field Detail

VARIABLE_NAME_TEXT

static final String VARIABLE_NAME_TEXT

This is the name of the variable with the plain text of the content from the parsed GenericContext.
This variable has the type String and should always be set (not null).

See Also:

Constant Field Values

VARIABLE_NAME_TITLE

static final String VARIABLE_NAME_TITLE

This is the name of the variable with the title of the content from the parsed GenericContext.
It has the type String and is optional (may be null).

See Also:

Constant Field Values

VARIABLE_NAME_KEYWORDS

static final String VARIABLE_NAME_KEYWORDS

This is the name of the variable with the keywords (also called tags) of the content from the parsed GenericContext.
It has the type String and is optional (may be null).

See Also:

Constant Field Values

VARIABLE_NAME_CREATOR

static final String VARIABLE_NAME_CREATOR

This is the name of the variable with the creator (also called author, artist, composer, etc.) of the content from the parsed GenericContext.
It has the type String and is optional (may be null).

See Also:

Constant Field Values

VARIABLE_NAME_LANGUAGE

static final String VARIABLE_NAME_LANGUAGE

This is the name of the variable with the language of the content from the parsed GenericContext.
It has the type String and is optional (may be null).

See Also:

Constant Field Values

Method Detail

parse

GenericContext parse(InputStream inputStream,
                     long filesize)
              throws Exception

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

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

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.

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

getExtension

String getExtension()

This method gets the default filename extension excluding the dot (e.g. "txt", "xml", "html", "pdf", etc.) for the content managed by this ContentParser.

Returns:

the default filename extension or null if this is the generic parser.

getMimetype

String getMimetype()

This method gets the default mimetype (e.g. "text/plain", "text/xml", "text/html", "application/pdf", etc.) for the content managed by this ContentParser.

Returns:

the default filename extension or null if this is the generic parser.

getPrimaryKeys

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

Returns:

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

See Also:

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

getSecondaryKeys

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

Returns:

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

See Also:

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