org.eclipse.emf.ecore.resource
Interface ResourceSet

All Superinterfaces:
Notifier
All Known Implementing Classes:
AdapterFactoryEditingDomain.AdapterFactoryEditingDomainResourceSet, 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. Clients must extend the default implementation, since methods can and will be added to this API.

See Also:
Resource, Resource.Factory, URIConverter, EcoreUtil.getRegisteredAdapter(EObject, Object), EcoreUtil.getRegisteredAdapter(Resource, 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.
 Resource createResource(URI uri, java.lang.String contentType)
          Creates a new resource, of the appropriate type, and returns it.
 EList<AdapterFactory> getAdapterFactories()
          Returns the list of registered AdapterFactory instances.
 TreeIterator<Notifier> 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.
 java.util.Map<java.lang.Object,java.lang.Object> 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<Resource> 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

static final int RESOURCE_SET__RESOURCES
The getResources() feature ID.

See Also:
Constant Field Values
Method Detail

getResources

EList<Resource> 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

TreeIterator<Notifier> 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(ResourceSet, boolean)

getAdapterFactories

EList<AdapterFactory> 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), EcoreUtil.getRegisteredAdapter(Resource, Object), AdapterFactory.adapt(Notifier, Object)

getLoadOptions

java.util.Map<java.lang.Object,java.lang.Object> 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

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, or null if there isn't one.
Throws:
java.lang.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

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, or null if there isn't one and it's not being demand loaded.
Throws:
java.lang.RuntimeException - if a resource can't be demand created.
WrappedException - if a problem occurs during demand load.

createResource

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

createResource

Resource createResource(URI uri,
                        java.lang.String contentType)
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 adds 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.
contentType - the content type identifier of the URI, or null if no content type should be used during lookup.
Returns:
a new resource, or null if no factory is registered.
Since:
2.4

getResourceFactoryRegistry

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

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

Parameters:
resourceFactoryRegistry - the new registry.

getURIConverter

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

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

setURIConverter

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

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

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

Parameters:
packageRegistry - the new registry.

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