/**
 * Copyright (c) 2002-2011 IBM Corporation and others.
 * All rights reserved.   This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v2.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v20.html
 *
 * Contributors:
 *   IBM - Initial API and implementation
 */
package org.eclipse.emf.ecore.resource;


import java.io.InputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Map;
import java.util.Set;

import org.eclipse.emf.common.util.Callback;
import org.eclipse.emf.common.util.EList;
import org.eclipse.emf.common.util.URI;
import org.eclipse.emf.ecore.resource.impl.ExtensibleURIConverterImpl;


/**
 * A converter to normalize a URI or to produce an input or output stream for a URI.
 * <p>
 * A resource set provides {@link ResourceSet#getURIConverter one} of these
 * for use by it's {@link ResourceSet#getResources resources}
 * when they are {@link Resource#save(java.util.Map) serialized} and {@link Resource#load(java.util.Map) deserialized}.
 * A resource set also uses this directly when it {@link ResourceSet#getResource looks up} a resource:
 * a resource is considered a match if {@link Resource#getURI it's URI}, 
 * and the URI being looked up, 
 * {@link #normalize normalize} to {@link URI#equals(Object) equal} URIs.
 * Clients must extend the default {@link org.eclipse.emf.ecore.resource.impl.ExtensibleURIConverterImpl implementation},
 * since methods can and will be added to this API.
 * </p>
 * @see ResourceSet#getURIConverter()
 * @see URIHandler
 * @see ContentHandler
 */
public interface URIConverter
{
  /**
   * An option used to pass the calling URIConverter to the {@link URIHandler}s.
   * @since 2.4
   */
  String OPTION_URI_CONVERTER = "URI_CONVERTER";

  /**
   * An option to pass a {@link Map Map&lt;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
   */
  String OPTION_RESPONSE = "RESPONSE";

  /**
   * A property of the {@link #OPTION_RESPONSE response option} 
   * used to yield the result for the asynchronous methods.
   * @since 2.7
   */
  String RESPONSE_RESULT = "RESULT";

  /**
   * A property of the {@link #OPTION_RESPONSE response option} 
   * used to yield the {@link #ATTRIBUTE_TIME_STAMP time stamp} associated
   * with the creation of an {@link #createInputStream(URI, Map) input} or an {@link #createOutputStream(URI, Map) output} stream.
   * This is typically used by resource {@link Resource#load(Map) load} and {@link Resource#save(Map) save} 
   * in order to set the {@link Resource#getTimeStamp()}.
   * @since 2.4
   */
  String RESPONSE_TIME_STAMP_PROPERTY = "TIME_STAMP";

  /**
   * A property of the {@link #OPTION_RESPONSE response option} 
   * used to yield the newly allocated URI associated
   * with the creation of an {@link #createOutputStream(URI, Map) output} stream.
   * This is typically used by resource {@link Resource#save(Map) save} 
   * in order to {@link Resource#setURI(URI) set the resource URI}.
   * @since 2.7
   */
  String RESPONSE_URI = "URI";

  /**
   * A {@link #createOutputStream(URI, Map) createOutputStream},
   * {@link #store(URI, byte[], Map, Callback) store},
   * or {@link #delete(URI, Map, Callback) delete} option 
   * that specifies a long {@link #RESPONSE_TIME_STAMP_PROPERTY timestamp} which must match the underlying resource's timestamp for the update to succeed.
   * @since 2.7
   */
  String OPTION_UPDATE_ONLY_IF_TIME_STAMP_MATCHES = "UPDATE_ONLY_IF_TIME_STAMP_MATCHES";

  /**
   * Returns the normalized form of the URI.
   * <p>
   * This may, in theory, do absolutely anything.
   * Default behaviour includes 
   * applying URI {@link URIConverter#getURIMap mapping},
   * assuming <code>"file:"</code> protocol 
   * for a {@link URI#isRelative relative} URI with a {@link URI#hasRelativePath relative path}:
   *<pre>
   *  ./WhateverDirectory/Whatever.file 
   *    -> 
   *  file:./WhateverDirectory/Whatever.file
   *</pre>
   * and assuming <code>"platform:/resource"</code> protocol 
   * for a relative URI with an {@link URI#hasAbsolutePath absolute path}:
   *<pre>
   *  /WhateverRelocatableProject/Whatever.file 
   *    -> 
   *  platform:/resource/WhateverRelocatableProject/Whatever.file
   *</pre>
   * </p>
   * <p>
   * 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.
   * </p>
   * @param uri the URI to normalize.
   * @return the normalized form.
   * @see org.eclipse.emf.ecore.plugin.EcorePlugin#getPlatformResourceMap
   */
  URI normalize(URI uri);

  /**
   * Returns the map used for remapping a logical URI to a physical URI when {@link #normalize normalizing}.
   * <p>
   * An implementation will typically also delegate to the {@link URIConverter#URI_MAP global} map,
   * so registrations made in this map are <em>local</em> to this URI converter,
   * i.e., they augment or override those of the global map.
   * </p>
   * <p>
   * 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 {@link URI#replacePrefix prefix}, 
   * e.g., if the map contains:
   *<pre>
   *  http://www.example.com/ -> platform:/resource/example/
   *</pre>
   * then the URI
   *<pre>
   *  http://www.example.com/a/b/c.d
   *</pre>
   * will map to 
   *<pre>
   *  platform:/resource/example/a/b/c.d
   *</pre>
   * A matching instance mapping is considered first.
   * If there isn't one, the folder mappings are considered starting with the {@link URI#segmentCount() longest} prefix. 
   * </p>
   * @see #normalize(URI)
   * @see #URI_MAP
   * @return the map used for remapping a logical URI to a physical URI.
   */
  Map<URI, URI> getURIMap();

  /**
   * The global static URI map.
   * Registrations made in this instance will (typically) be available
   * for {@link URIConverter#normalize use} by any URI converter.
   * @see #normalize(URI)
   */
  Map<URI, URI> URI_MAP = org.eclipse.emf.ecore.resource.impl.URIMappingRegistryImpl.INSTANCE.map();

  /**
   * Returns the list of {@link URIHandler}s.
   * @return the list of {@link URIHandler}s.
   * @since 2.4
   */
  EList<URIHandler> getURIHandlers();

  /**
   * Returns the first URI handler in the {@link #getURIHandler(URI) list} of URI handlers which {@link URIHandler#canHandle(URI) can handle} the given URI.
   * @param uri the URI for which to find a handler.
   * @return the first URI handler in the list of URI handlers which can handle the given URI.
   * @throws RuntimeException if no matching handler is found.
   * @since 2.4 
   */
  URIHandler getURIHandler(URI uri);

  /**
   * Returns the list of {@link ContentHandler}s.
   * @return the list of {@link ContentHandler}s.
   * @since 2.4
   */
  EList<ContentHandler> getContentHandlers();

  /**
   * Creates an input stream for the URI and returns it;
   * it has the same effect as calling {@link #createInputStream(URI, Map) createInputStream(uri, null)}.
   * @param uri the URI for which to create the input stream.
   * @return an open input stream.
   * @exception IOException if there is a problem obtaining an open input stream.
   * @see #createInputStream(URI, Map)
   */
  InputStream createInputStream(URI uri) throws IOException;

  /**
   * Creates an input stream for the URI and returns it.
   * <p>
   * It {@link #normalize normalizes} the URI and uses that as the basis for further processing.
   * Special requirements, such as an Eclipse file refresh, 
   * are handled by the {@link org.eclipse.emf.ecore.resource.impl.ExtensibleURIConverterImpl default implementation}.
   * </p>
   * @param uri the URI for which to create the input stream.
   * @param options a map of options to influence the kind of stream that is returned; unrecognized options are ignored and <code>null</code> is permitted.
   * @return an open input stream.
   * @exception IOException if there is a problem obtaining an open input stream.
   * @since 2.4
   */
  InputStream createInputStream(URI uri, Map<?, ?> options) throws IOException;

  /**
   * TODO
   * @param uri
   * @param options
   * @param callback
   */
  void createInputStream(URI uri, Map<?, ?> options, Callback<Map<?, ?>> callback);

  /**
   * An interface that is optionally implemented by the input streams returned from 
   * {@link URIConverter#createInputStream(URI)} and {@link URIConverter#createInputStream(URI, Map)}.
   * An input stream implementing this interface is highly unlikely to support {@link InputStream#read() read}.
   * Instead {@link #loadResource(Resource) loadResource} should be called.
   * @since 2.7
   */
  interface Loadable
  {
    /**
     * Load the contents of the resource directly from the backing store for which the stream implementing this interface is a facade.
     * @param resource the resource to load.
     * @throws IOException if there are any problems load the resource from the backing store.
     */
    void loadResource(Resource resource) throws IOException;
  }

  /**
   * Creates an output stream for the URI and returns it;
   * it has the same effect as calling {@link #createOutputStream(URI, Map) createOutputStream(uri, null)}.
   * @return an open output stream.
   * @exception IOException if there is a problem obtaining an open output stream.
   * @see #createOutputStream(URI, Map)
   */
  OutputStream createOutputStream(URI uri) throws IOException;
  
  /**
   * Creates an output stream for the URI and returns it.
   * <p>
   * It {@link #normalize normalizes} the URI and uses that as the basis for further processing.
   * Special requirements, such as an Eclipse file refresh, 
   * are handled by the {@link org.eclipse.emf.ecore.resource.impl.ExtensibleURIConverterImpl default implementation}.
   * </p>
   * @param uri the URI for which to create the output stream.
   * @param options a map of options to influence the kind of stream that is returned; unrecognized options are ignored and <code>null</code> is permitted.
   * @return an open output stream.
   * @exception IOException if there is a problem obtaining an open output stream.
   * @since 2.4
   */
  OutputStream createOutputStream(URI uri, Map<?, ?> options) throws IOException;

  /**
   * TODO
   * @param uri
   * @param bytes
   * @param options
   * @param callback
   */
  void store(URI uri, byte[] bytes, Map<?, ?> options, Callback<Map<?, ?>> callback);

  /**
   * An interface that is optionally implemented by the output streams returned from 
   * {@link URIConverter#createOutputStream(URI)} and {@link URIConverter#createOutputStream(URI, Map)}.
   * An output stream implementing this interface is highly unlikely to support {@link OutputStream#write(int) write}.
   * Instead {@link #saveResource(Resource) saveResource} should be called.
   * @since 2.7
   */
  interface Saveable
  {
    /**
     * Save the contents of the resource directly to the backing store for which the stream implementing this interface is a facade.
     * @param resource the resource to save.
     * @throws IOException if there are any problems saving the resource to the backing store.
     */
    void saveResource(Resource resource) throws IOException;
  }

  /**
   * An interface to be implemented by encryption service providers.
   * @since 2.2.0
   */
  interface Cipher
  {
    /**
     * Encrypts the specified output stream.
     * @param outputStream
     * @return an encrypted output stream
     */
    OutputStream encrypt(OutputStream outputStream) throws Exception;
  
    /**
     * This method is invoked after the encrypted output stream is used
     * allowing the Cipher implementation to do any maintenance work required,
     * such as flushing an internal cache.
     * @param outputStream the encrypted stream returned by {@link #encrypt(OutputStream)}.
     */
    void finish(OutputStream outputStream) throws Exception;
  
    /**
     * Decrypts the specified input stream.
     * @param inputStream
     * @return a decrypted input stream
     */
    InputStream decrypt(InputStream inputStream) throws Exception;
    
    /**
     * This method is invoked after the decrypted input stream is used
     * allowing the Cipher implementation to do any maintenance work required,
     * such as flushing internal cache.
     * @param inputStream the stream returned by {@link #decrypt(InputStream)}.
     */
    void finish(InputStream inputStream) throws Exception;
  }

  /**
   * Deletes the contents of the given URI. 
   * @param uri the URI to consider.
   * @param options options to influence how the contents are deleted, or <code>null</code> if there are no options.
   * @throws IOException if there is a problem deleting the contents.
   * @since 2.4
   */
  void delete(URI uri, Map<?, ?> options) throws IOException;

  /**
   * TODO
   * @param uri
   * @param options
   * @param callback
   */
  void delete(URI uri, Map<?, ?> options, Callback<Map<?, ?>> callback);
  
  /**
   * Returns a map from String properties to their corresponding values representing a description the given URI's contents.
   * See the {@link ContentHandler#contentDescription(URI, InputStream, Map, Map) content handler} for more details.
   * @param uri the URI to consider.
   * @param options options to influence how the content description is determined, or <code>null</code> if there are no options.
   * @return a map from String properties to their corresponding values representing a description the given URI's contents.
   * @throws IOException if there is a problem accessing the contents.
   * @see ContentHandler#contentDescription(URI, InputStream, Map, Map)
   * @since 2.4
   */
  Map<String, ?> contentDescription(URI uri, Map<?, ?> options) throws IOException;

  /**
   * Returns whether the given URI has contents.
   * If the URI {@link #exists(URI, Map) exists}
   * it will be possible to {@link #createOutputStream(URI, Map) create} an input stream.
   * @param uri the URI to consider.
   * @param options options to influence how the existence determined, or <code>null</code> if there are no options.
   * @return whether the given URI has contents.
   * @since 2.4
   */
  boolean exists(URI uri, Map<?, ?> options);

  /**
   * TODO
   * @param uri
   * @param options
   * @param callback
   */
  void exists(URI uri, Map<?, ?> options, Callback<Boolean> callback);

  /**
   * The time stamp {@link #getAttributes(URI, Map) 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
   */
  String ATTRIBUTE_TIME_STAMP = "timeStamp";

  /**
   * A {@link #ATTRIBUTE_TIME_STAMP} value that indicates no time stamp is available.
   * @since 2.4
   */
  long NULL_TIME_STAMP = -1;

  /**
   * The length {@link #getAttributes(URI, Map) attribute} representing the number of bytes in the contents of a URI.
   * It is represented as a Long value.
   * @since 2.4
   */
  String ATTRIBUTE_LENGTH = "length";

  /**
   * The read only {@link #getAttributes(URI, Map) attribute} representing whether the contents of a URI can be modified.
   * It is represented as a Boolean value.
   * If the URI's contents {@link #exists(URI, Map) exist} and it is read only, 
   * it will not be possible to {@link #createOutputStream(URI, Map) create} an output stream.
   * @since 2.4
   */
  String ATTRIBUTE_READ_ONLY = "readOnly";

  /**
   * The execute {@link #getAttributes(URI, Map) attribute} representing whether the contents of a URI can be executed.
   * It is represented as a Boolean value.
   * @since 2.4
   */
  String ATTRIBUTE_EXECUTABLE = "executable";

  /**
   * The archive {@link #getAttributes(URI, Map) attribute} representing whether the contents of a URI are archived.
   * It is represented as a Boolean value.
   * @since 2.4
   */
  String ATTRIBUTE_ARCHIVE = "archive";

  /**
   * The hidden {@link #getAttributes(URI, Map) attribute} representing whether the URI is visible.
   * It is represented as a Boolean value.
   * @since 2.4
   */
  String ATTRIBUTE_HIDDEN = "hidden";

  /**
   * The directory {@link #getAttributes(URI, Map) attribute} representing whether the URI represents a directory rather than a file.
   * It is represented as a Boolean value.
   * @since 2.4
   */
  String ATTRIBUTE_DIRECTORY = "directory";

  /**
   * An option passed to a {@link Set Set<String>} to {@link #getAttributes(URI, Map)} to indicate the specific attributes to be fetched.
   */
  String OPTION_REQUESTED_ATTRIBUTES = "requestedAttributes";

  /**
   * Returns a map from String attributes to their corresponding values representing information about various aspects of the URI's state.
   * The {@link #OPTION_REQUESTED_ATTRIBUTES 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.
   * @param uri the URI to consider.
   * @param options options to influence how the attributes are determined, or <code>null</code> if there are no options.
   * @return a map from String attributes to their corresponding values representing information about various aspects of the URI's state.
   */
  Map<String, ?> getAttributes(URI uri, Map<?, ?> options);

  /**
   * 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.
   * @param uri the URI to consider.
   * @param attributes the new values for the attributes.
   * @param options options to influence how the attributes are updated, or <code>null</code> if there are no options.
   * @throws IOException if there is a problem updating the attributes.
   */
  void setAttributes(URI uri, Map<String, ?> attributes, Map<?, ?> options) throws IOException;

  /**
   * 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 {@link ResourceSet#getURIConverter() local} instance.
   * @since 2.4
   */
  URIConverter INSTANCE = new ExtensibleURIConverterImpl();
}
