## 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`.

  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.

  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.

  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)`

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