org.eclipse.emf.ecore.resource
Interface Resource

All Superinterfaces:
Notifier
All Known Subinterfaces:
Ecore2XMLResource, Resource.Internal, XMIResource, XMLResource
All Known Implementing Classes:
Ecore2XMLResourceImpl, EMOFResourceImpl, ResourceImpl, XMIResourceImpl, XMLResourceImpl

public interface Resource
extends Notifier

A persistent document.

A resource of an appropriate type is created by a resource factory; a resource set indirectly creates a resource using such a factory. A resource is typically contained by a resource set, along with related resources. It has a URI representing it's identity and that URI is used to determine where to save and load. It provides modeled contents, in fact, it provides even the tree of modeled contents, as well as diagnostics for errors and other problems. It may be unloaded to discard the contents and the load state can be queried. Modification can be tracked, but it's expensive. The resource will be informed as objects are attached and detached; if needed, it will be able to maintain a map to support getEObject. Structured URI fragments are used rather than IDs, since they are a more general alternative. Clients will typically extend the default implementation, or one of it's derived classes.

A resource produces notification for changes to the value of each of these features:

See Also:
org.eclipse.emf.common.notify, ResourceImpl, Resource.Factory, ResourceSet, URIConverter

Nested Class Summary
static interface Resource.Diagnostic
          A noteworthy issue in a document.
static interface Resource.Factory
          A factory for creating resources.
static interface Resource.Internal
          An internal interface implemented by all resources.
static class Resource.IOWrappedException
          An IO exception that wraps another exception.
 
Field Summary
static String OPTION_CIPHER
          Specify a URIConverter.Cipher to encrypt and decrypt the resource content.
static String OPTION_ZIP
          Specify whether the content of the resource should be zipped during save and unzip during load.
static int RESOURCE__CONTENTS
          The getContents() feature ID.
static int RESOURCE__ERRORS
          The getErrors() feature ID.
static int RESOURCE__IS_LOADED
          The isLoaded() feature ID.
static int RESOURCE__IS_MODIFIED
          The isModified() feature ID.
static int RESOURCE__IS_TRACKING_MODIFICATION
          The isTrackingModification() feature ID.
static int RESOURCE__RESOURCE_SET
          The getResourceSet() feature ID.
static int RESOURCE__URI
          The getURI() feature ID.
static int RESOURCE__WARNINGS
          The getWarnings() feature ID.
 
Method Summary
 TreeIterator getAllContents()
          Returns a tree iterator that iterates over all the direct contents and indirect contents of this resource.
 EList getContents()
          Returns the list of the direct content objects; each is of type EObject.
 EObject getEObject(String uriFragment)
          Returns the resolved object for the given URI fragment.
 EList getErrors()
          Returns a list of the errors in the resource; each error will be of type Resource.Diagnostic.
 ResourceSet getResourceSet()
          Returns the containing resource set.
 URI getURI()
          Returns the URI of this resource.
 String getURIFragment(EObject eObject)
          Returns the URI fragment that, when passed to getEObject will return the given object.
 EList getWarnings()
          Returns a list of the warnings and informational messages in the resource; each warning will be of type Resource.Diagnostic.
 boolean isLoaded()
          Returns whether the resource is loaded.
 boolean isModified()
          Returns whether this resource has been modified.
 boolean isTrackingModification()
          Returns whether modification tracking is enabled.
 void load(InputStream inputStream, Map options)
          Loads the resource from the input stream using the specified options.
 void load(Map options)
          Loads the resource using the specified options.
 void save(Map options)
          Saves the resource using the specified options.
 void save(OutputStream outputStream, Map options)
          Saves the resource to the output stream using the specified options.
 void setModified(boolean isModified)
          Sets whether this resource has been modified.
 void setTrackingModification(boolean isTrackingModification)
          Sets whether modification tracking is enabled.
 void setURI(URI uri)
          Sets the URI of this resource.
 void unload()
          Clears the contents, errors, and warnings of the resource and marks it as unloaded.
 
Methods inherited from interface org.eclipse.emf.common.notify.Notifier
eAdapters, eDeliver, eNotify, eSetDeliver
 

Field Detail

RESOURCE__RESOURCE_SET

public static final int RESOURCE__RESOURCE_SET
The getResourceSet() feature ID.

See Also:
Constant Field Values

RESOURCE__URI

public static final int RESOURCE__URI
The getURI() feature ID.

See Also:
Constant Field Values

RESOURCE__CONTENTS

public static final int RESOURCE__CONTENTS
The getContents() feature ID.

See Also:
Constant Field Values

RESOURCE__IS_MODIFIED

public static final int RESOURCE__IS_MODIFIED
The isModified() feature ID.

See Also:
Constant Field Values

RESOURCE__IS_LOADED

public static final int RESOURCE__IS_LOADED
The isLoaded() feature ID.

See Also:
Constant Field Values

RESOURCE__IS_TRACKING_MODIFICATION

public static final int RESOURCE__IS_TRACKING_MODIFICATION
The isTrackingModification() feature ID.

See Also:
Constant Field Values

RESOURCE__ERRORS

public static final int RESOURCE__ERRORS
The getErrors() feature ID.

See Also:
Constant Field Values

RESOURCE__WARNINGS

public static final int RESOURCE__WARNINGS
The getWarnings() feature ID.

See Also:
Constant Field Values

OPTION_CIPHER

public static final String OPTION_CIPHER
Specify a URIConverter.Cipher to encrypt and decrypt the resource content.

See Also:
Constant Field Values

OPTION_ZIP

public static final String OPTION_ZIP
Specify whether the content of the resource should be zipped during save and unzip during load. The default value is Boolean.FALSE

See Also:
Constant Field Values
Method Detail

getResourceSet

public ResourceSet getResourceSet()
Returns the containing resource set. A resource is contained by a resource set if it appears in the resources, i.e., the contents, of that resource set. This reference can only be modified by altering the contents of the resource set directly.

Returns:
the containing resource set.
See Also:
EObject.eContainer(), EObject.eResource(), ResourceSet.getResources()

getURI

public URI getURI()
Returns the URI of this resource. The URI is normally expected to be absolute and hierarchical; document-relative references will not be serialized and will not be resolved, if this is not the case.

Returns:
the URI of this resource.
See Also:
setURI(URI), URI.isRelative(), URI.isHierarchical()

setURI

public void setURI(URI uri)
Sets the URI of this resource.

Parameters:
uri - the new URI.
See Also:
getURI()

getContents

public EList getContents()
Returns the list of the direct content objects; each is of type EObject.

The contents may be directly modified. Removing an object will have the same effect as EcoreUtil.remove(EObject). Adding an object will remove it from the previous container; it's container will be null and it's resource will the this.

Returns:
the direct content objects.

getAllContents

public TreeIterator getAllContents()
Returns a tree iterator that iterates over all the direct contents and indirect contents of this resource.

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

getURIFragment

public String getURIFragment(EObject eObject)
Returns the URI fragment that, when passed to getEObject will return the given object.

In other words, the following is true for any object contained by a resource:

   Resource resource = eObject.eResource();
   eObject == resource.getEObject(resource.getURIFragment(eObject))
An implementation may choose to use IDs or to use structured URI fragments, as supported by eURIFragmentSegment.

Parameters:
eObject - the object to identify.
Returns:
the URI fragment for the object.
See Also:
getEObject(String), InternalEObject.eURIFragmentSegment(org.eclipse.emf.ecore.EStructuralFeature, EObject)

getEObject

public EObject getEObject(String uriFragment)
Returns the resolved object for the given URI fragment.

The fragment encoding will typically be that produced by getURIFragment.

Parameters:
uriFragment - the fragment to resolve.
Returns:
the resolved object for the given fragment.
Throws:
WrappedException - if a problem occurs navigating the fragment.
See Also:
getURIFragment(EObject), ResourceSet.getEObject(URI, boolean), EcoreUtil.resolve(EObject, ResourceSet), InternalEObject.eObjectForURIFragmentSegment(String)

save

public void save(Map options)
          throws IOException
Saves the resource using the specified options.

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

An implementation typically uses the URI converter of the containing resource set to create an output stream, and then delegates to save(OutputStream, Map).

Parameters:
options - the save options.
Throws:
IOException
See Also:
save(OutputStream, Map)

load

public void load(Map options)
          throws IOException
Loads the resource using the specified options.

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

An implementation typically uses the URI converter of the containing resource set to create an input stream, and then delegates to load(InputStream, Map).

When the load completes, the errors and warnings can be consulted. An implementation will typically deserialize as much of a document as possible while producing diagnostics for any problems that are encountered.

Parameters:
options - the load options.
Throws:
IOException
See Also:
load(InputStream, Map)

save

public void save(OutputStream outputStream,
                 Map options)
          throws IOException
Saves the resource to the output stream using the specified options.

Usually, save(Map) is called directly and it calls this.

Parameters:
outputStream - the stream
options - the save options.
Throws:
IOException
See Also:
save(Map), load(InputStream, Map)

load

public void load(InputStream inputStream,
                 Map options)
          throws IOException
Loads the resource from the input stream using the specified options.

Usually, load(Map) is called directly and it calls this.

Parameters:
inputStream - the stream
options - the load options.
Throws:
IOException
See Also:
load(Map), save(OutputStream, Map)

isTrackingModification

public boolean isTrackingModification()
Returns whether modification tracking is enabled.

If modification tracking is enabled, each object of the resource must be adapted in order to listen for changes. This will make the processing of attached and detached significantly more expensive. as well as all model editing, in general.

Returns:
whether modification tracking is enabled.

setTrackingModification

public void setTrackingModification(boolean isTrackingModification)
Sets whether modification tracking is enabled.

Calling this method is expensive because it walks the content tree to add or remove adapters.

Parameters:
isTrackingModification - whether modification tracking is to be enabled.

isModified

public boolean isModified()
Returns whether this resource has been modified.

A resource is set to be unmodified after it is loaded or saved. Automatic modification tracking is supported, but it is expensive. Moreover, it is a poor fit for a model that supports undoable commands, since an undo looks like a change when it's really exactly the opposite.

Returns:
whether this resource has been modified.
See Also:
setModified(boolean)

setModified

public void setModified(boolean isModified)
Sets whether this resource has been modified.

A resource is automatically set to be unmodified after it is loaded or saved. Automatic modification tracking typically calls this directly.

Parameters:
isModified - whether this resource has been modified.
See Also:
isModified()

isLoaded

public boolean isLoaded()
Returns whether the resource is loaded.

This will be false when the resource is first created and will be set to false, when the resource is unloaded. It will be set to true when the resource is loaded and when contents are first added to a resource that isn't loaded. Calling clear for the contents of a resource that isn't loaded, will set the resource to be loaded; this is the simplest way to create an empty resource that's considered loaded.

Returns:
whether the resource is loaded.

unload

public void unload()
Clears the contents, errors, and warnings of the resource and marks it as unloaded.

It walks the content tree, and sets each content object to be a proxy. The resource will remain in the resource set, and can be subsequently reloaded.


getErrors

public EList getErrors()
Returns a list of the errors in the resource; each error will be of type Resource.Diagnostic.

These will typically be produced as the resource is loaded.

Returns:
a list of the errors in the resource.
See Also:
load(Map)

getWarnings

public EList getWarnings()
Returns a list of the warnings and informational messages in the resource; each warning will be of type Resource.Diagnostic.

These will typically be produced as the resource is loaded.

Returns:
a list of the warnings in the resource.
See Also:
load(Map)

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