URIConverter


1   /**
2    * <copyright>
3    *
4    * Copyright (c) 2002-2004 IBM Corporation and others.
5    * All rights reserved.   This program and the accompanying materials
6    * are made available under the terms of the Eclipse Public License v1.0
7    * which accompanies this distribution, and is available at
8    * http://www.eclipse.org/legal/epl-v10.html
9    *
10   * Contributors:
11   *   IBM - Initial API and implementation
12   *
13   * </copyright>
14   *
15   * $Id: URIConverter.java,v 1.3 2005/06/08 06:20:10 nickb Exp $
16   */
17  package org.eclipse.emf.ecore.resource;
18  
19  
20  import java.io.IOException  ;
21  import java.io.InputStream  ;
22  import java.io.OutputStream  ;
23  import java.util.Map  ;
24  
25  import org.eclipse.emf.common.util.URI;
26  
27  
28  /**
29   * A converter to normalize a URI or to produce an input or output stream for a URI.
30   * <p>
31   * A resource set provides {@link ResourceSet#getURIConverter one} of these
32   * for use by it's {@link ResourceSet#getResources resources}
33   * when they are {@link Resource#save(java.util.Map) serialized} and {@link Resource#load(java.util.Map) deserialized}.
34   * A resource set also uses this directly when it {@link ResourceSet#getResource looks up} a resource:
35   * a resource is considered a match if {@link Resource#getURI it's URI}, 
36   * and the URI being looked up, 
37   * {@link #normalize normalize} to {@link URI#equals(Object) equal} URIs.
38   * </p>
39   */
40  public interface URIConverter
41  {
42    /**
43     * Returns the normalized form of the URI.
44     * <p>
45     * This may, in theory, do absolutly anything.
46     * Default behaviour includes 
47     * applying URI {@link URIConverter#getURIMap mapping},
48     * assuming <code>"file:"</code> protocol 
49     * for a {@link URI#isRelative relative} URI with a {@link URI#hasRelativePath relative path}:
50     *<pre>
51     *  ./WhateverDirectory/Whatever.file 
52     *    -> 
53     *  file:./WhateverDirectory/Whatever.file
54     *</pre>
55     * and assuming <code>"platform:/resource"</code> protocol 
56     * for a relative URI with an {@link URI#hasAbsolutePath absolute path}:
57     *<pre>
58     *  /WhateverRelocatableProject/Whatever.file 
59     *    -> 
60     *  platform:/resource/WhateverRelocatableProject/Whatever.file
61     *</pre>
62     * </p>
63     * <p>
64     * It is important to emphasize that normalization can result it loss of information.
65     * The normalized URI should generally be used only for comparison and for access to input or output streams.
66     * </p>
67     * @param uri the URI to normalize.
68     * @return the normalized form.
69     * @see org.eclipse.emf.ecore.plugin.EcorePlugin#getPlatformResourceMap
70     */
71    URI normalize(URI uri);
72  
73    /**
74     * Returns the map used for remapping a logical URI to a physical URI when {@link #normalize normalizing}.
75     * <p>
76     * An implementation will typically also delegate to the {@link URIConverter#URI_MAP global} map,
77     * so registrations made in this map are <em>local</em> to this URI converter,
78     * i.e., they augment or override those of the global map.
79     * </p>
80     * <p>
81     * The map generally specifies instance to instance mapping,
82     * except for the case that both the key URI and the value URI end with "/", 
83     * which specifies a folder to folder mapping.
84     * A folder mapping will remap any URI that has the key as its {@link URI#replacePrefix prefix}, 
85     * e.g., if the map contains:
86     *<pre>
87     *  http://www.example.com/ -> platform:/resource/example/
88     *</pre>
89     * then the URI
90     *<pre>
91     *  http://www.example.com/a/b/c.d
92     *</pre>
93     * will map to 
94     *<pre>
95     *  platform:/resource/example/a/b/c.d
96     *</pre>
97     * A matching instance mapping is considered first.
98     * If there isn't one, the folder mappings are considered starting with the {@link URI#segmentCount() longest} prefix. 
99     * </p>
100    * @see #normalize(URI)
101    * @see #URI_MAP
102    * @return the map used for remapping a logical URI to a physical URI.
103    */
104   Map   getURIMap();
105 
106   /**
107    * The global static URI map.
108    * Registrations made in this instance will (typically) be available
109    * for {@link URIConverter#normalize use} by any URI converter.
110    * It is populated by URI mappings registered via
111    * {@link org.eclipse.emf.ecore.plugin.EcorePlugin.Implementation#startup plugin registration}.
112    * @see #normalize(URI)
113    */
114   Map   URI_MAP = org.eclipse.emf.ecore.resource.impl.URIMappingRegistryImpl.INSTANCE.map();
115 
116   /**
117    * Creates an input stream for the URI and returns it.
118    * <p>
119    * It {@link #normalize normalizes} the URI and uses that as the basis for further processing.
120    * Special requirements, such as an Eclipse file refresh, 
121    * are handled by the {@link org.eclipse.emf.ecore.resource.impl.URIConverterImpl default implementation}.
122    * </p>
123    * @return an open input stream.
124    * @exception IOException if there is a problem obtaining an open input stream.
125    */
126   InputStream   createInputStream(URI uri) throws IOException  ;
127 
128   /**
129    * Creates an output stream for the URI and returns it.
130    * <p>
131    * It {@link #normalize normalizes} the URI and uses that as the basis for further processing.
132    * Special requirements, such as an Eclipse file refresh and automatic subdirectory creation, 
133    * are handled by the {@link org.eclipse.emf.ecore.resource.impl.URIConverterImpl default implementation}.
134    * </p>
135    * @return an open output stream.
136    * @exception IOException if there is a problem obtaining an open output stream.
137    */
138   OutputStream   createOutputStream(URI uri) throws IOException  ;
139 }
140
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags