ResourceSet


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: ResourceSet.java,v 1.2 2005/06/08 06:20:10 nickb Exp $
16   */
17  package org.eclipse.emf.ecore.resource;
18  
19  
20  import java.util.Map  ;
21  
22  import org.eclipse.emf.common.notify.Notifier;
23  import org.eclipse.emf.common.util.EList;
24  import org.eclipse.emf.common.util.TreeIterator;
25  import org.eclipse.emf.common.util.URI;
26  import org.eclipse.emf.ecore.EObject;
27  import org.eclipse.emf.ecore.EPackage;
28  
29  
30  /**
31   * A collection of related persistent documents.
32   * <p>
33   * A resource set manages a collection of related {@link #getResources resources}
34   * and produces notification for changes to that collection.
35   * It provides a {@link #getAllContents tree} of contents.
36   * A collection of {@link #getAdapterFactories adapter factories} 
37   * supports {@link org.eclipse.emf.ecore.util.EcoreUtil#getRegisteredAdapter adapter lookup} via registered adapter factory.
38   * </p>
39   * <p>
40   * A resource can be {@link #createResource created} 
41   * or {@link #getResource(URI, boolean) demand loaded}
42   * into the collection.
43   * The {@link #getResourceFactoryRegistry registry} of resource factories can be configured
44   * to create resources of the appropriate type.
45   * A proxy can be {@link #getEObject resolved} by the resource set, 
46   * and may cause the demand load of a resource.
47   * Default {@link #getLoadOptions load options} are used during demand load.
48   * A {@link #getURIConverter URI converter} can be configured to 
49   * normalize URIs for comparison and to monitor access to the backing store.
50   * </p>
51   * @see Resource
52   * @see Resource.Factory
53   * @see URIConverter
54   * @see org.eclipse.emf.ecore.util.EcoreUtil#getRegisteredAdapter(EObject, Object)
55   */
56  public interface ResourceSet extends Notifier
57  {
58    /**
59     * The {@link #getResources} feature {@link org.eclipse.emf.common.notify.Notification#getFeatureID ID}.
60     */
61    int RESOURCE_SET__RESOURCES = 0;
62  
63    /**
64     * Returns the direct {@link Resource}s being managed.
65     * <p>
66     * A resource added to this list 
67     * will be {@link Resource#getResourceSet contained} by this resource set.
68     * If it was previously contained by a resource set, it will have been removed.
69     * </p>
70     * @return the resources.
71     * @see Resource#getResourceSet
72     */
73    EList getResources();
74  
75    /**
76     * Returns a tree iterator that iterates over all the {@link #getResources direct resources} 
77     * and over the content {@link Resource#getAllContents tree} of each. 
78     * @return a tree iterator that iterates over all contents.
79     * @see EObject#eAllContents
80     * @see Resource#getAllContents
81     * @see org.eclipse.emf.ecore.util.EcoreUtil#getAllContents
82     */
83    TreeIterator getAllContents();
84  
85    /**
86     * Returns the list of registered {@link org.eclipse.emf.common.notify.AdapterFactory} instances.
87     * <p>
88     * One style of adapter {@link org.eclipse.emf.ecore.util.EcoreUtil#getRegisteredAdapter lookup} supported by EMF 
89     * is via registered adapter factories.
90     * Since these factories are accessible to any fully contained object via
91     *<pre>
92     *  eObject.eResource().getResourceSet().getAdapterFactories()
93     *</pre>
94     * they can be used to create adapters on demand, 
95     * without going to the factory first.
96     * </p>
97     * @return the list of adapter factories.
98     * @see org.eclipse.emf.ecore.util.EcoreUtil#getRegisteredAdapter(EObject, Object)
99     * @see org.eclipse.emf.common.notify.AdapterFactory#adapt(Notifier, Object)
100    */
101   EList getAdapterFactories();
102 
103   /**
104    * Returns the options used during demand load.
105    * <p>
106    * Options are handled generically as feature-to-setting entries.
107    * They are passed to the resource when it is {@link Resource#load(Map) deserialized}.
108    * A resource will ignore options it doesn't recognize.
109    * The options could even include things like an Eclipse progress monitor...
110    * </p>
111    * @return the options used during demand load.
112    * @see Resource#load(Map)
113    */
114   Map   getLoadOptions();
115 
116   /**
117    * Returns the object resolved by the URI.
118    * <p>
119    * Every object {@link EObject#eResource contained} by a resource (or that is a {@link EObject#eIsProxy proxy})
120    * has a {@link org.eclipse.emf.ecore.util.EcoreUtil#getURI corresponding URI} 
121    * that resolves to the object.
122    * So for any object contained by a resource, the following is <code>true</code>.
123    *<pre>
124    *   eObject == eObject.eResource().getResourceSet().getEObject(EcoreUtil.getURI(eObject), false)
125    *</pre>
126    * </p>
127    * <p>
128    * The URI {@link URI#trimFragment without} the fragment,
129    * is used to {@link #getResource resolve} a resource.
130    * If the resource resolves,
131    * the {@link URI#fragment fragment} is used to {@link Resource#getEObject resolve} the object.
132    * </p>
133    * @param uri the URI to resolve.
134    * @param loadOnDemand whether to create and load the resource, if it doesn't already exists.
135    * @return the object resolved by the URI.
136    * @see Resource#getEObject(String)
137    * @see #getResource(URI, boolean)
138    * @see org.eclipse.emf.ecore.util.EcoreUtil#getURI(EObject)
139    * @throws RuntimeException if a resource can't be demand created.
140    * @throws org.eclipse.emf.common.util.WrappedException if a problem occurs during demand load.
141    */
142   EObject getEObject(URI uri, boolean loadOnDemand);
143 
144   /**
145    * Returns the resource resolved by the URI.
146    * <p>
147    * A resource set is expected to implement the following strategy 
148    * in order to resolve the given URI to a resource.
149    * First it uses it's {@link #getURIConverter URI converter} to {@link URIConverter#normalize normalize} the URI 
150    * and then to compare it with the normalized URI of each resource;
151    * if it finds a match, 
152    * that resource becomes the result.
153    * Failing that,
154    * it {@link org.eclipse.emf.ecore.resource.impl.ResourceSetImpl#delegatedGetResource delegates} 
155    * to allow the URI to be resolved elsewhere.
156    * For example, 
157    * the {@link org.eclipse.emf.ecore.EPackage.Registry#INSTANCE package registry}
158    * is used to {@link org.eclipse.emf.ecore.EPackage.Registry#getEPackage resolve} 
159    * the {@link org.eclipse.emf.ecore.EPackage namespace URI} of a package
160    * to the static instance of that package.
161    * So the important point is that an arbitrary implementation may resolve the URI to any resource,
162    * not necessarily to one contained by this particular resource set.
163    * If the delegation step fails to provide a result,
164    * and if <code>loadOnDemand</code> is <code>true</code>,
165    * a resource is {@link org.eclipse.emf.ecore.resource.impl.ResourceSetImpl#demandCreateResource created} 
166    * and that resource becomes the result.
167    * If <code>loadOnDemand</code> is <code>true</code>
168    * and the result resource is not {@link Resource#isLoaded loaded}, 
169    * it will be {@link org.eclipse.emf.ecore.resource.impl.ResourceSetImpl#demandLoad loaded} before it is returned.
170    * </p>
171    * @param uri the URI to resolve.
172    * @param loadOnDemand whether to create and load the resource, if it doesn't already exists.
173    * @return the resource resolved by the URI.
174    * @throws RuntimeException if a resource can't be demand created.
175    * @throws org.eclipse.emf.common.util.WrappedException if a problem occurs during demand load.
176    */
177   Resource getResource(URI uri, boolean loadOnDemand);
178 
179   /**
180    * Creates a new resource, of the appropriate type, and returns it.
181    * <p>
182    * It delegates to the resource factory {@link #getResourceFactoryRegistry registry} 
183    * to determine the {@link Resource.Factory.Registry#getFactory correct} factory,
184    * and then it uses that factory to {@link Resource.Factory#createResource create} the resource
185    * and add it to the {@link #getResources contents}.
186    * If there is no registered factory, <code>null</code> will be returned;
187    * when running within Eclipse,
188    * a default XMI factory will be registered,
189    * and this will never return <code>null</code>.
190    * </p>
191    * @param uri the URI of the resource to create.
192    * @return a new resource, or <code>null</code> if no factory is registered.
193    */
194   Resource createResource(URI uri);
195 
196   /**
197    * Returns the registry used for creating a resource of the appropriate type.
198    * <p>
199    * An implementation will typically provide a registry that delegates to
200    * the {@link Resource.Factory.Registry#INSTANCE global} resource factory registry.
201    * As a result, registrations made in this registry are <em>local</em> to this resource set,
202    * i.e., they augment or override those of the global registry.
203    * </p>
204    * @return the registry used for creating a resource of the appropriate type.
205    */
206   Resource.Factory.Registry getResourceFactoryRegistry();
207 
208   /**
209    * Sets the registry used for creating resource of the appropriate type.
210    * @param resourceFactoryRegistry the new registry.
211    */
212   void setResourceFactoryRegistry(Resource.Factory.Registry resourceFactoryRegistry);
213 
214   /**
215    * Returns the converter used to normalize URIs and to open streams.
216    * @return the URI converter.
217    * @see URIConverter
218    * @see URI
219    */
220   URIConverter getURIConverter();
221 
222   /**
223    * Sets the converter used to normalize URIs and to open streams.
224    * @param converter the new converter.
225    * @see URIConverter
226    * @see URI
227    */
228   void setURIConverter(URIConverter converter);
229 
230   /**
231    * Returns the registry used for looking up a package based namespace.
232    * <p>
233    * An implementation will typically provide a registry that delegates to
234    * the {@link org.eclipse.emf.ecore.EPackage.Registry#INSTANCE global} package registry.
235    * As a result, registrations made in this registry are <em>local</em> to this resource set,
236    * i.e., they augment or override those of the global registry.
237    * </p>
238    * @return the registry used for looking up a package based namespace.
239    */
240   EPackage.Registry getPackageRegistry();
241 
242   /**
243    * Set the registry used for looking up a package based namespace.
244    * @param packageRegistry the new registry.
245    */
246   void setPackageRegistry(EPackage.Registry packageRegistry);
247 }
248
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags