public interface Resource extends Notifier
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:
org.eclipse.emf.common.notify
,
ResourceImpl
,
Resource.Factory
,
ResourceSet
,
URIConverter
Modifier and Type | Interface and Description |
---|---|
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.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
OPTION_CIPHER
Specify a
URIConverter.Cipher to encrypt and decrypt the resource content. |
static java.lang.String |
OPTION_LINE_DELIMITER
Specify the line delimiter to be used for saving the contents.
|
static java.lang.String |
OPTION_LINE_DELIMITER_UNSPECIFIED
A value for
OPTION_LINE_DELIMITER that can be used only with save(Map)
to specify that the appropriate line delimiter be determined from the line delimiter property
of the content description . |
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
|
static int |
RESOURCE__WARNINGS
The
getWarnings() feature ID . |
Modifier and Type | Method and Description |
---|---|
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()
|
eAdapters, eDeliver, eNotify, eSetDeliver
static final int RESOURCE__RESOURCE_SET
getResourceSet()
feature ID
.static final int RESOURCE__URI
static final int RESOURCE__CONTENTS
getContents()
feature ID
.static final int RESOURCE__IS_MODIFIED
isModified()
feature ID
.static final int RESOURCE__IS_LOADED
isLoaded()
feature ID
.static final int RESOURCE__IS_TRACKING_MODIFICATION
isTrackingModification()
feature ID
.static final int RESOURCE__ERRORS
getErrors()
feature ID
.static final int RESOURCE__WARNINGS
getWarnings()
feature ID
.static final int RESOURCE__TIME_STAMP
getTimeStamp()
feature ID
.static final java.lang.String OPTION_CIPHER
URIConverter.Cipher
to encrypt and decrypt the resource content.static final java.lang.String OPTION_ZIP
static final java.lang.String OPTION_SAVE_ONLY_IF_CHANGED
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
.static final java.lang.String OPTION_SAVE_ONLY_IF_CHANGED_MEMORY_BUFFER
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.static final java.lang.String OPTION_SAVE_ONLY_IF_CHANGED_FILE_BUFFER
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.static final java.lang.String OPTION_LINE_DELIMITER
OPTION_LINE_DELIMITER_UNSPECIFIED
,
Constant Field Valuesstatic final java.lang.String OPTION_LINE_DELIMITER_UNSPECIFIED
OPTION_LINE_DELIMITER
that can be used only with save(Map)
to specify that the appropriate line delimiter be determined from the line delimiter property
of the content description
.ResourceSet getResourceSet()
resources
, i.e., the contents, of that resource set.
This reference can only be modified by altering the contents of the resource set directly.
null
if there isn't one.EObject.eContainer()
,
EObject.eResource()
,
ResourceSet.getResources()
URI getURI()
absolute
and hierarchical
;
document-relative references will not be serialized and will not be resolved
,
if this is not the case.null
if there isn't one.setURI(URI)
,
URI.isRelative()
,
URI.isHierarchical()
void setURI(URI uri)
uri
- the new URI.getURI()
long getTimeStamp()
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.setTimeStamp(long)
void setTimeStamp(long timeStamp)
time stamp
.
The time stamp is typically set indirectly via other operations on the resource
such as loading
and saving
.timeStamp
- the new value of the time stamp.getTimeStamp()
,
RESOURCE__TIME_STAMP
EList<EObject> getContents()
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
.
TreeIterator<EObject> getAllContents()
direct contents
and indirect contents of this resource.EObject.eAllContents()
,
ResourceSet.getAllContents()
,
EcoreUtil.getAllContents(Resource, boolean)
java.lang.String getURIFragment(EObject eObject)
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
.
eObject
- the object to identify.fragment
for the object.getEObject(String)
,
InternalEObject.eURIFragmentSegment(org.eclipse.emf.ecore.EStructuralFeature, EObject)
EObject getEObject(java.lang.String uriFragment)
fragment
.
The fragment encoding will typically be that produced by getURIFragment
.
uriFragment
- the fragment to resolve.null
if it can't be resolved.WrappedException
- if a problem occurs navigating the fragment.getURIFragment(EObject)
,
ResourceSet.getEObject(URI, boolean)
,
EcoreUtil.resolve(EObject, ResourceSet)
,
InternalEObject.eObjectForURIFragmentSegment(String)
void save(java.util.Map<?,?> options) throws java.io.IOException
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)
.
options
- the save options.java.io.IOException
save(OutputStream, Map)
void load(java.util.Map<?,?> options) throws java.io.IOException
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.
options
- the load options.java.io.IOException
load(InputStream, Map)
void save(java.io.OutputStream outputStream, java.util.Map<?,?> options) throws java.io.IOException
Usually, save(Map)
is called directly and it calls this.
outputStream
- the streamoptions
- the save options.java.io.IOException
save(Map)
,
load(InputStream, Map)
void load(java.io.InputStream inputStream, java.util.Map<?,?> options) throws java.io.IOException
Usually, load(Map)
is called directly and it calls this.
inputStream
- the streamoptions
- the load options.java.io.IOException
load(Map)
,
save(OutputStream, Map)
boolean isTrackingModification()
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.
void setTrackingModification(boolean isTrackingModification)
Calling this method is expensive because it walks the content tree
to add or remove adapters.
isTrackingModification
- whether modification tracking is to be enabled.boolean isModified()
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.
setModified(boolean)
void setModified(boolean isModified)
A resource is automatically set to be unmodified after it is loaded or saved.
Automatic
modification tracking typically calls this directly.
isModified
- whether this resource has been modified.isModified()
boolean isLoaded()
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.
void unload()
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
.
java.io.IOException
EList<Resource.Diagnostic> getErrors()
Resource.Diagnostic
.
These will typically be produced as the resource is loaded
.
load(Map)
EList<Resource.Diagnostic> getWarnings()
Resource.Diagnostic
.
These will typically be produced as the resource is loaded
.
load(Map)