org.eclipse.emf.ecore.resource
Interface URIConverter

All Known Implementing Classes:
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.


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).
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).
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 Map URI_MAP
          The global static URI map.
 
Method Summary
 InputStream createInputStream(URI uri)
          Creates an input stream for the URI and returns it.
 OutputStream createOutputStream(URI uri)
          Creates an output stream for the URI and returns it.
 Map 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.
 

Field Detail

URI_MAP

public static final Map 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)
Method Detail

normalize

public URI normalize(URI uri)
Returns the normalized form of the URI.

This may, in theory, do absolutly 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

public Map 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

createInputStream

public InputStream createInputStream(URI uri)
                              throws 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.

Returns:
an open input stream.
Throws:
IOException - if there is a problem obtaining an open input stream.

createOutputStream

public OutputStream createOutputStream(URI uri)
                                throws 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 and automatic subdirectory creation, are handled by the default implementation.

Returns:
an open output stream.
Throws:
IOException - if there is a problem obtaining an open output stream.

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