## org.eclipse.emf.ecore.resource
Interface URIConverter

All Known Implementing Classes:
  ExtensibleURIConverterImpl, URIConverterImpl

    public interface URIConverter

A converter to normalize a URI or to produce an input or output stream for a URI.

A resource set provides `one` of these for use by it's `resources` when they are `serialized` and `deserialized`. A resource set also uses this directly when it `looks up` a resource: a resource is considered a match if `it's URI`, and the URI being looked up, `normalize` to `equal` URIs. Clients must extend the default `implementation`, since methods can and will be added to this API.

See Also:
  `ResourceSet.getURIConverter()`, `URIHandler`, `ContentHandler`

Nested Class Summary
`static interface` `URIConverter.Cipher` An interface to be implemented by encryption service providers.
`static interface` `URIConverter.Readable` An interface that is optionally implemented by the input streams returned from `createInputStream(URI)` and `createInputStream(URI, Map)`.
`static class` `URIConverter.ReadableInputStream` A wrapper around a reader that implements an input stream but can be unwrapped to access the reader directly.
`static interface` `URIConverter.Writeable` An interface that is optionally implemented by the output streams returned from `createOutputStream(URI)` and `createOutputStream(URI, Map)`.
`static class` `URIConverter.WriteableOutputStream` A wrapper around a writer that implements an output stream but can be unwrapped to access the writer directly.

Field Summary
`static java.lang.String` `ATTRIBUTE_ARCHIVE` The archive `attribute` representing whether the contents of a URI are archived.
`static java.lang.String` `ATTRIBUTE_DIRECTORY` The directory `attribute` representing whether the URI represents a directory rather than a file.
`static java.lang.String` `ATTRIBUTE_EXECUTABLE` The execute `attribute` representing whether the contents of a URI can be executed.
`static java.lang.String` `ATTRIBUTE_HIDDEN` The hidden `attribute` representing whether the URI is visible.
`static java.lang.String` `ATTRIBUTE_LENGTH` The length `attribute` representing the number of bytes in the contents of a URI.
`static java.lang.String` `ATTRIBUTE_READ_ONLY` The read only `attribute` representing whether the contents of a URI can be modified.
`static java.lang.String` `ATTRIBUTE_TIME_STAMP` The time stamp `attribute` representing the last time the contents of a URI were modified.
`static URIConverter` `INSTANCE` The global static URI converter instance.
`static long` `NULL_TIME_STAMP` A `ATTRIBUTE_TIME_STAMP` value that indicates no time stamp is available.
`static java.lang.String` `OPTION_REQUESTED_ATTRIBUTES` An option passed to a `Set<String>` to `getAttributes(URI, Map)` to indicate the specific attributes to be fetched.
`static java.lang.String` `OPTION_RESPONSE` An option to pass a `Map<Object, Object>` to any of the URI converter's methods in order to yield results in addition to the returned value of the method.
`static java.lang.String` `OPTION_URI_CONVERTER` An option used to pass the calling URIConverter to the `URIHandler`s.
`static java.lang.String` `RESPONSE_TIME_STAMP_PROPERTY` A property of the `response option` used to yield the `time stamp` associated with the creation of an `input` or an `output` stream.
`static java.util.Map<URI,URI>` `URI_MAP` The global static URI map.

Method Summary
`java.util.Map<java.lang.String,?>` `contentDescription(URI uri, java.util.Map<?,?> options)` Returns a map from String properties to their corresponding values representing a description the given URI's contents.
`java.io.InputStream` `createInputStream(URI uri)` Creates an input stream for the URI and returns it; it has the same effect as calling `createInputStream(uri, null)`.
`java.io.InputStream` `createInputStream(URI uri, java.util.Map<?,?> options)` Creates an input stream for the URI and returns it.
`java.io.OutputStream` `createOutputStream(URI uri)` Creates an output stream for the URI and returns it; it has the same effect as calling `createOutputStream(uri, null)`.
`java.io.OutputStream` `createOutputStream(URI uri, java.util.Map<?,?> options)` Creates an output stream for the URI and returns it.
`void` `delete(URI uri, java.util.Map<?,?> options)` Deletes the contents of the given URI.
`boolean` `exists(URI uri, java.util.Map<?,?> options)` Returns whether the given URI has contents.
`java.util.Map<java.lang.String,?>` `getAttributes(URI uri, java.util.Map<?,?> options)` Returns a map from String attributes to their corresponding values representing information about various aspects of the URI's state.
`EList<ContentHandler>` `getContentHandlers()` Returns the list of `ContentHandler`s.
`URIHandler` `getURIHandler(URI uri)` Returns the first URI handler in the `list` of URI handlers which `can handle` the given URI.
`EList<URIHandler>` `getURIHandlers()` Returns the list of `URIHandler`s.
`java.util.Map<URI,URI>` `getURIMap()` Returns the map used for remapping a logical URI to a physical URI when `normalizing`.
`URI` `normalize(URI uri)` Returns the normalized form of the URI.
`void` `setAttributes(URI uri, java.util.Map<java.lang.String,?> attributes, java.util.Map<?,?> options)` Updates the map from String attributes to their corresponding values representing information about various aspects of the URI's state.

Field Detail

### OPTION_URI_CONVERTER

    static final java.lang.String OPTION_URI_CONVERTER

  An option used to pass the calling URIConverter to the `URIHandler`s.

  Since:
    2.4
  See Also:
    Constant Field Values

### OPTION_RESPONSE

    static final java.lang.String OPTION_RESPONSE

  An option to pass a `Map<Object, Object>` to any of the URI converter's methods in order to yield results in addition to the returned value of the method.

  Since:
    2.4
  See Also:
    Constant Field Values

### RESPONSE_TIME_STAMP_PROPERTY

    static final java.lang.String RESPONSE_TIME_STAMP_PROPERTY

  A property of the `response option` used to yield the `time stamp` associated with the creation of an `input` or an `output` stream. This is typically used by resource `load` and `save` in order to set the `Resource.getTimeStamp()`.

  Since:
    2.4
  See Also:
    Constant Field Values

### URI_MAP

    static final java.util.Map<URI,URI> URI_MAP

  The global static URI map. Registrations made in this instance will (typically) be available for `use` by any URI converter. It is populated by URI mappings registered via `plugin registration`.

  See Also:
    `normalize(URI)`

### ATTRIBUTE_TIME_STAMP

    static final java.lang.String ATTRIBUTE_TIME_STAMP

  The time stamp `attribute` representing the last time the contents of a URI were modified. The value is represented as Long that encodes the number of milliseconds since the epoch 00:00:00 GMT, January 1, 1970.

  Since:
    2.4
  See Also:
    Constant Field Values

### NULL_TIME_STAMP

    static final long NULL_TIME_STAMP

  A `ATTRIBUTE_TIME_STAMP` value that indicates no time stamp is available.

  Since:
    2.4
  See Also:
    Constant Field Values

### ATTRIBUTE_LENGTH

    static final java.lang.String ATTRIBUTE_LENGTH

  The length `attribute` representing the number of bytes in the contents of a URI. It is represented as a Long value.

  Since:
    2.4
  See Also:
    Constant Field Values

### ATTRIBUTE_READ_ONLY

    static final java.lang.String ATTRIBUTE_READ_ONLY

  The read only `attribute` representing whether the contents of a URI can be modified. It is represented as a Boolean value. If the URI's contents `exist` and it is read only, it will not be possible to `create` an output stream.

  Since:
    2.4
  See Also:
    Constant Field Values

### ATTRIBUTE_EXECUTABLE

    static final java.lang.String ATTRIBUTE_EXECUTABLE

  The execute `attribute` representing whether the contents of a URI can be executed. It is represented as a Boolean value.

  Since:
    2.4
  See Also:
    Constant Field Values

### ATTRIBUTE_ARCHIVE

    static final java.lang.String ATTRIBUTE_ARCHIVE

  The archive `attribute` representing whether the contents of a URI are archived. It is represented as a Boolean value.

  Since:
    2.4
  See Also:
    Constant Field Values

### ATTRIBUTE_HIDDEN

    static final java.lang.String ATTRIBUTE_HIDDEN

  The hidden `attribute` representing whether the URI is visible. It is represented as a Boolean value.

  Since:
    2.4
  See Also:
    Constant Field Values

### ATTRIBUTE_DIRECTORY

    static final java.lang.String ATTRIBUTE_DIRECTORY

  The directory `attribute` representing whether the URI represents a directory rather than a file. It is represented as a Boolean value.

  Since:
    2.4
  See Also:
    Constant Field Values

### OPTION_REQUESTED_ATTRIBUTES

    static final java.lang.String OPTION_REQUESTED_ATTRIBUTES

  An option passed to a `Set<String>` to `getAttributes(URI, Map)` to indicate the specific attributes to be fetched.

  See Also:
    Constant Field Values

### INSTANCE

    static final URIConverter INSTANCE

  The global static URI converter instance. It's generally not a good idea to modify any aspect of this instance. Instead, use a resource set's `local` instance.

  Since:
    2.4

Method Detail

### normalize

    URI normalize(URI uri)

  Returns the normalized form of the URI.

  This may, in theory, do absolutely anything. Default behaviour includes applying URI `mapping`, assuming `"file:"` protocol for a `relative` URI with a `relative path`:

        ./WhateverDirectory/Whatever.file
          ->
        file:./WhateverDirectory/Whatever.file

  and assuming `"platform:/resource"` protocol for a relative URI with an `absolute path`:

        /WhateverRelocatableProject/Whatever.file
          ->
        platform:/resource/WhateverRelocatableProject/Whatever.file

  It is important to emphasize that normalization can result it loss of information. The normalized URI should generally be used only for comparison and for access to input or output streams.

  Parameters:
    `uri` - the URI to normalize.
  Returns:
    the normalized form.
  See Also:
    `EcorePlugin.getPlatformResourceMap()`

### getURIMap

    java.util.Map<URI,URI> getURIMap()

  Returns the map used for remapping a logical URI to a physical URI when `normalizing`.

  An implementation will typically also delegate to the `global` map, so registrations made in this map are local to this URI converter, i.e., they augment or override those of the global map.

  The map generally specifies instance to instance mapping, except for the case that both the key URI and the value URI end with "/", which specifies a folder to folder mapping. A folder mapping will remap any URI that has the key as its `prefix`, e.g., if the map contains:

        http://www.example.com/ -> platform:/resource/example/

  then the URI

        http://www.example.com/a/b/c.d

  will map to

        platform:/resource/example/a/b/c.d

  A matching instance mapping is considered first. If there isn't one, the folder mappings are considered starting with the `longest` prefix.

  Returns:
    the map used for remapping a logical URI to a physical URI.
  See Also:
    `normalize(URI)`, `URI_MAP`

### getURIHandlers

    EList<URIHandler> getURIHandlers()

  Returns the list of `URIHandler`s.

  Returns:
    the list of `URIHandler`s.
  Since:
    2.4

### getURIHandler

    URIHandler getURIHandler(URI uri)

  Returns the first URI handler in the `list` of URI handlers which `can handle` the given URI.

  Parameters:
    `uri` - the URI for which to find a handler.
  Returns:
    the first URI handler in the list of URI handlers which can handle the given URI.
  Throws:
    `java.lang.RuntimeException` - if no matching handler is found.
  Since:
    2.4

### getContentHandlers

    EList<ContentHandler> getContentHandlers()

  Returns the list of `ContentHandler`s.

  Returns:
    the list of `ContentHandler`s.
  Since:
    2.4

### createInputStream

    java.io.InputStream createInputStream(URI uri)
                                          throws java.io.IOException

  Creates an input stream for the URI and returns it; it has the same effect as calling `createInputStream(uri, null)`.

  Parameters:
    `uri` - the URI for which to create the input stream.
  Returns:
    an open input stream.
  Throws:
    `java.io.IOException` - if there is a problem obtaining an open input stream.
  See Also:
    `createInputStream(URI, Map)`

### createInputStream

    java.io.InputStream createInputStream(URI uri,
                                          java.util.Map<?,?> options)
                                          throws java.io.IOException

  Creates an input stream for the URI and returns it.

  It `normalizes` the URI and uses that as the basis for further processing. Special requirements, such as an Eclipse file refresh, are handled by the `default implementation`.

  Parameters:
    `uri` - the URI for which to create the input stream.
    `options` - a map of options to influence the kind of stream that is returned; unrecognized options are ignored and `null` is permitted.
  Returns:
    an open input stream.
  Throws:
    `java.io.IOException` - if there is a problem obtaining an open input stream.
  Since:
    2.4

### createOutputStream

    java.io.OutputStream createOutputStream(URI uri)
                                            throws java.io.IOException

  Creates an output stream for the URI and returns it; it has the same effect as calling `createOutputStream(uri, null)`.

  Returns:
    an open output stream.
  Throws:
    `java.io.IOException` - if there is a problem obtaining an open output stream.
  See Also:
    `createOutputStream(URI, Map)`

### createOutputStream

    java.io.OutputStream createOutputStream(URI uri,
                                            java.util.Map<?,?> options)
                                            throws java.io.IOException

  Creates an output stream for the URI and returns it.

  It `normalizes` the URI and uses that as the basis for further processing. Special requirements, such as an Eclipse file refresh, are handled by the `default implementation`.

  Parameters:
    `uri` - the URI for which to create the output stream.
    `options` - a map of options to influence the kind of stream that is returned; unrecognized options are ignored and `null` is permitted.
  Returns:
    an open output stream.
  Throws:
    `java.io.IOException` - if there is a problem obtaining an open output stream.
  Since:
    2.4

### delete

    void delete(URI uri,
                java.util.Map<?,?> options)
                throws java.io.IOException

  Deletes the contents of the given URI.

  Parameters:
    `uri` - the URI to consider.
    `options` - options to influence how the contents are deleted, or `null` if there are no options.
  Throws:
    `java.io.IOException` - if there is a problem deleting the contents.
  Since:
    2.4

### contentDescription

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

  Returns a map from String properties to their corresponding values representing a description the given URI's contents. See the `content handler` for more details.

  Parameters:
    `uri` - the URI to consider.
    `options` - options to influence how the content description is determined, or `null` if there are no options.
  Returns:
    a map from String properties to their corresponding values representing a description the given URI's contents.
  Throws:
    `java.io.IOException` - if there is a problem accessing the contents.
  Since:
    2.4
  See Also:
    `ContentHandler.contentDescription(URI, InputStream, Map, Map)`

### exists

    boolean exists(URI uri,
                   java.util.Map<?,?> options)

  Returns whether the given URI has contents. If the URI `exists` it will be possible to `create` an input stream.

  Parameters:
    `uri` - the URI to consider.
    `options` - options to influence how the existence determined, or `null` if there are no options.
  Returns:
    whether the given URI has contents.
  Since:
    2.4

### getAttributes

    java.util.Map<java.lang.String,?> getAttributes(URI uri,
                                                    java.util.Map<?,?> options)

  Returns a map from String attributes to their corresponding values representing information about various aspects of the URI's state. The `requested attributes option` can be used to specify which properties to fetch; without that option, all supported attributes will be fetched. If the URI doesn't not support any particular attribute, an entry for that attribute will not be appear in the result.

  Parameters:
    `uri` - the URI to consider.
    `options` - options to influence how the attributes are determined, or `null` if there are no options.
  Returns:
    a map from String attributes to their corresponding values representing information about various aspects of the URI's state.

### setAttributes

    void setAttributes(URI uri,
                       java.util.Map<java.lang.String,?> attributes,
                       java.util.Map<?,?> options)
                       throws java.io.IOException

  Updates the map from String attributes to their corresponding values representing information about various aspects of the URI's state. Unsupported or unchangeable attributes are ignored.

  Parameters:
    `uri` - the URI to consider.
    `attributes` - the new values for the attributes.
    `options` - options to influence how the attributes are updated, or `null` if there are no options.
  Throws:
    `java.io.IOException` - if there is a problem updating the attributes.

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