org.eclipse.emf.ecore.resource
Interface Resource

All Superinterfaces:

Notifier

All Known Subinterfaces:

Ecore2XMLResource, Resource.Internal, XMIResource, XMLResource

All Known Implementing Classes:

BinaryResourceImpl, Ecore2EcoreResourceImpl, Ecore2XMLResourceImpl, EMOFResourceImpl, GenericXMLResourceImpl, ResourceImpl, XMIResourceImpl, XMLResourceImpl, XMLTypeResourceImpl

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 must extend the default implementation, or one of its derived classes, since methods can and will be added to this API.

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

• getResourceSet()
• getURI()
• getTimeStamp()
• getContents()
• isModified()
• isLoaded()
• isTrackingModification()
• getErrors()
• getWarnings()

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 java.lang.String	OPTION_CIPHER Specify a URIConverter.Cipher to encrypt and decrypt the resource content.
static java.lang.String	OPTION_SAVE_ONLY_IF_CHANGED A save option that can be used only with save(Map) to specify that the resource is to be saved only if the new contents are different from actual contents; this compares the bytes in the backing store against the new bytes that would be saved.
static java.lang.String	OPTION_SAVE_ONLY_IF_CHANGED_FILE_BUFFER A value for OPTION_SAVE_ONLY_IF_CHANGED to specify that a file buffer should be used to compare the new contents with the actual contents.
static java.lang.String	OPTION_SAVE_ONLY_IF_CHANGED_MEMORY_BUFFER A value for OPTION_SAVE_ONLY_IF_CHANGED to specify that an in-memory buffer should be used to compare the new contents with the actual contents.
static java.lang.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__TIME_STAMP The getTimeStamp() feature ID.
static int	RESOURCE__URI The getURI() feature ID.
static int	RESOURCE__WARNINGS The getWarnings() feature ID.

Method Summary

void	delete(java.util.Map<?,?> options) deletes the resource using the specified options, unloads it, and then removes it from the containing resource set.
TreeIterator<EObject>	getAllContents() Returns a tree iterator that iterates over all the direct contents and indirect contents of this resource.
EList<EObject>	getContents() Returns the list of the direct content objects; each is of type EObject.
EObject	getEObject(java.lang.String uriFragment) Returns the resolved object for the given URI fragment.
EList<Resource.Diagnostic>	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.
long	getTimeStamp() Returns the cached value of the time stamp when this resource was last loaded or saved, or NULL_TIME_STAMP if the resource is not loaded and the time stamp has not been set.
URI	getURI() Returns the URI of this resource.
java.lang.String	getURIFragment(EObject eObject) Returns the URI fragment that, when passed to getEObject will return the given object.
EList<Resource.Diagnostic>	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(java.io.InputStream inputStream, java.util.Map<?,?> options) Loads the resource from the input stream using the specified options.
void	load(java.util.Map<?,?> options) Loads the resource using the specified options.
void	save(java.util.Map<?,?> options) Saves the resource using the specified options.
void	save(java.io.OutputStream outputStream, java.util.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	setTimeStamp(long timeStamp) Sets the value of the time stamp.
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

static final int RESOURCE__RESOURCE_SET

The getResourceSet() feature ID.

See Also:

Constant Field Values

RESOURCE__URI

static final int RESOURCE__URI

The getURI() feature ID.

See Also:

Constant Field Values

RESOURCE__CONTENTS

static final int RESOURCE__CONTENTS

The getContents() feature ID.

See Also:

Constant Field Values

RESOURCE__IS_MODIFIED

static final int RESOURCE__IS_MODIFIED

The isModified() feature ID.

See Also:

Constant Field Values

RESOURCE__IS_LOADED

static final int RESOURCE__IS_LOADED

The isLoaded() feature ID.

See Also:

Constant Field Values

RESOURCE__IS_TRACKING_MODIFICATION

static final int RESOURCE__IS_TRACKING_MODIFICATION

The isTrackingModification() feature ID.

See Also:

Constant Field Values

RESOURCE__ERRORS

static final int RESOURCE__ERRORS

The getErrors() feature ID.

See Also:

Constant Field Values

RESOURCE__WARNINGS

static final int RESOURCE__WARNINGS

The getWarnings() feature ID.

See Also:

Constant Field Values

RESOURCE__TIME_STAMP

static final int RESOURCE__TIME_STAMP

The getTimeStamp() feature ID.

Since:

2.4

See Also:

Constant Field Values

OPTION_CIPHER

static final java.lang.String OPTION_CIPHER

Specify a URIConverter.Cipher to encrypt and decrypt the resource content.

See Also:

Constant Field Values

OPTION_ZIP

static final java.lang.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

OPTION_SAVE_ONLY_IF_CHANGED

static final java.lang.String OPTION_SAVE_ONLY_IF_CHANGED

A save option that can be used only with save(Map) to specify that the resource is to be saved only if the new contents are different from actual contents; this compares the bytes in the backing store against the new bytes that would be saved. The value on this option can be either null, OPTION_SAVE_ONLY_IF_CHANGED_FILE_BUFFER, or OPTION_SAVE_ONLY_IF_CHANGED_MEMORY_BUFFER.

Since:

2.3

See Also:

Constant Field Values

OPTION_SAVE_ONLY_IF_CHANGED_MEMORY_BUFFER

static final java.lang.String OPTION_SAVE_ONLY_IF_CHANGED_MEMORY_BUFFER

A value for OPTION_SAVE_ONLY_IF_CHANGED to specify that an in-memory buffer should be used to compare the new contents with the actual contents. This will be faster than OPTION_SAVE_ONLY_IF_CHANGED_FILE_BUFFER but will use up more memory.

Since:

2.3

See Also:

Constant Field Values

OPTION_SAVE_ONLY_IF_CHANGED_FILE_BUFFER

static final java.lang.String OPTION_SAVE_ONLY_IF_CHANGED_FILE_BUFFER

A value for OPTION_SAVE_ONLY_IF_CHANGED to specify that a file buffer should be used to compare the new contents with the actual contents. This will be slower than OPTION_SAVE_ONLY_IF_CHANGED_MEMORY_BUFFER but will use up less memory.

Since:

2.3

See Also:

Constant Field Values

Method Detail

getResourceSet

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

See Also:

EObject.eContainer(), EObject.eResource(), ResourceSet.getResources()

getURI

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

See Also:

setURI(URI), URI.isRelative(), URI.isHierarchical()

setURI

void setURI(URI uri)

Sets the URI of this resource.

Parameters:

uri - the new URI.

See Also:

getURI()

getTimeStamp

long getTimeStamp()

Returns the cached value of the time stamp when this resource was last loaded or saved, or NULL_TIME_STAMP if the resource is not loaded and the time stamp has not been set. The return value is represented as the number of milliseconds since the epoch (00:00:00 GMT, January 1, 1970). The returned value may not be the same as the actual time stamp if the resource has been modified via external means since the last load or save.

Since:

2.4

See Also:

setTimeStamp(long)

setTimeStamp

void setTimeStamp(long timeStamp)

Sets the value of the time stamp. The time stamp is typically set indirectly via other operations on the resource such as loading and saving.

Parameters:

timeStamp - the new value of the time stamp.

Since:

2.4

See Also:

getTimeStamp(), RESOURCE__TIME_STAMP

getContents

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

TreeIterator<EObject> 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(Resource, boolean)

getURIFragment

java.lang.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

EObject getEObject(java.lang.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, or null if it can't be resolved.

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

void save(java.util.Map<?,?> options)
          throws java.io.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:

java.io.IOException

See Also:

save(OutputStream, Map)

load

void load(java.util.Map<?,?> options)
          throws java.io.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:

java.io.IOException

See Also:

load(InputStream, Map)

save

void save(java.io.OutputStream outputStream,
          java.util.Map<?,?> options)
          throws java.io.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:

java.io.IOException

See Also:

save(Map), load(InputStream, Map)

load

void load(java.io.InputStream inputStream,
          java.util.Map<?,?> options)
          throws java.io.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:

java.io.IOException

See Also:

load(Map), save(OutputStream, Map)

isTrackingModification

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

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

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

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

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

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.

delete

void delete(java.util.Map<?,?> options)
            throws java.io.IOException

deletes the resource using the specified options, unloads it, and then removes it from the containing resource set.

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 URIConverter.delete(URI, Map) the resource's URI.

Throws:

java.io.IOException

getErrors

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

EList<Resource.Diagnostic> 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)