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.Loadable
          An interface that is optionally implemented by the input streams returned from createInputStream(URI) and createInputStream(URI, Map).
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.Saveable
          An interface that is optionally implemented by the output streams returned from createOutputStream(URI) and createOutputStream(URI, Map).
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 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 URIHandlers.
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.lang.String RESPONSE_URI
          A property of the response option used to yield the newly allocated URI associated with the creation of 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 ContentHandlers.
 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 URIHandlers.
 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 URIHandlers.

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

RESPONSE_URI

static final java.lang.String RESPONSE_URI
A property of the response option used to yield the newly allocated URI associated with the creation of an output stream. This is typically used by resource save in order to set the resource URI.

Since:
2.7
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 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 in 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 URIHandlers.

Returns:
the list of URIHandlers.
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 ContentHandlers.

Returns:
the list of ContentHandlers.
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.