KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > pde > core > IModel


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.pde.core;
12 import java.io.InputStream JavaDoc;
13
14 import org.eclipse.core.resources.IResource;
15 import org.eclipse.core.runtime.CoreException;
16 /**
17  * A generic model. Classes that implement this interface are expected to be
18  * able to:
19  * <ul>
20  * <li>Load from an input stream
21  * <li>Reload (reset, load, fire 'world change')
22  * <li>Dispose (clear all the data and reset)
23  * <li>Be associated with a resource (optional)
24  * </ul>
25  * If a model is not created from a workspace resource file, its underlying
26  * resource will be <samp>null </samp>.
27  *
28  * @since 2.0
29  */

30 public interface IModel extends IBaseModel {
31     /**
32      * Returns a string found in the resource bundle associated with this model
33      * for the provided key.
34      *
35      * @param key
36      * the name to use for bundle lookup
37      * @return the string for the key in the resource bundle, or the key itself
38      * if not found
39      */

40     String JavaDoc getResourceString(String JavaDoc key);
41     /**
42      * Returns a workspace resource that this model is created from. Load/reload
43      * operations are not directly connected with the resource (although they
44      * can be). In some cases, models will load from a buffer (an editor
45      * document) rather than a resource. However, the buffer will eventually be
46      * synced up with this resource.
47      * <p>
48      * With the caveat of stepped loading, all other properties of the
49      * underlying resource could be used directly (path, project etc.).
50      *
51      * @return a workspace resource (file) that this model is associated with,
52      * or <samp>null </samp> if the model is not created from a
53      * resource.
54      */

55     public IResource getUnderlyingResource();
56     /**
57      * Tests if this model is loaded and can be used.
58      *
59      * @return <code>true</code> if the model has been loaded
60      */

61     boolean isLoaded();
62     /**
63      * Tests if this model is in sync with the storage object it was loaded
64      * from. Models loaded from resources are in sync if underlying resources
65      * are in sync. Models loaded from files on the file systems are in sync if
66      * the time stamp matches the model time stamp.
67      *
68      * @return <code>true</code> if the model is in sync with the file system.
69      */

70     boolean isInSync();
71     /**
72      * Returns the last modification time stamp. The model itself does not have
73      * the time stamp. It is 'borrowed' from the underlying physical object.
74      *
75      * @return the time stamp of the underlying physical object.
76      */

77     long getTimeStamp();
78     /**
79      * Loads the model directly from an underlying resource. This method does
80      * nothing if this model has no underlying resource or if there is a buffer
81      * stage between the model and the resource.
82      *
83      * @throws CoreException
84      * if errors are encountered during the loading.
85      */

86     public void load() throws CoreException;
87     /**
88      * Loads the model from the provided input stream. This method throws a
89      * CoreException if errors are encountered during the loading. Upon
90      * succesful load, 'isLoaded()' should return <samp>true </samp>.
91      *
92      * @param source
93      * an input stream that should be parsed to load the model
94      * @param outOfSync
95      * if true, time stamp will not be updated to maintain
96      * out-of-sync state of the model.
97      * @throws CoreException
98      * if errors are encountered during the loading.
99      */

100     public void load(InputStream JavaDoc source, boolean outOfSync)
101             throws CoreException;
102     /**
103      * Reload is a version of 'load' operation that has the following steps:
104      * <ul>
105      * <li>Reset the model
106      * <li>Load the model
107      * <li>Fire "world changed" event
108      * </ul>
109      * Reload operation is used when a model that is already in use is
110      * invalidated by a change in the underlying buffer or resource. Since we
111      * don't know the extent of the change, the only safe thing to do is to
112      * reparse the buffer to sync up. The event that is subsequently fired
113      * should be used by listeners to discard all caches and/or fully refresh
114      * views that shows any portion of the model.
115      *
116      * @param source
117      * an input stream that should be parsed to load the model.
118      * @param outOfSync
119      * if true, the timestamp will not be updated to maintain
120      * out-of-sync state of the model.
121      * @throws CoreException
122      * if errors are encountered during the reloading.
123      */

124     public void reload(InputStream JavaDoc source, boolean outOfSync)
125             throws CoreException;
126     /**
127      * Returns whether this model needs to react to changes in source and
128      * reconcile them. Only model instances used in editors need to perform this
129      * task.
130      *
131      * @return <code>true</code> if this is a reconciling model,
132      * <code>false</code> otherwise.
133      */

134     public boolean isReconcilingModel();
135 }
136
Popular Tags