org.eclipse.emf.ecore.resource
Interface ResourceSet

All Superinterfaces:
Notifier
All Known Implementing Classes:
ResourceSetImpl

public interface ResourceSet
extends Notifier

A collection of related persistent documents.

A resource set manages a collection of related resources and produces notification for changes to that collection. It provides a tree of contents. A collection of adapter factories supports adapter lookup via registered adapter factory.

A resource can be created or demand loaded into the collection. The registry of resource factories can be configured to create resources of the appropriate type. A proxy can be resolved by the resource set, and may cause the demand load of a resource. Default load options are used during demand load. A URI converter can be configured to normalize URIs for comparison and to monitor access to the backing store.

See Also:
Resource, Resource.Factory, URIConverter, EcoreUtil.getRegisteredAdapter(EObject, Object)

Field Summary
static int RESOURCE_SET__RESOURCES
          The getResources() feature ID.
 
Method Summary
 Resource createResource(URI uri)
          Creates a new resource, of the appropriate type, and returns it.
 EList getAdapterFactories()
          Returns the list of registered AdapterFactory instances.
 TreeIterator getAllContents()
          Returns a tree iterator that iterates over all the direct resources and over the content tree of each.
 EObject getEObject(URI uri, boolean loadOnDemand)
          Returns the object resolved by the URI.
 Map getLoadOptions()
          Returns the options used during demand load.
 EPackage.Registry getPackageRegistry()
          Returns the registry used for looking up a package based namespace.
 Resource getResource(URI uri, boolean loadOnDemand)
          Returns the resource resolved by the URI.
 Resource.Factory.Registry getResourceFactoryRegistry()
          Returns the registry used for creating a resource of the appropriate type.
 EList getResources()
          Returns the direct Resources being managed.
 URIConverter getURIConverter()
          Returns the converter used to normalize URIs and to open streams.
 void setPackageRegistry(EPackage.Registry packageRegistry)
          Set the registry used for looking up a package based namespace.
 void setResourceFactoryRegistry(Resource.Factory.Registry resourceFactoryRegistry)
          Sets the registry used for creating resource of the appropriate type.
 void setURIConverter(URIConverter converter)
          Sets the converter used to normalize URIs and to open streams.
 
Methods inherited from interface org.eclipse.emf.common.notify.Notifier
eAdapters, eDeliver, eNotify, eSetDeliver
 

Field Detail

RESOURCE_SET__RESOURCES

public static final int RESOURCE_SET__RESOURCES
The getResources() feature ID.

See Also:
Constant Field Values
Method Detail

getResources

public EList getResources()
Returns the direct Resources being managed.

A resource added to this list will be contained by this resource set. If it was previously contained by a resource set, it will have been removed.

Returns:
the resources.
See Also:
Resource.getResourceSet()

getAllContents

public TreeIterator getAllContents()
Returns a tree iterator that iterates over all the direct resources and over the content tree of each.

Returns:
a tree iterator that iterates over all contents.
See Also:
EObject.eAllContents(), Resource.getAllContents(), EcoreUtil.getAllContents(java.util.Collection)

getAdapterFactories

public EList getAdapterFactories()
Returns the list of registered AdapterFactory instances.

One style of adapter lookup supported by EMF is via registered adapter factories. Since these factories are accessible to any fully contained object via

  eObject.eResource().getResourceSet().getAdapterFactories()
they can be used to create adapters on demand, without going to the factory first.

Returns:
the list of adapter factories.
See Also:
EcoreUtil.getRegisteredAdapter(EObject, Object), AdapterFactory.adapt(Notifier, Object)

getLoadOptions

public Map getLoadOptions()
Returns the options used during demand load.

Options are handled generically as feature-to-setting entries. They are passed to the resource when it is deserialized. A resource will ignore options it doesn't recognize. The options could even include things like an Eclipse progress monitor...

Returns:
the options used during demand load.
See Also:
Resource.load(Map)

getEObject

public EObject getEObject(URI uri,
                          boolean loadOnDemand)
Returns the object resolved by the URI.

Every object contained by a resource (or that is a proxy) has a corresponding URI that resolves to the object. So for any object contained by a resource, the following is true.

   eObject == eObject.eResource().getResourceSet().getEObject(EcoreUtil.getURI(eObject), false)

The URI without the fragment, is used to resolve a resource. If the resource resolves, the fragment is used to resolve the object.

Parameters:
uri - the URI to resolve.
loadOnDemand - whether to create and load the resource, if it doesn't already exists.
Returns:
the object resolved by the URI.
Throws:
RuntimeException - if a resource can't be demand created.
WrappedException - if a problem occurs during demand load.
See Also:
Resource.getEObject(String), getResource(URI, boolean), EcoreUtil.getURI(EObject)

getResource

public Resource getResource(URI uri,
                            boolean loadOnDemand)
Returns the resource resolved by the URI.

A resource set is expected to implement the following strategy in order to resolve the given URI to a resource. First it uses it's URI converter to normalize the URI and then to compare it with the normalized URI of each resource; if it finds a match, that resource becomes the result. Failing that, it delegates to allow the URI to be resolved elsewhere. For example, the package registry is used to resolve the namespace URI of a package to the static instance of that package. So the important point is that an arbitrary implementation may resolve the URI to any resource, not necessarily to one contained by this particular resource set. If the delegation step fails to provide a result, and if loadOnDemand is true, a resource is created and that resource becomes the result. If loadOnDemand is true and the result resource is not loaded, it will be loaded before it is returned.

Parameters:
uri - the URI to resolve.
loadOnDemand - whether to create and load the resource, if it doesn't already exists.
Returns:
the resource resolved by the URI.
Throws:
RuntimeException - if a resource can't be demand created.
WrappedException - if a problem occurs during demand load.

createResource

public Resource createResource(URI uri)
Creates a new resource, of the appropriate type, and returns it.

It delegates to the resource factory registry to determine the correct factory, and then it uses that factory to create the resource and add it to the contents. If there is no registered factory, null will be returned; when running within Eclipse, a default XMI factory will be registered, and this will never return null.

Parameters:
uri - the URI of the resource to create.
Returns:
a new resource, or null if no factory is registered.

getResourceFactoryRegistry

public Resource.Factory.Registry getResourceFactoryRegistry()
Returns the registry used for creating a resource of the appropriate type.

An implementation will typically provide a registry that delegates to the global resource factory registry. As a result, registrations made in this registry are local to this resource set, i.e., they augment or override those of the global registry.

Returns:
the registry used for creating a resource of the appropriate type.

setResourceFactoryRegistry

public void setResourceFactoryRegistry(Resource.Factory.Registry resourceFactoryRegistry)
Sets the registry used for creating resource of the appropriate type.

Parameters:
resourceFactoryRegistry - the new registry.

getURIConverter

public URIConverter getURIConverter()
Returns the converter used to normalize URIs and to open streams.

Returns:
the URI converter.
See Also:
URIConverter, URI

setURIConverter

public void setURIConverter(URIConverter converter)
Sets the converter used to normalize URIs and to open streams.

Parameters:
converter - the new converter.
See Also:
URIConverter, URI

getPackageRegistry

public EPackage.Registry getPackageRegistry()
Returns the registry used for looking up a package based namespace.

An implementation will typically provide a registry that delegates to the global package registry. As a result, registrations made in this registry are local to this resource set, i.e., they augment or override those of the global registry.

Returns:
the registry used for looking up a package based namespace.

setPackageRegistry

public void setPackageRegistry(EPackage.Registry packageRegistry)
Set the registry used for looking up a package based namespace.

Parameters:
packageRegistry - the new registry.

Copyright 2001-2006 IBM Corporation and others.
All Rights Reserved.