Java > Open Source Codes > org > eclipse > emf > ecore > resource > Resource


1 /**
2  * <copyright>
3  *
4  * Copyright (c) 2002-2004 IBM Corporation and others.
5  * All rights reserved. This program and the accompanying materials
6  * are made available under the terms of the Eclipse Public License v1.0
7  * which accompanies this distribution, and is available at
8  * http://www.eclipse.org/legal/epl-v10.html
9  *
10  * Contributors:
11  * IBM - Initial API and implementation
12  *
13  * </copyright>
14  *
15  * $Id: Resource.java,v 1.3 2005/06/08 06:20:10 nickb Exp $
16  */
17 package org.eclipse.emf.ecore.resource;
18
19
20 import java.io.IOException ;
21 import java.io.InputStream ;
22 import java.io.OutputStream ;
23 import java.io.PrintStream ;
24 import java.io.PrintWriter ;
25 import java.util.Map ;
26
27 import org.eclipse.emf.common.notify.NotificationChain;
28 import org.eclipse.emf.common.notify.Notifier;
29 import org.eclipse.emf.common.util.EList;
30 import org.eclipse.emf.common.util.TreeIterator;
31 import org.eclipse.emf.common.util.URI;
32 import org.eclipse.emf.ecore.EObject;
33 import org.eclipse.emf.ecore.resource.impl.ResourceFactoryRegistryImpl;
34
35
36 /**
37  * A persistent document.
38  * <p>
39  * A resource of an appropriate type is {@link Factory#createResource created} by a resource factory;
40  * a resource set indirectly {@link ResourceSet#createResource creates} a resource using such a factory.
41  * A resource is typically {@link #getResourceSet contained} by a resource set,
42  * along with related resources.
43  * It has a {@link #getURI URI} representing it's identity
44  * and that URI is {@link org.eclipse.emf.ecore.resource.URIConverter used}
45  * to determine where to {@link #save(Map) save} and {@link #load(Map) load}.
46  * It provides modeled {@link #getContents contents},
47  * in fact, it provides even the {@link #getAllContents tree} of modeled contents,
48  * as well as {@link Diagnostic diagnostics} for {@link #getErrors errors} and {@link #getWarnings other} problems.
49  * It may be {@link #unload unloaded} to discard the contents and the load state can be {@link #isLoaded queried}.
50  * {@link #isModified Modification} can be {@link #isTrackingModification tracked}, but it's expensive.
51  * The resource will be informed
52  * as objects are {@link Resource.Internal#attached attached} and {@link Resource.Internal#detached detached};
53  * if needed, it will be able to maintain a map to support {@link #getEObject getEObject}.
54  * Structured URI {@link #getURIFragment fragments} are used rather than IDs, since they are a more general alternative.
55  * Clients will typically extend the default {@link org.eclipse.emf.ecore.resource.impl.ResourceImpl implementation},
56  * or one of it's derived classes.
57  * </p>
58  * <p>
59  * A resource produces notification for changes to the value of each of these features:
60  * <ul>
61  * <li>{@link #getResourceSet}</li>
62  * <li>{@link #getURI}</li>
63  * <li>{@link #getContents}</li>
64  * <li>{@link #isModified}</li>
65  * <li>{@link #isLoaded}</li>
66  * <li>{@link #isTrackingModification}</li>
67  * <li>{@link #getErrors}</li>
68  * <li>{@link #getWarnings}</li>
69  * </ul>
70  * </p>
71  * <p>
72  * </p>
73  * @see org.eclipse.emf.common.notify
74  * @see org.eclipse.emf.ecore.resource.impl.ResourceImpl
75  * @see Factory
76  * @see ResourceSet
77  * @see URIConverter
78  */
79 public interface Resource extends Notifier
80 {
81   /**
82    * The {@link #getResourceSet} feature {@link org.eclipse.emf.common.notify.Notification#getFeatureID ID}.
83    */
84   int RESOURCE__RESOURCE_SET = 0;
85
86   /**
87    * The {@link #getURI} feature {@link org.eclipse.emf.common.notify.Notification#getFeatureID ID}.
88    */
89   int RESOURCE__URI = 1;
90
91   /**
92    * The {@link #getContents} feature {@link org.eclipse.emf.common.notify.Notification#getFeatureID ID}.
93    */
94   int RESOURCE__CONTENTS = 2;
95
96   /**
97    * The {@link #isModified} feature {@link org.eclipse.emf.common.notify.Notification#getFeatureID ID}.
98    */
99   int RESOURCE__IS_MODIFIED = 3;
100
101   /**
102    * The {@link #isLoaded} feature {@link org.eclipse.emf.common.notify.Notification#getFeatureID ID}.
103    */
104   int RESOURCE__IS_LOADED = 4;
105
106   /**
107    * The {@link #isTrackingModification} feature {@link org.eclipse.emf.common.notify.Notification#getFeatureID ID}.
108    */
109   int RESOURCE__IS_TRACKING_MODIFICATION = 5;
110
111   /**
112    * The {@link #getErrors} feature {@link org.eclipse.emf.common.notify.Notification#getFeatureID ID}.
113    */
114   int RESOURCE__ERRORS = 6;
115
116   /**
117    * The {@link #getWarnings} feature {@link org.eclipse.emf.common.notify.Notification#getFeatureID ID}.
118    */
119   int RESOURCE__WARNINGS = 7;
120
121   /**
122    * Returns the containing resource set.
123    * A resource is contained by a resource set
124    * if it appears in the {@link ResourceSet#getResources resources}, i.e., the contents, of that resource set.
125    * This reference can only be modified by altering the contents of the resource set directly.
126    * </p>
127    * @return the containing resource set.
128    * @see EObject#eContainer
129    * @see EObject#eResource
130    * @see ResourceSet#getResources
131    */
132   ResourceSet getResourceSet();
133
134   /**
135    * Returns the URI of this resource.
136    * The URI is normally expected to be {@link URI#isRelative absolute} and {@link URI#isHierarchical hierarchical};
137    * document-relative references will not be serialized and will not be {@link URI#resolve resolved},
138    * if this is not the case.
139    * @return the URI of this resource.
140    * @see #setURI(URI)
141    * @see URI#isRelative
142    * @see URI#isHierarchical
143    */
144   URI getURI();
145
146   /**
147    * Sets the URI of this resource.
148    * @param uri the new URI.
149    * @see #getURI
150    */
151   void setURI(URI uri);
152
153   /**
154    * Returns the list of the direct content objects;
155    * each is of type {@link EObject}.
156    * <p>
157    * The contents may be directly modified.
158    * Removing an object will have the same effect as
159    * {@link org.eclipse.emf.ecore.util.EcoreUtil#remove(EObject) EcoreUtil.remove(EObject)}.
160    * Adding an object will remove it from the previous container;
161    * it's {@link EObject#eContainer container} will be <code>null</code>
162    * and it's {@link EObject#eResource resource} will the <code>this</code>.
163    * </p>
164    * @return the direct content objects.
165    */
166   EList getContents();
167
168   /**
169    * Returns a tree iterator that iterates over all the {@link #getContents direct contents} and indirect contents of this resource.
170    * @return a tree iterator that iterates over all contents.
171    * @see EObject#eAllContents
172    * @see ResourceSet#getAllContents
173    * @see org.eclipse.emf.ecore.util.EcoreUtil#getAllContents
174    */
175   TreeIterator getAllContents();
176
177   /**
178    * Returns the URI {@link URI#fragment fragment} that,
179    * when passed to {@link #getEObject getEObject} will return the given object.
180    * <p>
181    * In other words,
182    * the following is <code>true</code> for any object contained by a resource:
183    *<pre>
184    * Resource resource = eObject.eResource();
185    * eObject == resource.getEObject(resource.getURIFragment(eObject))
186    *</pre>
187    * An implementation may choose to use IDs
188    * or to use structured URI fragments, as supported by
189    * {@link org.eclipse.emf.ecore.InternalEObject#eURIFragmentSegment eURIFragmentSegment}.
190    * </p>
191    * @param eObject the object to identify.
192    * @return the URI {@link URI#fragment fragment} for the object.
193    * @see #getEObject(String)
194    * @see org.eclipse.emf.ecore.InternalEObject#eURIFragmentSegment(org.eclipse.emf.ecore.EStructuralFeature, EObject)
195    */
196   String getURIFragment(EObject eObject);
197
198
199   /**
200    * Returns the resolved object for the given URI {@link URI#fragment fragment}.
201    * <p>
202    * The fragment encoding will typically be that produced by {@link #getURIFragment getURIFragment}.
203    * </p>
204    * @param uriFragment the fragment to resolve.
205    * @return the resolved object for the given fragment.
206    * @see #getURIFragment(EObject)
207    * @see ResourceSet#getEObject(URI, boolean)
208    * @see org.eclipse.emf.ecore.util.EcoreUtil#resolve(EObject, ResourceSet)
209    * @see org.eclipse.emf.ecore.InternalEObject#eObjectForURIFragmentSegment(String)
210    * @throws org.eclipse.emf.common.util.WrappedException if a problem occurs navigating the fragment.
211    */
212   EObject getEObject(String uriFragment);
213
214   /**
215    * Saves the resource using the specified options.
216    * <p>
217    * Options are handled generically as feature-to-setting entries;
218    * the resource will ignore options it doesn't recognize.
219    * The options could even include things like an Eclipse progress monitor...
220    * </p>
221    * <p>
222    * An implementation typically uses the {@link ResourceSet#getURIConverter URI converter}
223    * of the {@link #getResourceSet containing} resource set
224    * to {@link URIConverter#createOutputStream create} an output stream,
225    * and then delegates to {@link #save(OutputStream, Map) save(OutputStream, Map)}.
226    * </p>
227    * @param options the save options.
228    * @see #save(OutputStream, Map)
229    */
230   void save(Map options) throws IOException ;
231
232   /**
233    * Loads the resource using the specified options.
234    * <p>
235    * Options are handled generically as feature-to-setting entries;
236    * the resource will ignore options it doesn't recognize.
237    * The options could even include things like an Eclipse progress monitor...
238    * </p>
239    * <p>
240    * An implementation typically uses the {@link ResourceSet#getURIConverter URI converter}
241    * of the {@link #getResourceSet containing} resource set
242    * to {@link URIConverter#createInputStream create} an input stream,
243    * and then delegates to {@link #load(InputStream, Map) load(InputStream, Map)}.
244    * </p>
245    * <p>
246    * When the load completes, the {@link #getErrors errors} and {@link #getWarnings warnings} can be consulted.
247    * An implementation will typically deserialize as much of a document as possible
248    * while producing diagnostics for any problems that are encountered.
249    * </p>
250    * @param options the load options.
251    * @see #load(InputStream, Map)
252    */
253   void load(Map options) throws IOException ;
254
255   /**
256    * Saves the resource to the output stream using the specified options.
257    * <p>
258    * Usually, {@link #save(Map) save(Map)} is called directly and it calls this.
259    * </p>
260    * @param outputStream the stream
261    * @param options the save options.
262    * @see #save(Map)
263    * @see #load(InputStream, Map)
264    */
265   void save(OutputStream outputStream, Map options) throws IOException ;
266
267   /**
268    * Loads the resource from the input stream using the specified options.
269    * <p>
270    * Usually, {@link #load(Map) load(Map)} is called directly and it calls this.
271    * </p>
272    * @param inputStream the stream
273    * @param options the load options.
274    * @see #load(Map)
275    * @see #save(OutputStream, Map)
276    */
277   void load(InputStream inputStream, Map options) throws IOException ;
278
279   /**
280    * Returns whether modification tracking is enabled.
281    * <p>
282    * If modification tracking is enabled,
283    * each object of the resource must be adapted in order to listen for changes.
284    * This will make the processing of {@link Resource.Internal#attached attached}
285    * and {@link Resource.Internal#detached detached } significantly more expensive.
286    * as well as all model editing, in general.
287    * </p>
288    * @return whether modification tracking is enabled.
289    */
290   boolean isTrackingModification();
291
292   /**
293    * Sets whether modification tracking is enabled.
294    * <p>
295    * Calling this method is expensive because it walks the content {@link #getAllContents tree} to add or remove adapters.
296    * </p>
297    * @param isTrackingModification whether modification tracking is to be enabled.
298    */
299   void setTrackingModification(boolean isTrackingModification);
300
301   /**
302    * Returns whether this resource has been modified.
303    * <p>
304    * A resource is set to be unmodified after it is loaded or saved.
305    * {@link #isTrackingModification Automatic} modification tracking is supported, but it is expensive.
306    * Moreover, it is a poor fit for a model that supports undoable commands,
307    * since an undo looks like a change when it's really exactly the opposite.
308    * </p>
309    * @return whether this resource has been modified.
310    * @see #setModified(boolean)
311    */
312   boolean isModified();
313
314   /**
315    * Sets whether this resource has been modified.
316    * <p>
317    * A resource is automatically set to be unmodified after it is loaded or saved.
318    * {@link #isTrackingModification Automatic} modification tracking typically calls this directly.
319    * </p>
320    * @param isModified whether this resource has been modified.
321    * @see #isModified
322    */
323   void setModified(boolean isModified);
324
325   /**
326    * Returns whether the resource is loaded.
327    * <p>
328    * This will be <code>false</code> when the resource is first {@link ResourceSet#createResource created}
329    * and will be set to <code>false</code>, when the resource is {@link #unload unloaded}.
330    * It will be set to <code>true</code> when the resource is {@link #load(Map) loaded}
331    * and when {@link #getContents contents} are first added to a resource that isn't loaded.
332    * Calling {@link org.eclipse.emf.common.util.BasicEList#clear clear}
333    * for the {@link #getContents contents} of a resource that isn't loaded,
334    * will set the resource to be loaded;
335    * this is the simplest way to create an empty resource that's considered loaded.
336    * </p>
337    * @return whether the resource is loaded.
338    */
339   boolean isLoaded();
340
341   /**
342    * Clears the {@link #getContents contents},
343    * {@link #getErrors errors},
344    * and {@link #getWarnings warnings} of the resource
345    * and {@link #isLoaded marks} it as unloaded.
346    * <p>
347    * It walks the content {@link #getAllContents tree},
348    * and {@link org.eclipse.emf.ecore.InternalEObject#eSetProxyURI sets} each content object to be a proxy.
349    * The resource will remain in the {@link #getResourceSet resource set},
350    * and can be subsequently reloaded.
351    * </p>
352    */
353   void unload();
354
355   /**
356    * Returns a list of the errors in the resource;
357    * each error will be of type {@link org.eclipse.emf.ecore.resource.Resource.Diagnostic}.
358    * <p>
359    * These will typically be produced as the resource is {@link #load(Map) loaded}.
360    * </p>
361    * @return a list of the errors in the resource.
362    * @see #load(Map)
363    */
364   EList getErrors();
365
366   /**
367    * Returns a list of the warnings and informational messages in the resource;
368    * each warning will be of type {@link org.eclipse.emf.ecore.resource.Resource.Diagnostic}.
369    * <p>
370    * These will typically be produced as the resource is {@link #load(Map) loaded}.
371    * </p>
372    * @return a list of the warnings in the resource.
373    * @see #load(Map)
374    */
375   EList getWarnings();
376
377   /**
378    * A noteworthy issue in a document.
379    */
380   interface Diagnostic
381   {
382     /**
383      * Returns a translated message describing the issue.
384      * @return a translated message.
385      */
386     String getMessage();
387
388     /**
389      * Returns the source location of the issue.
390      * This will typically be just the {@link Resource#getURI URI} of the resource containing this diagnostic.
391      * @return the location of the issue.
392      */
393     String getLocation();
394
395     /**
396      * Returns the line location of the issue within the source.
397      * Line <code>1</code> is the first line.
398      * @return the line location of the issue.
399      */
400     int getLine();
401
402     /**
403      * Returns the column location of the issue within the source.
404      * Column <code>1</code> is the first column.
405      * @return the column location of the issue.
406      */
407     int getColumn();
408   }
409
410   /**
411    * A factory for creating resources.
412    * <p>
413    * A factory is implemented to {@link #createResource create} a specialized type of resource
414    * and is typically registered in {@link Resource.Factory.Registry registry}.
415    * </p>
416    * @see ResourceSet#createResource(URI)
417    */
418   interface Factory
419   {
420     /**
421      * Creates a resource with the given URI and returns it.
422      * <p>
423      * Clients will typically not call this directly themselves;
424      * it's called by the resource set to {@link ResourceSet#createResource create} a resource.
425      * </p>
426      * @param uri the URI.
427      * @return a new resource.
428      * @see ResourceSet#createResource(URI)
429      */
430     Resource createResource(URI uri);
431
432     /**
433      * A descriptor used by a resource factory registry to defer factory creation.
434      * <p>
435      * The creation is defered until the factory is {@link Resource.Factory.Registry#getFactory fetched} for the first time.
436      * </p>
437      * @see Resource.Factory.Registry#getFactory(URI)
438      */
439     interface Descriptor
440     {
441       /**
442        * Creates a factory and returns it.
443        * <p>
444        * An implementation may and usually does choose to create only one instance,
445        * which it returns for each call.
446        * </p>
447        * @return a factory.
448        */
449       Factory createFactory();
450     }
451
452     /**
453      * A registry of resource factories.
454      * <p>
455      * A registry implementation will typically delegate to the global instance, which can be used as follows
456      *<pre>
457      * Resource.Factory.Registry.{@link Resource.Factory.Registry#INSTANCE INSTANCE}.getProtocolToFactoryMap().
458      * put("abc", resourceFactoryForURIWithAbcProtocol);
459      * Resource.Factory.Registry.INSTANCE.getExtensionToFactoryMap().
460      * put("xyz", resourceFactoryForURIWithXyzFileExtension);
461      *</pre>
462      * A {@link Resource.Factory.Descriptor descriptor} can be used in place of an actual {@link Resource.Factory factory}
463      * as a value in the map.
464      * It is used for factories registered via
465      * {@link org.eclipse.emf.ecore.plugin.EcorePlugin.Implementation#startup plugin registration}
466      * to ensure delayed plugin load.
467      * </p>
468      * @see ResourceSet#getResourceFactoryRegistry()
469      */
470     interface Registry
471     {
472       /**
473        * Returns the resource factory appropriate for the given URI.
474        * <p>
475        * An implementation will (typically) use
476        * the URI's {@link URI#scheme scheme} to search the {@link #getProtocolToFactoryMap protocol} map
477        * and the URI's {@link URI#fileExtension file extension} to search {@link #getExtensionToFactoryMap extension} map.
478        * It will {@link org.eclipse.emf.ecore.resource.Resource.Factory.Descriptor#createFactory convert}
479        * a resulting descriptor into a factory.
480        * It may choose to provide additional mechanisms and algorithms to determine a factory appropriate for the given URI.
481        * </p>
482        * @param uri the URI.
483        * @return the resource factory appropriate for the given URI.
484        * @see ResourceSet#createResource(URI)
485        */
486       Factory getFactory(URI uri);
487
488       /**
489        * Returns a map from {@link URI#scheme protocol} to
490        * {@link org.eclipse.emf.ecore.resource.Resource.Factory}
491        * or {@link org.eclipse.emf.ecore.resource.Resource.Factory.Descriptor}.
492        * @return the protocol map.
493        */
494       Map getProtocolToFactoryMap();
495
496       /**
497        * The file extension <code>"*"</code> that matches any extension.
498        * @see #getExtensionToFactoryMap
499        */
500       String DEFAULT_EXTENSION = "*";
501
502       /**
503        * Returns a map from {@link URI#fileExtension file extension} to
504        * {@link org.eclipse.emf.ecore.resource.Resource.Factory}
505        * or {@link org.eclipse.emf.ecore.resource.Resource.Factory.Descriptor}.
506        * <p>
507        * The {@link #DEFAULT_EXTENSION default} file extension <code>"*"</code>
508        * can be registered as a default that matches any file extension.
509        * This is typically reserved for a default factory that supports XMI serialization;
510        * clients are strongly discouraged from using this feature in the global registry,
511        * particularly those that must function effectively within an Eclipse environment.
512        * </p>
513        * @return the file extension map.
514        * @see #DEFAULT_EXTENSION
515        */
516       Map getExtensionToFactoryMap();
517
518       /**
519        * The global static resource factory registry.
520        * Registrations made in this instance will (typically) be available
521        * for {@link ResourceSet#createResource use} by any resource set.
522        * @see ResourceSet#createResource(URI)
523        * @see ResourceSet#getResourceFactoryRegistry()
524        */
525       Registry INSTANCE = new ResourceFactoryRegistryImpl();
526
527     }
528   }
529
530   /**
531    * An IO exception that wraps another exception.
532    * <p>
533    * Since save and load throw an IO Exception,
534    * it may be convenient for an implementation to wrap another exception
535    * in order to throw it as an IO exception.
536    * </p>
537    */
538   class IOWrappedException extends IOException
539   {
540     /**
541      * The wrapped exception.
542      */
543     protected Exception exception;
544
545     /**
546      * Creates an instance which wraps the given exception.
547      * @param exception the exception to wrap.
548      */
549     public IOWrappedException(Exception exception)
550     {
551       super(exception.getLocalizedMessage());
552       this.exception = exception;
553     }
554
555     /**
556      * Returns the wrapped exception.
557      * @return the wrapped exception.
558      */
559     public Exception getWrappedException()
560     {
561       return exception;
562     }
563
564     /**
565      * Returns the localized message of the wrapped exception.
566      * @return the localized message of the wrapped exception.
567      */
568     public String getLocalizedMessage()
569     {
570       return exception.getLocalizedMessage();
571     }
572
573     /**
574      * Returns the message of the wrapped exception.
575      * @return the message of the wrapped exception.
576      */
577     public String getMessage()
578     {
579       return exception.getMessage();
580     }
581
582     /**
583      * Prints the stack trace of the wrapped exception.
584      */
585     public void printStackTrace()
586     {
587       exception.printStackTrace();
588     }
589
590     /**
591      * Prints the stack trace of the wrapped exception.
592      * @param printStream the stream to print to.
593      */
594     public void printStackTrace(PrintStream printStream)
595     {
596       exception.printStackTrace(printStream);
597     }
598
599     /**
600      * Prints the stack trace of the wrapped exception.
601      * @param printWriter the writer to print to.
602      */
603     public void printStackTrace(PrintWriter printWriter)
604     {
605       exception.printStackTrace(printWriter);
606     }
607   }
608
609   /**
610    * An internal interface implemented by all resources.
611    * <p>
612    * It is used to maintain the referential integrity of
613    * the containment relation between a resource set and a resource.
614    * </p>
615    * @see Resource#getResourceSet
616    * @see ResourceSet#getResources
617    * @see org.eclipse.emf.ecore.InternalEObject#eBasicSetContainer(org.eclipse.emf.ecore.InternalEObject, int, NotificationChain)
618    * InternalEObject.eBasicSetContainer(InternalEObject, int, NotificationChain)
619    */
620   interface Internal extends Resource
621   {
622     /**
623      * Called when the object is attached to this resource,
624      * i.e., when it's {@link EObject#eResource eResource} changes to be this one.
625      * <p>
626      * An implementation that {@link #getEObject resolves} based on IDs
627      * will need to walk the {@link EObject#eAllContents tree} of this object
628      * in order to tabulate an index.
629      * An implementation that needs to {@link #isTrackingModification track modification}
630      * will also need to walk the tree
631      * in order to add the necessary adapter.
632      * In either of these cases,
633      * editing of containment relations will be significantly more expensive.
634      * </p>
635      * @param eObject the attached object.
636      * @see #detached(EObject)
637      */
638     void attached(EObject eObject);
639
640     /**
641      * Called when the object is detached from this resource,
642      * i.e., when it's {@link EObject#eResource eResource} changes to no longer be this one.
643      * <p>
644      * An implementation that {@link #getEObject resolves} based on IDs
645      * will need to walk the {@link EObject#eAllContents tree} of this object
646      * in order clean up it's index.
647      * An implementation that needs to {@link #isTrackingModification track modification}
648      * will also need to walk the tree
649      * in order to remove the added adapter.
650      * In either of these cases,
651      * editing of containment relations will be significantly more expensive.
652      * </p>
653      * @param eObject the attached object.
654      * @see #attached(EObject)
655      */
656     void detached(EObject eObject);
657
658     /**
659      * Sets the resource to be contained by the given resource set, and returns the notifications this produces.
660      * <p>
661      * If it was previously contained by a resource set, it will have been removed.
662      * </p>
663      * @return the notifications produced.
664      */
665     NotificationChain basicSetResourceSet(ResourceSet resourceSet, NotificationChain notifications);
666   }
667 }
668

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags