Source code: javax/ide/model/Document.java
1 package javax.ide.model;
2
3 import java.io.IOException;
4 import java.io.Reader;
5
6 import java.net.URI;
7
8 import javax.ide.model.spi.DocumentImpl;
9 import javax.ide.model.spi.ElementImpl;
10 import javax.ide.model.spi.ModelAdapterFactory;
11
12 /**
13 * The <CODE>Document</CODE> interface is implemented by objects that can
14 * be saved and restored. These objects are generally persisted on some
15 * file system and are address using an unique {@link URI}.<p>
16 *
17 * Documents are generally created using the {@link DocumentFactory}. This
18 * ensures that there is always one instance of a document pointed to by
19 * the same {@link URI}.<p>
20 *
21 * The specification defines following types of documents:<p>
22 *
23 * <ul>
24 * <li>{@link javax.ide.model.Project}s: containing user work,<li><p>
25 * <li>{@link javax.ide.model.text.TextDocument}s: encapsulating text based files,<li><p>
26 * <li>{@link javax.ide.model.java.JavaSource}s: encapsulating java files, and <li><p>
27 * <li>{@link javax.ide.model.xml.XMLDocument}s: encapsulating xml files. <li><p>
28 * </ul>
29 *
30 * Extension writers that need to introduce custom document classes, should
31 * extend this class.<p>
32 *
33 * When a new document class is introduced, the <code>DocumentFactory</code>
34 * must be told how to recognize the new document. Extension writers tell
35 * the document factory how to recognize newly introduced document classes
36 * in the extension deployment descriptor.
37 */
38 public class Document extends Element
39 {
40 private URI _uri;
41 private ElementDisplayInfo _displayInfo;
42
43 protected final ElementImpl getElementImpl()
44 {
45 return
46 ModelAdapterFactory.getModelAdapterFactory().getImpl( this );
47 }
48
49 private DocumentImpl getDocumentImpl()
50 {
51 return (DocumentImpl) getElementImpl();
52 }
53
54 /**
55 * Set the display info for this element. This can be used by custom
56 * documents to customize their display in the IDE.
57 *
58 * @param displayInfo the display info for this document. If null, the
59 * IDE will display this element in whatever the default way is standard
60 * for elements of this type.
61 */
62 protected final void setDisplayInfo( ElementDisplayInfo displayInfo )
63 {
64 _displayInfo = displayInfo;
65 }
66
67 public ElementDisplayInfo getDisplayInfo()
68 {
69 return _displayInfo;
70 }
71
72 /**
73 * Returns the {@link URI} that identifies this
74 * <CODE>Document</CODE>. Parts of the IDE will use the value of
75 * this {@link URI} as a hash key for caching UI components for this
76 * <CODE>Document</CODE>. Therefore, {@link URI} uniqueness is
77 * important.
78 *
79 * @return The {@link URI} identifying this <CODE>Document</CODE>.
80 */
81 public final URI getURI()
82 {
83 return _uri;
84 }
85
86 /**
87 * Sets the {@link URI} associated with this <CODE>Document</CODE>.
88 * It is important that the {@link URI} only be changed when the
89 * <CODE>Document</CODE> has just been created or when all caches
90 * keyed on the previous {@link URI} can also be updated.
91 *
92 * @param uri The {@link URI} to set.
93 */
94 public final void setURI( URI uri )
95 {
96 _uri = uri;
97 }
98
99 /**
100 * Returns <CODE>true</CODE> if the object's data has already been
101 * loaded.
102 */
103 public final boolean isOpen()
104 {
105 return getDocumentImpl().isOpen();
106 }
107
108 /**
109 * Returns <CODE>true</CODE> if the document's data has never been
110 * saved.
111 */
112 public final boolean isNew()
113 {
114 return getDocumentImpl().isNew();
115 }
116
117 /**
118 * Opens the <CODE>Document</CODE> and loads any associated data
119 * into the appropriate data structures. This method notifies listeners
120 * if the document is successfully opened.
121 *
122 * @exception IOException if the document cannot be opened.
123 */
124 public final void open() throws IOException
125 {
126 getDocumentImpl().open();
127 }
128
129 /**
130 * Closes the <CODE>Document</CODE> and unloads any associated data.
131 * When this method returns, the state of the <CODE>Document</CODE>
132 * object should be equivalent to when the <CODE>Document</CODE>
133 * object has just been instantiated but not yet opened.
134 *
135 * @exception IOException if the document cannot be closed.
136 */
137 public final void close() throws IOException
138 {
139 getDocumentImpl().close();
140 }
141
142 /**
143 * Saves the contents of the document.
144 */
145 public final void save() throws IOException
146 {
147 getDocumentImpl().save();
148 }
149
150 /**
151 * Returns <CODE>true</CODE> if the document's data has never been
152 * saved.
153 *
154 * @return <CODE>true</CODE> if the document's data has never been
155 * saved.
156 */
157 public final boolean isReadOnly()
158 {
159 return getDocumentImpl().isReadOnly();
160 }
161
162 /**
163 * True if the data in the object has been modified.
164 *
165 * @return <CODE>true</CODE> if the data in the object has been modified.
166 */
167 public final boolean isDirty()
168 {
169 return getDocumentImpl().isDirty();
170 }
171
172 /**
173 * Marks the data with the specified dirty state.
174 *
175 * @param dirty If <CODE>true</CODE>, sets the object as being
176 * dirty; if <CODE>false</CODE>, sets the object as being up-to-date.
177 */
178 public final void markDirty( boolean dirty )
179 {
180 getDocumentImpl().markDirty( dirty );
181 }
182
183 /**
184 * Returns the timestamp associated with the <CODE>Document</CODE>,
185 * which indicates the time at which the document was last modified.
186 * The returned <CODE>long</CODE> is expressed in milliseconds since
187 * 00:00:00 GMT Jan 1, 1970.
188 *
189 * @return the <CODE>Document</CODE>'s time stamp.
190 */
191 public final long getTimestamp()
192 {
193 return getDocumentImpl().getTimestamp();
194 }
195
196 /**
197 * Gets an {@link Reader} that can be used to read the contents
198 * of this object.
199 *
200 * @return an {@link Reader}, or <CODE>null</CODE> if the
201 * document has no contents.
202 *
203 * @exception IOException if a security manager exists and its
204 * <CODE>checkRead</CODE> method denies read access.
205 */
206 public final Reader getReader() throws IOException
207 {
208 return getDocumentImpl().getReader();
209 }
210
211 /**
212 * Add a {@link DocumentListener} to the listener list.
213 * A <code>DocumentEvent</code> will be fired in response modifying
214 * the contents of this document.
215 */
216 public final void addDocumentListener( DocumentListener listener )
217 {
218 getDocumentImpl().addDocumentListener( listener );
219 }
220
221 /**
222 * Removes a {@link DocumentListener} from the listener list.
223 */
224 public final void removeDocumentListener( DocumentListener listener )
225 {
226 getDocumentImpl().removeDocumentListener( listener );
227 }
228
229 //--------------------------------------------------------------------------
230 // Object overrides.
231 //--------------------------------------------------------------------------
232 public final int hashCode()
233 {
234 return 42 + getURI().hashCode();
235 }
236
237 public final boolean equals( Object other )
238 {
239 if ( other == this )
240 {
241 return true;
242 }
243
244 if ( ! super.equals( other ) )
245 {
246 return false;
247 }
248
249 if ( ! ( other instanceof Document ) )
250 {
251 return false;
252 }
253
254 return getURI().equals( ((Document)other).getURI() );
255 }
256
257 //
258 //
259 // /**
260 // * Gets the time when the document was last modified on the file system.
261 // *
262 // * @return The last time the document was modified.
263 // */
264 // protected long refreshTimestamp()
265 // {
266 // _timestamp = VirtualFileSystem.getVirtualFileSystem().lastModified( getURI() );
267 // return _timestamp;
268 //
269 // }
270 //
271 // /**
272 // * Mark the document as opened.
273 // *
274 // * @param value The open state of the document.
275 // */
276 // protected void markOpen( boolean value )
277 // {
278 // synchronized( _lock )
279 // {
280 // _open = value;
281 // }
282 // }
283 //
284 // /**
285 // * Get the current value of the timestamp data member.
286 // *
287 // * @return The current value of the timestamp data member.
288 // */
289 // protected long getTimestampDirectly()
290 // {
291 // return _timestamp;
292 // }
293 //
294 // /**
295 // * Set the current value of the timestamp data member.
296 // *
297 // * @param value The current value of the timestamp data member.
298 // */
299 // protected void setTimestampDirectly( long value )
300 // {
301 // _timestamp = value;
302 // }
303 //
304 // /**
305 // * Get the list of {@link javax.ide.IDEListener} instances. This method will create
306 // * the instances if necessary.
307 // *
308 // * @return A list of {@link javax.ide.IDEListener} instances.
309 // */
310 // protected List getListeners()
311 // {
312 // if ( _listeners == null )
313 // {
314 // _listeners = new ArrayList(0);
315 // }
316 // return _listeners;
317 // }
318 //
319 // /**
320 // * Called when a document is opened.
321 // */
322 // protected void fireDocumentOpened()
323 // {
324 // final List listeners = getListeners();
325 //
326 // for ( int i = listeners.size() - 1; i >= 0; i-- )
327 // {
328 // final DocumentListener listener = (DocumentListener)listeners.get( i );
329 // listener.opened( new DocumentEvent( this ) );
330 // }
331 // }
332 //
333 // /**
334 // * Called when a document is closed.
335 // */
336 // protected void fireDocumentClosed()
337 // {
338 // final List listeners = getListeners();
339 //
340 // for ( int i = listeners.size() - 1; i >= 0; i-- )
341 // {
342 // final DocumentListener listener = (DocumentListener)listeners.get( i );
343 // listener.closed( new DocumentEvent( this ) );
344 // }
345 // }
346 //
347 // /**
348 // * Called when a document is about to be closed.
349 // */
350 // protected void fireDocumentWillBeClosed()
351 // {
352 // final List listeners = getListeners();
353 //
354 // for ( int i = listeners.size() - 1; i >= 0; i-- )
355 // {
356 // final DocumentListener listener = (DocumentListener)listeners.get( i );
357 // listener.willBeClosed( new DocumentEvent( this ) );
358 // }
359 // }
360 //
361 // /**
362 // * Called when a document is about to be saved.
363 // */
364 // protected void fireDocumentWillBeSaved()
365 // {
366 // final List listeners = getListeners();
367 //
368 // for ( int i = listeners.size() - 1; i >= 0; i-- )
369 // {
370 // final DocumentListener listener = (DocumentListener)listeners.get( i );
371 // listener.willBeSaved( new DocumentEvent( this ) );
372 // }
373 // }
374 //
375 // /**
376 // * Called when a document is closed.
377 // */
378 // protected void fireDocumentSaved()
379 // {
380 // final List listeners = getListeners();
381 //
382 // for ( int i = listeners.size() - 1; i >= 0; i-- )
383 // {
384 // final DocumentListener listener = (DocumentListener)listeners.get( i );
385 // listener.saved( new DocumentEvent( this ) );
386 // }
387 // }
388 //
389 // /**
390 // * Called when a document is modified.
391 // */
392 // protected void fireDocumentModified()
393 // {
394 // final List listeners = getListeners();
395 //
396 // for ( int i = listeners.size() - 1; i >= 0; i-- )
397 // {
398 // final DocumentListener listener = (DocumentListener)listeners.get( i );
399 // listener.modified( new DocumentEvent( this ) );
400 // }
401 // }
402 //
403 // /**
404 // * Constructor.
405 // */
406 // protected Document()
407 // {
408 // super();
409 // }
410 }