org.eclipse.emf.ecore.resource
Interface ContentHandler

All Known Implementing Classes:

ContentHandlerImpl, PlatformContentHandlerImpl, RootXMLContentHandlerImpl, XMLContentHandlerImpl, XMLContentHandlerImpl.XMI

public interface ContentHandler

A handler for describing the contents of URIs.

A content handler is used primarily by a URI converter which provides support for describing the contents of a URI by virtue of having a list of content handlers that it consults to determine whether the handler can handle the given URI and if so that it uses as a delegate for computing the content description.

Since:

2.4

See Also:

URIHandler, URIConverter

Nested Class Summary

static class	ContentHandler.ByteOrderMark A value specifying the byte order mark of a content description.
static interface	ContentHandler.Registry A registry of content handlers based on a priority order; lower values indicate have higher priority.
static class	ContentHandler.Validity A value specifying the validity of a content description.

Field Summary

static java.lang.String	BYTE_ORDER_MARK_PROPERTY A content description property describing the byte order mark at the beginning of the contents.
static java.lang.String	CHARSET_PROPERTY A content description property describing the character set encoding used by the bytes of the content.
static java.lang.String	CONTENT_TYPE_PROPERTY A content description property describing the content's type identity.
static java.util.Map<java.lang.String,java.lang.Object>	INVALID_CONTENT_DESCRIPTION An unmodifiable content description indicating that the content is invalid.
static java.lang.String	OPTION_REQUESTED_PROPERTIES An option used to specify the Set of properties being requested when computing a content description.
static java.lang.String	UNSPECIFIED_CONTENT_TYPE A constant used to indicate that a content type needs to be computed.
static java.lang.String	VALIDITY_PROPERTY A content description property indicating the validity of the content.

Method Summary

boolean	canHandle(URI uri) Returns whether this handler can describe the contents for the given URI.
java.util.Map<java.lang.String,?>	contentDescription(URI uri, java.io.InputStream inputStream, java.util.Map<?,?> options, java.util.Map<java.lang.Object,java.lang.Object> context) Returns a map of properties that describe the content of the given URI's corresponding input stream.

Field Detail

OPTION_REQUESTED_PROPERTIES

static final java.lang.String OPTION_REQUESTED_PROPERTIES

An option used to specify the Set of properties being requested when computing a content description.

See Also:

VALIDITY_PROPERTY, CONTENT_TYPE_PROPERTY, BYTE_ORDER_MARK_PROPERTY, CHARSET_PROPERTY, Constant Field Values

VALIDITY_PROPERTY

static final java.lang.String VALIDITY_PROPERTY

A content description property indicating the validity of the content. The value will be one of ContentHandler.Validity.INVALID, ContentHandler.Validity.INDETERMINATE, or ContentHandler.Validity.VALID. This property will always be present in a content description.

See Also:

ContentHandler.Validity, IContentDescriber.INVALID, IContentDescriber.INDETERMINATE, IContentDescriber.VALID, Constant Field Values

CONTENT_TYPE_PROPERTY

static final java.lang.String CONTENT_TYPE_PROPERTY

A content description property describing the content's type identity. The value will be an arbitrary string. The content type is often used to determine an appropriate resource factory for processing the contents of a URI.

See Also:

IContentType.getId(), Resource.Factory.Registry.getContentTypeToFactoryMap(), Resource.Factory.Registry.getFactory(URI, String), Constant Field Values

UNSPECIFIED_CONTENT_TYPE

static final java.lang.String UNSPECIFIED_CONTENT_TYPE

A constant used to indicate that a content type needs to be computed.

See Also:

ResourceSet.createResource(URI, String), Resource.Factory.Registry.getFactory(URI, String), Constant Field Values

CHARSET_PROPERTY

static final java.lang.String CHARSET_PROPERTY

A content description property describing the character set encoding used by the bytes of the content. The value will be a string denoting a character set.

See Also:

IContentDescription.CHARSET, Constant Field Values

BYTE_ORDER_MARK_PROPERTY

static final java.lang.String BYTE_ORDER_MARK_PROPERTY

A content description property describing the byte order mark at the beginning of the contents. The value will be of type ContentHandler.ByteOrderMark.

See Also:

IContentDescription.BYTE_ORDER_MARK, Constant Field Values

INVALID_CONTENT_DESCRIPTION

static final java.util.Map<java.lang.String,java.lang.Object> INVALID_CONTENT_DESCRIPTION

An unmodifiable content description indicating that the content is invalid.

Method Detail

canHandle

boolean canHandle(URI uri)

Returns whether this handler can describe the contents for the given URI.

Parameters:

uri - the URI to consider.

Returns:

whether this handler can describe the contents for the given URI.

contentDescription

java.util.Map<java.lang.String,?> contentDescription(URI uri,
                                                     java.io.InputStream inputStream,
                                                     java.util.Map<?,?> options,
                                                     java.util.Map<java.lang.Object,java.lang.Object> context)
                                                     throws java.io.IOException

Returns a map of properties that describe the content of the given URI's corresponding input stream. The validity property will always be present to indicate the status. The content type property too will always be present, except when the validity property is ContentHandler.Validity.INVALID. The option OPTION_REQUESTED_PROPERTIES can be used to specify the set of additional properties that should appear in the result. If this option is not present, all properties this handler can compute will be returned. The context map is used to cache results that can be shared between content handler implementations. For example, once a content handler has computed the byte order mark property, the result can be cached so that it is not recomputed repeatedly. Similarly, content handlers for XML content might cache the character set property, and might even share a parsed XML representation so that each handle can analyze to determine whether that XML is of the expected form for the content type.

Parameters:

uri - the URI for which to determine the content description.

inputStream - the input stream associated with the given URI.

options - a map of options to direct what kind of description is needed.

context - a map of contextual information that content handlers use to store partially computed results.

Returns:

a map of properties that describe the content of the given URI's corresponding input stream.

Throws:

java.io.IOException - if there is a problem reading the stream.