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

Copyright 2001-2006 IBM Corporation and others. All Rights Reserved.