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

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