net.sf.mmm.util.xml.api
Interface XmlUtil

All Known Implementing Classes:

XmlUtilImpl

@ComponentSpecification
public interface XmlUtil

This is the interface for a collection of utility functions that help to deal with XML.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

DomUtil, StaxUtil, XmlUtilImpl.getInstance()

Field Summary

static String	NAMESPACE_PREFIX_SCHEMA the default namespace prefix for XML-Schema
static String	NAMESPACE_PREFIX_SCHEMA_INSTANCE the default namespace prefix for XML-Schema
static String	NAMESPACE_PREFIX_SVG the default namespace prefix for SVG
static String	NAMESPACE_PREFIX_XHTML the default namespace prefix for XHTML
static String	NAMESPACE_PREFIX_XINCLUDE the default namespace prefix for XInclude
static String	NAMESPACE_PREFIX_XLINK the default namespace prefix for XLink
static String	NAMESPACE_PREFIX_XML the reserved xmlns namespace prefix
static String	NAMESPACE_PREFIX_XML_EVENTS the default namespace prefix for XML-Events
static String	NAMESPACE_PREFIX_XMLNS the reserved xmlns namespace prefix
static String	NAMESPACE_PREFIX_XPATH_FUNCTIONS the default namespace prefix for XML-Schema
static String	NAMESPACE_PREFIX_XSLT the default namespace prefix for XSLT
static String	NAMESPACE_URI_MATHML the URI of the MathML namespace
static String	NAMESPACE_URI_RELAXNG_ANNOTATION the URI of the RELAX-NG-Structure namespace
static String	NAMESPACE_URI_RELAXNG_STRUCTURE the URI of the RELAX-NG-Structure namespace
static String	NAMESPACE_URI_SCHEMA the URI of the XML-Schema namespace
static String	NAMESPACE_URI_SCHEMA_INSTANCE the URI of the XML-Schema namespace
static String	NAMESPACE_URI_SVG the URI of the SVG namespace
static String	NAMESPACE_URI_XHTML the URI of the XHTML namespace
static String	NAMESPACE_URI_XINCLUDE the URI of the XInclude namespace
static String	NAMESPACE_URI_XLINK the URI of the XLink namespace
static String	NAMESPACE_URI_XML the URI of the xmlns namespace
static String	NAMESPACE_URI_XML_EVENTS the URI of the XML-Events namespace
static String	NAMESPACE_URI_XMLNS the URI of the xmlns namespace
static String	NAMESPACE_URI_XPATH_FUNCTIONS the URI of the XML-Schema namespace
static String	NAMESPACE_URI_XSLT the URI of the XSLT namespace

Method Summary

Reader	createXmlReader(InputStream inputStream) This method creates a Reader from the given inputStream that uses the encoding specified in the (potential) XML header of the InputStreams content.
Reader	createXmlReader(InputStream inputStream, Charset defaultCharset) This method creates a Reader from the given inputStream that uses the encoding specified in the (potential) XML header of the InputStreams content.
String	escapeXml(String string, boolean escapeQuotations) This method escapes the given string for usage in XML (or HTML, etc.).
void	escapeXml(String string, Writer writer, boolean escapeQuotations) This method writes the given string to the writer while escaping special characters for XML (or HTML, etc.).
ParserState	extractPlainText(String htmlFragment, StringBuilder buffer, ParserState parserState) This method extracts the plain text from the given htmlFragment and appends it to the given buffer.
Character	resolveEntity(String entityName) This method resolves an HTML entity given by entityName.

Field Detail

NAMESPACE_URI_XML

static final String NAMESPACE_URI_XML

the URI of the xmlns namespace

NAMESPACE_PREFIX_XML

static final String NAMESPACE_PREFIX_XML

the reserved xmlns namespace prefix

NAMESPACE_URI_XMLNS

static final String NAMESPACE_URI_XMLNS

the URI of the xmlns namespace

NAMESPACE_PREFIX_XMLNS

static final String NAMESPACE_PREFIX_XMLNS

the reserved xmlns namespace prefix

NAMESPACE_URI_XINCLUDE

static final String NAMESPACE_URI_XINCLUDE

the URI of the XInclude namespace

NAMESPACE_PREFIX_XINCLUDE

static final String NAMESPACE_PREFIX_XINCLUDE

the default namespace prefix for XInclude

NAMESPACE_URI_XLINK

static final String NAMESPACE_URI_XLINK

the URI of the XLink namespace

NAMESPACE_PREFIX_XLINK

static final String NAMESPACE_PREFIX_XLINK

the default namespace prefix for XLink

NAMESPACE_URI_XSLT

static final String NAMESPACE_URI_XSLT

the URI of the XSLT namespace

NAMESPACE_PREFIX_XSLT

static final String NAMESPACE_PREFIX_XSLT

the default namespace prefix for XSLT

NAMESPACE_URI_SCHEMA

static final String NAMESPACE_URI_SCHEMA

the URI of the XML-Schema namespace

NAMESPACE_PREFIX_SCHEMA

static final String NAMESPACE_PREFIX_SCHEMA

the default namespace prefix for XML-Schema

NAMESPACE_URI_SCHEMA_INSTANCE

static final String NAMESPACE_URI_SCHEMA_INSTANCE

the URI of the XML-Schema namespace

NAMESPACE_PREFIX_SCHEMA_INSTANCE

static final String NAMESPACE_PREFIX_SCHEMA_INSTANCE

the default namespace prefix for XML-Schema

NAMESPACE_URI_XPATH_FUNCTIONS

static final String NAMESPACE_URI_XPATH_FUNCTIONS

the URI of the XML-Schema namespace

NAMESPACE_PREFIX_XPATH_FUNCTIONS

static final String NAMESPACE_PREFIX_XPATH_FUNCTIONS

the default namespace prefix for XML-Schema

NAMESPACE_URI_SVG

static final String NAMESPACE_URI_SVG

the URI of the SVG namespace

NAMESPACE_PREFIX_SVG

static final String NAMESPACE_PREFIX_SVG

the default namespace prefix for SVG

NAMESPACE_URI_MATHML

static final String NAMESPACE_URI_MATHML

the URI of the MathML namespace

NAMESPACE_URI_XHTML

static final String NAMESPACE_URI_XHTML

the URI of the XHTML namespace

NAMESPACE_PREFIX_XHTML

static final String NAMESPACE_PREFIX_XHTML

the default namespace prefix for XHTML

NAMESPACE_URI_XML_EVENTS

static final String NAMESPACE_URI_XML_EVENTS

the URI of the XML-Events namespace

NAMESPACE_PREFIX_XML_EVENTS

static final String NAMESPACE_PREFIX_XML_EVENTS

the default namespace prefix for XML-Events

NAMESPACE_URI_RELAXNG_STRUCTURE

static final String NAMESPACE_URI_RELAXNG_STRUCTURE

the URI of the RELAX-NG-Structure namespace

NAMESPACE_URI_RELAXNG_ANNOTATION

static final String NAMESPACE_URI_RELAXNG_ANNOTATION

the URI of the RELAX-NG-Structure namespace

Method Detail

escapeXml

String escapeXml(String string,
                 boolean escapeQuotations)

This method escapes the given string for usage in XML (or HTML, etc.).

Parameters:

string - is the string to escape.

escapeQuotations - if true also the ASCII quotation characters (apos '\'' and quot '"') will be escaped, else if false quotations are untouched. Set this to true if you are writing the value of an attribute.

Returns:

the escaped string.

escapeXml

void escapeXml(String string,
               Writer writer,
               boolean escapeQuotations)
               throws RuntimeIoException

This method writes the given string to the writer while escaping special characters for XML (or HTML, etc.).

Parameters:

string - is the string to escape.

writer - is where to write the string to.

escapeQuotations - if true also the ASCII quotation characters (apos '\'' and quot '"') will be escaped, else if false quotations are untouched. Set this to true if you are writing the value of an attribute.

Throws:

RuntimeIoException - if the writer produced an I/O error.

createXmlReader

Reader createXmlReader(InputStream inputStream)
                       throws RuntimeIoException

This method creates a Reader from the given inputStream that uses the encoding specified in the (potential) XML header of the InputStreams content. If no XML header is specified, the default encoding is used.

Parameters:

inputStream - is a fresh input-stream that is supposed to point to the content of an XML document.

Returns:

a reader on the given inputStream that takes respect on the encoding specified in the (potential) XML header.

Throws:

RuntimeIoException - if an I/O error occurred when trying to read the XML header.

createXmlReader

Reader createXmlReader(InputStream inputStream,
                       Charset defaultCharset)
                       throws RuntimeIoException

This method creates a Reader from the given inputStream that uses the encoding specified in the (potential) XML header of the InputStreams content. If no XML header is specified, the default encoding is used.

Parameters:

inputStream - is a fresh input-stream that is supposed to point to the content of an XML document.

defaultCharset - is the Charset used if NO encoding was specified via an XML header.

Returns:

a reader on the given inputStream that takes respect on the encoding specified in the (potential) XML header.

Throws:

RuntimeIoException - if an I/O error occurred when trying to read the XML header.

resolveEntity

Character resolveEntity(String entityName)

This method resolves an HTML entity given by entityName.

Parameters:

entityName - is the bare name of the entity (e.g. "amp" or "uuml"). Please note that entity-names are case-sensitive.

Returns:

the value of the entity or null if no entity exists for the given entityName.

extractPlainText

ParserState extractPlainText(String htmlFragment,
                             StringBuilder buffer,
                             ParserState parserState)

This method extracts the plain text from the given htmlFragment and appends it to the given buffer. This includes removing tags, un-escaping entities and parsing CDATA sections. Unlike DOM parsers this method is completely fault tolerant, fast and uses a minimum amount of memory.
ATTENTION:
Be aware that the caller is responsible for reading the HTML with the proper encoding (according to Content-Type from HTTP header and/or META tag).

Parameters:

htmlFragment - is the HTML fragment to parse.

buffer - is the buffer where the plain text will be appended to.

parserState - is the state to continue on a subsequent call for multiple htmlFragments of the same HTML-document or null for a fresh start.

Returns:

the state at the end of htmlFragment. You can pass this as parserState argument on subsequent call to continue parsing.